# @vaebe/ccui 完整文档

> @vaebe/ccui 是 Vue 3 + TypeScript 组件库，视觉对齐 Ant Design v6.3.7。本文件聚合了官网全部组件文档，供 AI agent / LLM 一次性读入，构成代码生成与问答的知识库。
> 站点：https://vaebe.github.io/ccui/
> 仓库：https://github.com/vaebe/ccui

约定：

- 所有组件以 `c-` 前缀使用，如 `<c-button>`、`<c-form-item>`。
- 命令式组件（Message / Notification / Modal）通过 `useMessage()` / `useNotification()` / `useModal()` 等 hook 在 setup 中调用。
- 完整引入：`app.use(ccui)`；按需引入推荐配合 `@vaebe/unplugin-vue-components-ccui` 的 `Vue3CCUIResolver()`。

---

# 简介

`@vaebe/ccui` 是一套基于 **Vue 3 + TypeScript** 的开箱即用组件库，视觉与心智模型对齐 [Ant Design v6](https://ant-design.antgroup.com/)，覆盖通用 / 布局 / 导航 / 数据录入 / 数据展示 / 反馈 / 其他七类、80+ 个组件。

## 设计取向

- **对标而非照搬**：能力覆盖到、迁移成本低，但 React-only 的 API 形态（render props / forwardRef / 静态属性挂子组件等）会全部翻译成 Vue 习惯（slot、`v-model:*`、平铺导出）。详见 [对标原则](https://github.com/vaebe/ccui/blob/main/docs-notes/decisions/benchmark-principles.md)。
- **TypeScript 优先**：完整 `.d.ts` 类型导出，组件 props / events / slots 全量可推导。
- **主题原生 CSS 变量**：SeedToken / MapToken 双层体系，CSS 变量挂 `:root`，切换 `.dark` 类即启用暗色。
- **可访问性**：浮层 / 选择 / 列表 / 录入 等关键组件已完成 ARIA + 键盘审计。
- **国际化**：内置 zhCN / enUS / jaJP / koKR 四个语言包，`ConfigProvider` 切换同步驱动 dayjs locale 按需懒加载。

## 主题 Token

| Token         | 默认值                        |
| ------------- | ----------------------------- |
| colorPrimary  | `#1677ff`                     |
| colorSuccess  | `#52c41a`                     |
| colorWarning  | `#faad14`                     |
| colorError    | `#ff4d4f`                     |
| colorInfo     | `#1677ff`                     |
| borderRadius  | `6px`（large 8 / small 4）    |
| fontSize      | `14px`（行高 1.5714）         |
| controlHeight | `32px`（large 40 / small 24） |

CSS 变量同时挂载到 `:root` 和 SCSS 变量 fallback，可直接通过 `var(--ccui-color-primary)` 等方式消费；切换到 `.dark` 类即可启用暗色主题。完整 token 列表与定制方式见 [ConfigProvider 全局配置](/components/config-provider/)。

## 浏览器支持

跟随 Vue 3 官方支持范围：现代浏览器、不再支持 IE11。

## 下一步

- 安装与引入方式见 [快速开始](/quick-start)
- 给 AI / Copilot 接入 ccui 的索引文件见 [AI 接入](/for-ai)


---

# Affix 固钉

> 文档链接：https://vaebe.github.io/ccui/components/affix/index.html

将页面元素钉在可视区域。常用于侧边目录、操作栏、工具条等需要常驻视野的场景。

## 基本使用

相对顶部 0px 固定，滚动到阈值后元素贴住顶部。下面在一个可滚动容器内演示效果（页面本身带固定导航，直接相对窗口顶部 0px 固定会被导航遮住，故用容器演示）。

:::demo

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

<template>
  <div
    ref="containerRef"
    style="height: 220px; overflow: auto; border: 1px solid var(--ccui-color-border-secondary); border-radius: 4px; padding: 12px; position: relative;"
  >
    <div style="height: 60px; color: var(--ccui-color-text-tertiary)">向下滚动这个容器 ↓</div>
    <c-affix :offset-top="0" :target="() => containerRef">
      <c-button type="primary">固定到顶部 0px</c-button>
    </c-affix>
    <div style="height: 600px; padding-top: 12px; color: var(--ccui-color-text-tertiary)">占位内容，撑开滚动空间……</div>
  </div>
</template>
```

:::

## 偏移量 offsetTop

通过 `offset-top` 设置距顶部固定的距离。多个固定元素错开摆放。

:::demo

```vue
<template>
  <c-affix :offset-top="80">
    <c-button type="primary">距顶 80px</c-button>
  </c-affix>
  <p>向下滚动查看固定效果</p>
</template>
```

:::

## 固定到底部 offsetBottom

`offset-bottom` 把元素固定在视口底部，常用于「返回顶部」、底部操作栏。

:::demo

```vue
<template>
  <c-affix :offset-bottom="20">
    <c-button type="primary">距底 20px</c-button>
  </c-affix>
  <p>滚动直到容器超出视口下边界，按钮会贴在底部</p>
</template>
```

:::

## 监听固定状态变化

通过 `change` 事件感知是否进入/退出固定状态，可联动展示阴影、收起等。

:::demo

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

const fixed = ref(false)

function onChange(val: boolean) {
  fixed.value = val
}
</script>

<template>
  <p>当前是否固定：{{ fixed ? '是' : '否' }}</p>
  <c-affix :offset-top="100" @change="onChange">
    <c-button :type="fixed ? 'primary' : 'default'">{{ fixed ? '已固定到顶部 100px' : '未固定，向下滚动' }}</c-button>
  </c-affix>
</template>
```

:::

## 在滚动容器中

通过 `target` 指定一个可滚动的父容器（CSS 选择器或 DOM 元素返回函数），固钉相对容器边界进行计算。

:::demo

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

<template>
  <div
    ref="containerRef"
    style="
      height: 200px;
      overflow: auto;
      border: 1px solid var(--ccui-color-border-secondary);
      padding: 12px;
      position: relative;
    "
  >
    <div style="height: 80px">先滚动这个容器</div>
    <c-affix :offset-top="0" :target="() => containerRef">
      <c-button type="primary">在容器内固定</c-button>
    </c-affix>
    <div style="height: 600px; padding-top: 12px">
      <p>占位内容用来撑开滚动空间...</p>
      <p>继续滚动...</p>
    </div>
  </div>
</template>
```

:::

## 自定义层级 zIndex

默认 `z-index: 10`；当页面里有 Drawer / Modal（更高 z-index）时按需调高，确保固钉不被遮罩盖住。

:::demo

```vue
<template>
  <c-affix :offset-top="0" :z-index="1100">
    <c-button type="primary">z-index = 1100</c-button>
  </c-affix>
  <p>常见取值：默认 10、悬浮触发器 100、Modal mask 1000、需要盖住 mask 时 1100+</p>
</template>
```

:::

## 多个 Affix 错开

工具栏吸顶 + 二级筛选条吸顶，靠 `offsetTop` 错开高度，构成「双层 sticky」效果。

:::demo

```vue
<template>
  <c-affix :offset-top="0">
    <div style="background: var(--ccui-color-primary); color: var(--ccui-color-text-light-solid); padding: 8px 12px; border-radius: 4px">
      第一层：主导航（offsetTop=0）
    </div>
  </c-affix>
  <c-affix :offset-top="48" style="margin-top: 8px">
    <div style="background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border); padding: 8px 12px; border-radius: 4px">
      第二层：筛选条（offsetTop=48）
    </div>
  </c-affix>
  <p style="margin-top: 12px">向下滚动，两层依次贴住顶部不重叠</p>
</template>
```

:::

## 表格工具栏吸顶

后台管理页常见：表格行很长，工具栏（搜索 / 新建 / 批量操作）始终可达。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const keyword = ref('')
</script>

<template>
  <c-affix :offset-top="0">
    <div
      style="
        background: var(--ccui-color-bg-container);
        padding: 12px;
        border-bottom: 1px solid var(--ccui-color-border-secondary);
        display: flex;
        gap: 8px;
        align-items: center;
      "
    >
      <c-input v-model="keyword" placeholder="搜索订单号" style="width: 200px" />
      <c-button>批量删除</c-button>
      <c-button type="primary">+ 新建订单</c-button>
    </div>
  </c-affix>
  <p style="margin-top: 12px">下方表格略...</p>
</template>
```

:::

## 章节锚点目录

侧边目录 sticky，配合右侧主内容滚动，是长文档 / 商品详情页常用排版。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px; align-items: flex-start">
    <c-affix :offset-top="80" style="width: 160px; flex-shrink: 0">
      <div style="background: var(--ccui-area); border-radius: 6px; padding: 12px">
        <p style="margin: 0 0 8px; color: var(--ccui-color-text-secondary); font-size: 12px">目录</p>
        <a href="#" style="display: block; color: var(--ccui-color-primary); margin: 4px 0">第一章 介绍</a>
        <a href="#" style="display: block; color: var(--ccui-color-primary); margin: 4px 0">第二章 安装</a>
        <a href="#" style="display: block; color: var(--ccui-color-primary); margin: 4px 0">第三章 用法</a>
        <a href="#" style="display: block; color: var(--ccui-color-primary); margin: 4px 0">第四章 进阶</a>
      </div>
    </c-affix>
    <div style="flex: 1">
      <h3>正文区</h3>
      <p>左侧目录会随页面滚动贴到 80px 处保持可见。</p>
    </div>
  </div>
</template>
```

:::

## 容器内 vs 全局对比

并列展示「以 window 为参照」和「以容器为参照」两种模式，便于业务侧理解 `target` 的影响范围。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const boxRef = ref(null)
</script>

<template>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px">
    <div>
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">target = window（默认）</p>
      <c-affix :offset-top="60">
        <c-button>滚整页时贴顶</c-button>
      </c-affix>
    </div>
    <div ref="boxRef" style="height: 160px; overflow: auto; border: 1px solid var(--ccui-color-border-secondary); padding: 8px">
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">target = 本容器</p>
      <c-affix :offset-top="0" :target="() => boxRef">
        <c-button type="primary">只在此盒子内贴顶</c-button>
      </c-affix>
      <div style="height: 400px; padding-top: 12px">滚动此处验证 →</div>
    </div>
  </div>
</template>
```

:::

## API

### Props

| 参数         | 类型                                                           | 默认值      | 说明                                                                            |
| ------------ | -------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- |
| offsetTop    | number                                                         | `0`         | 距离窗口（或目标容器）顶部多少像素后开始固定。`offsetBottom` 未传时启用顶部模式 |
| offsetBottom | number                                                         | `undefined` | 距离窗口（或目标容器）底部多少像素后开始固定。设置该值则忽略 `offsetTop`        |
| target       | `string \| HTMLElement \| () => HTMLElement \| Window \| null` | `window`    | 滚动容器。可传 CSS 选择器、DOM 节点或返回 DOM 节点的函数                        |
| zIndex       | number                                                         | `10`        | 固定时元素的 `z-index`                                                          |

### Events

| 事件名 | 回调签名           | 触发时机                      |
| ------ | ------------------ | ----------------------------- |
| change | `(fixed: boolean)` | 固定状态变化（进入/退出固定） |

## 注意事项

- `c-affix` 内部用一个占位元素保持原始位置和尺寸，固定时把内容切换为 `position: fixed`。所以父容器不要给固钉外层加 `transform`，会让 `position: fixed` 失效。
- 如果固定后宽度异常，请检查父级是否使用 `display: flex` 等会改变子元素宽度计算的布局。


---

# Alert 警告提示

> 文档链接：https://vaebe.github.io/ccui/components/alert/index.html

警告提示，展现需要关注的信息。

## 何时使用

- 当某个页面需要向用户显示警告的信息时。
- 非浮层的静态展现形式，始终展现，不会自动消失，用户可以点击关闭。

## 基本使用

:::demo

```vue
<template>
  <c-alert type="success" message="Success Tips" />
  <br />
  <c-alert type="info" message="Informational Notes" />
  <br />
  <c-alert type="warning" message="Warning" />
  <br />
  <c-alert type="error" message="Error" />
</template>
```

:::

## 含有辅助性文字介绍

:::demo

```vue
<template>
  <c-alert
    type="success"
    message="Success Tips"
    description="Detailed description and advice about successful copywriting."
  />
  <br />
  <c-alert
    type="info"
    message="Informational Notes"
    description="Additional description and information about copywriting."
  />
</template>
```

:::

## 显示图标

:::demo

```vue
<template>
  <c-alert show-icon type="success" message="Success Tips" />
  <br />
  <c-alert show-icon type="info" message="Informational Notes" />
  <br />
  <c-alert show-icon type="warning" message="Warning" />
  <br />
  <c-alert show-icon type="error" message="Error" />
</template>
```

:::

## 可关闭

:::demo

```vue
<script>
export default {
  methods: {
    onClose(e) {
      console.log('alert closed', e)
    },
  },
}
</script>

<template>
  <c-alert closable type="warning" message="Warning Text" @close="onClose" />
</template>
```

:::

## 顶部公告（banner）

`banner` 模式去边框、改背景，常用于页面顶部的全局提示。

:::demo

```vue
<template>
  <c-alert banner type="info" message="系统将于本周日 02:00 - 04:00 进行升级维护，请合理安排时间。" />
  <br />
  <c-alert banner show-icon type="warning" message="您的浏览器版本过低，可能影响部分功能体验。建议升级到最新版。" />
  <br />
  <c-alert banner show-icon type="error" message="账号余额不足，请尽快充值以避免服务中断。" closable />
</template>
```

:::

## 自定义关闭文字

`close-text` 替换默认的 × 按钮，常用于"知道了" / "我已了解"等业务文案。

:::demo

```vue
<template>
  <c-alert
    type="info"
    message="新功能上线：支持批量导出 Excel"
    description="您可以在「订单中心 → 批量操作」中找到该功能。"
    show-icon
    closable
    close-text="知道了"
  />
  <br />
  <c-alert type="warning" message="您正在测试环境" closable close-text="切换到生产" />
</template>
```

:::

## 图标 + 描述完整版

`show-icon` + `description` + `closable` 三者组合是最饱满的提示形式。

:::demo

```vue
<template>
  <c-alert
    show-icon
    closable
    type="success"
    message="同步完成"
    description="共同步 245 条数据，耗时 3.2 秒。详情可查看「同步记录」页。"
  />
  <br />
  <c-alert
    show-icon
    closable
    type="error"
    message="支付失败"
    description="您的银行卡余额不足，订单已暂存。请充值后在「待支付订单」中继续支付，30 分钟内有效。"
  />
</template>
```

:::

## 长内容自动换行

`message` 与 `description` 都会随容器宽度自动换行。

:::demo

```vue
<template>
  <div style="max-width: 480px">
    <c-alert
      show-icon
      type="info"
      message="本月统计周期变更通知"
      description="自 2026 年 5 月起，月度数据统计周期由「自然月 1 日 - 月末」调整为「每月 5 日 - 次月 4 日」。此变更不影响您的历史数据，但会影响下月起的统计报表生成时间。如有疑问请联系您的客户经理或在工单系统中提交问题。"
    />
  </div>
</template>
```

:::

## 表单顶部错误汇总（业务场景）

复杂表单提交失败时，把所有错误项放在顶部 Alert，便于用户快速定位。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const errors = ref(['用户名不能为空', '密码长度至少 8 位', '手机号格式错误'])
const dismissed = ref(false)

function reset() {
  dismissed.value = false
}
</script>

<template>
  <c-button @click="reset" style="margin-bottom: 12px">重置 alert</c-button>
  <c-alert
    v-if="!dismissed && errors.length > 0"
    show-icon
    closable
    type="error"
    :message="`表单有 ${errors.length} 项错误，请修正后重新提交`"
    @close="dismissed = true"
  >
    <template #default>
      <ul style="margin: 8px 0 0; padding-left: 20px">
        <li v-for="e in errors" :key="e" style="color: var(--ccui-color-error)">{{ e }}</li>
      </ul>
    </template>
  </c-alert>
</template>
```

:::

## 行内嵌入卡片

Alert 嵌在卡片或表单内部，作为局部提示。

:::demo

```vue
<template>
  <div style="border: 1px solid var(--ccui-color-border-secondary); border-radius: 8px; padding: 16px; max-width: 480px">
    <h3 style="margin: 0 0 12px">API 接入配置</h3>
    <c-alert show-icon type="warning" message="生产环境密钥泄露将导致严重后果，请妥善保管。" />
    <div style="margin-top: 12px; color: var(--ccui-color-text-secondary); font-size: 13px">App Key：sk-prod-XXXXXXXXXXXX</div>
  </div>
</template>
```

:::

## Alert 参数

| 参数        | 类型                                     | 默认值 | 说明               |
| ----------- | ---------------------------------------- | ------ | ------------------ |
| type        | 'success' / 'info' / 'warning' / 'error' | 'info' | 类型               |
| message     | string                                   | --     | 警告主标题         |
| description | string                                   | --     | 辅助性文字描述     |
| showIcon    | boolean                                  | false  | 是否显示图标       |
| closable    | boolean                                  | false  | 默认显示关闭按钮   |
| closeText   | string                                   | --     | 自定义关闭按钮文本 |
| banner      | boolean                                  | false  | 是否用作顶部公告   |

## Alert 事件

| 事件名 | 参数 | 说明           |
| ------ | ---- | -------------- |
| close  | --   | 关闭按钮被点击 |


---

# Anchor 锚点

> 文档链接：https://vaebe.github.io/ccui/components/anchor/index.html

页面内部跳转导航。点击锚点平滑滚动到对应内容，滚动时自动高亮当前所在区段。

## 基本使用

最简单的用法：传入扁平的 `items` 列表，每项包含 `href`（CSS 选择器形式 `#id`）和 `title`。

:::demo

```vue
<template>
  <div class="anchor-demo">
    <c-anchor
      :items="[
        { href: '#part-1', title: '第一节' },
        { href: '#part-2', title: '第二节' },
        { href: '#part-3', title: '第三节' },
      ]"
      style="width: 160px; flex: none;"
      scroll-container=".anchor-basic"
    />
    <div class="anchor-basic" style="flex: 1; max-height: 280px; overflow: auto;">
      <h3 id="part-1" style="margin-top: 0">第一节</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">第一节内容</p>
      <h3 id="part-2">第二节</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">第二节内容</p>
      <h3 id="part-3">第三节</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">第三节内容</p>
    </div>
  </div>
</template>

<style scoped>
.anchor-demo {
  display: flex;
  gap: 24px;
  border: 1px solid var(--ccui-color-border-secondary);
  border-radius: 8px;
  padding: 12px;
}
</style>
```

:::

## 嵌套层级

`items` 支持 `children` 字段表达父子结构，子级会自动缩进。

:::demo

```vue
<template>
  <div class="anchor-demo">
    <c-anchor :items="items" style="width: 200px; flex: none" scroll-container=".anchor-nested" />
    <div class="anchor-nested" style="flex: 1; max-height: 320px; overflow: auto">
      <h3 id="api">API</h3>
      <p style="height: 100px; background: var(--ccui-area); padding: 12px">概述...</p>
      <h4 id="props">Props</h4>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">props 列表...</p>
      <h4 id="events">Events</h4>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">events 列表...</p>
      <h3 id="faq">FAQ</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">FAQ...</p>
    </div>
  </div>
</template>

<script setup>
const items = [
  {
    href: '#api',
    title: 'API',
    children: [
      { href: '#props', title: 'Props' },
      { href: '#events', title: 'Events' },
    ],
  },
  { href: '#faq', title: 'FAQ' },
]
</script>

<style scoped>
.anchor-demo {
  display: flex;
  gap: 24px;
  border: 1px solid var(--ccui-color-border-secondary);
  border-radius: 8px;
  padding: 12px;
}
</style>
```

:::

## 监听变化

监听 `change` 事件可在锚点切换时触发联动逻辑（如埋点、菜单同步）。

:::demo

```vue
<template>
  <div class="anchor-demo">
    <c-anchor
      :items="[
        { href: '#sec-a', title: 'A 区段' },
        { href: '#sec-b', title: 'B 区段' },
        { href: '#sec-c', title: 'C 区段' },
      ]"
      style="width: 160px; flex: none"
      scroll-container=".anchor-change"
      @change="onChange"
    />
    <div class="anchor-change" style="flex: 1; max-height: 240px; overflow: auto">
      <h3 id="sec-a" style="margin-top: 0">A 区段</h3>
      <p style="height: 180px; background: var(--ccui-area); padding: 12px">A 内容</p>
      <h3 id="sec-b">B 区段</h3>
      <p style="height: 180px; background: var(--ccui-area); padding: 12px">B 内容</p>
      <h3 id="sec-c">C 区段</h3>
      <p style="height: 180px; background: var(--ccui-area); padding: 12px">C 内容</p>
    </div>
  </div>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前激活：{{ active }}</p>
</template>

<script setup>
import { ref } from 'vue'

const active = ref('未滚动')

function onChange(href) {
  active.value = href || '无'
}
</script>

<style scoped>
.anchor-demo {
  display: flex;
  gap: 24px;
  border: 1px solid var(--ccui-color-border-secondary);
  border-radius: 8px;
  padding: 12px;
}
</style>
```

:::

## 调整高亮容差

`bounds` 控制元素到顶部多近时算"激活"（默认 `5`），`offsetTop` 让滚动停留位置距顶部预留空间，避免被 fixed header 遮挡。

:::demo

```vue
<template>
  <div class="anchor-demo">
    <c-anchor
      :items="[
        { href: '#stop-1', title: '段落 1' },
        { href: '#stop-2', title: '段落 2' },
        { href: '#stop-3', title: '段落 3' },
      ]"
      :bounds="40"
      :offset-top="20"
      style="width: 160px; flex: none"
      scroll-container=".anchor-bounds"
    />
    <div class="anchor-bounds" style="flex: 1; max-height: 260px; overflow: auto; position: relative">
      <h3 id="stop-1" style="margin-top: 0">段落 1</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">点击右侧锚点会留 20px 顶部空隙</p>
      <h3 id="stop-2">段落 2</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">提前 40px 切高亮</p>
      <h3 id="stop-3">段落 3</h3>
      <p style="height: 200px; background: var(--ccui-area); padding: 12px">最后一节</p>
    </div>
  </div>
</template>

<style scoped>
.anchor-demo {
  display: flex;
  gap: 24px;
  border: 1px solid var(--ccui-color-border-secondary);
  border-radius: 8px;
  padding: 12px;
}
</style>
```

:::

## 拦截点击

监听 `click` 事件可在跳转前后追加业务逻辑，比如埋点。锚点的默认行为已在内部阻止。

:::demo

```vue
<template>
  <div class="anchor-demo">
    <c-anchor
      :items="[
        { href: '#hook-1', title: '点这里' },
        { href: '#hook-2', title: '或这里' },
      ]"
      style="width: 160px; flex: none"
      scroll-container=".anchor-click"
      @click="onClick"
    />
    <div class="anchor-click" style="flex: 1; max-height: 240px; overflow: auto">
      <h3 id="hook-1" style="margin-top: 0">区段 1</h3>
      <p style="height: 180px; background: var(--ccui-area); padding: 12px">内容</p>
      <h3 id="hook-2">区段 2</h3>
      <p style="height: 180px; background: var(--ccui-area); padding: 12px">内容</p>
    </div>
  </div>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近点击：{{ lastClicked || '（无）' }}</p>
</template>

<script setup>
import { ref } from 'vue'

const lastClicked = ref('')

function onClick(_e, link) {
  lastClicked.value = link.title
}
</script>

<style scoped>
.anchor-demo {
  display: flex;
  gap: 24px;
  border: 1px solid var(--ccui-color-border-secondary);
  border-radius: 8px;
  padding: 12px;
}
</style>
```

:::

## API

### Props

| 参数            | 类型                    | 默认值      | 说明                                       |
| --------------- | ----------------------- | ----------- | ------------------------------------------ |
| items           | `AnchorLink[]`          | `[]`        | 锚点列表，支持 `children` 嵌套             |
| affix           | boolean                 | `true`      | 是否固定（保留外观位）                     |
| bounds          | number                  | `5`         | 元素到顶部小于此距离时视为激活（px）       |
| offsetTop       | number                  | `0`         | 高亮判定与点击滚动统一加的顶部偏移（px）   |
| targetOffset    | number                  | `undefined` | 仅点击滚动用的偏移；未传则回退 `offsetTop` |
| scrollContainer | `string \| HTMLElement` | `window`    | 自定义滚动容器（CSS 选择器或元素引用）     |
| showInkInFixed  | boolean                 | `false`     | 固定时是否仍显示墨色滑块                   |

### AnchorLink

| 字段     | 类型           | 说明                        |
| -------- | -------------- | --------------------------- |
| href     | string         | 必填，目标元素 id（带 `#`） |
| title    | string         | 显示文本，省略则用 href     |
| children | `AnchorLink[]` | 子级锚点（可任意层嵌套）    |

### Events

| 事件名 | 回调签名                                | 触发时机               |
| ------ | --------------------------------------- | ---------------------- |
| change | `(activeHref: string)`                  | 当前激活锚点变化时     |
| click  | `(event: MouseEvent, link: AnchorLink)` | 点击锚点时（已阻默认） |

### Slots

| 名称    | 说明                                                     |
| ------- | -------------------------------------------------------- |
| default | 自定义渲染（不使用 `items`，需自行写带 `href` 的 `<a>`） |


---

# AutoComplete 自动完成

> 文档链接：https://vaebe.github.io/ccui/components/auto-complete/index.html

输入框 + 浮层下拉建议项。区别于 Select：值可以是任意字符串（不限于选项），适合做地址、邮箱、商品名、关键词等"补全"场景。

## 基本使用

`v-model` 绑定输入值，`options` 提供候选项。`options` 可以是 `string[]` 或 `{ value, label, disabled? }[]`。

:::demo

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

const value = ref('')
const options = ['张三', '李四', '王五', '赵六']
</script>

<template>
  <c-auto-complete v-model="value" :options="options" placeholder="输入名字" />
  <div style="margin-top: 8px; color: var(--ccui-color-text-tertiary)">value: {{ value }}</div>
</template>
```

:::

## 自定义选项格式

提供 `{ value, label, disabled }` 形态可以独立控制 value 和显示文本，并禁用某项。

:::demo

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

const value = ref('')
const options = [
  { value: 'gmail.com', label: '@gmail.com' },
  { value: 'outlook.com', label: '@outlook.com' },
  { value: 'qq.com', label: '@qq.com' },
  { value: 'banned.com', label: '@banned.com', disabled: true },
]
</script>

<template>
  <c-auto-complete v-model="value" :options="options" placeholder="输入邮箱后缀" allow-clear />
</template>
```

:::

## 过滤逻辑

`filter-option` 控制候选项过滤：

- `true`（默认）：按 label 包含输入内容（不区分大小写）
- `false`：不过滤，全量展示
- `function`：自定义过滤函数 `(input, option) => boolean`

:::demo

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

const v1 = ref('')
const v2 = ref('')
const v3 = ref('')
const fruits = ['Apple', 'Banana', 'Cherry', 'Durian']

function startsWith(input: string, option: { value: string }) {
  return String(option.value).toLowerCase().startsWith(input.toLowerCase())
}
</script>

<template>
  <c-auto-complete v-model="v1" :options="fruits" placeholder="默认 includes" />
  <c-auto-complete v-model="v2" :options="fruits" :filter-option="false" placeholder="不过滤" />
  <c-auto-complete v-model="v3" :options="fruits" :filter-option="startsWith" placeholder="startsWith 自定义" />
</template>
```

:::

## 大小写敏感

`case-sensitive=true` 让默认过滤区分大小写。

:::demo

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

const value = ref('')
</script>

<template>
  <c-auto-complete v-model="value" :options="['Apple', 'apple', 'APPLE']" case-sensitive placeholder="case-sensitive" />
</template>
```

:::

## 键盘导航

打开浮层后：

- `↑` `↓` 在候选项间移动焦点（自动跳过 disabled 项，到末尾循环回首项）
- `Enter` 选中当前焦点项
- `Esc` 关闭浮层
- 输入字符任意时刻打开浮层

## 三种尺寸

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const v = ref('')
const opts = ['Apple', 'Banana', 'Cherry']
</script>

<template>
  <c-auto-complete v-model="v" :options="opts" size="small" placeholder="small" />
  <c-auto-complete v-model="v" :options="opts" placeholder="default" />
  <c-auto-complete v-model="v" :options="opts" size="large" placeholder="large" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive({ keyword: '' })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { keyword: [{ required: true, message: '请输入关键词', trigger: 'change' }] }
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="keyword" label="关键词" prop="keyword">
      <c-auto-complete v-model="form.keyword" :options="['vue', 'react', 'svelte']" allow-clear />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()">校验</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

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

<template>
  <c-auto-complete v-model="v" :options="['Apple', 'Banana', 'Cherry']" popup-append-to-body />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-auto-complete v-model="value" :variant="variant" :options="opts" placeholder="输入查看补全" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
const opts = ['gmail.com', 'qq.com', '163.com']
</script>
```

:::

## API

### Props

| 参数                     | 类型                                                       | 默认值                    | 说明                                             |
| ------------------------ | ---------------------------------------------------------- | ------------------------- | ------------------------------------------------ |
| modelValue               | string \| number \| null                                   | --                        | 当前输入值，支持 `v-model`                       |
| defaultValue             | string \| number                                           | `''`                      | 非受控初始值                                     |
| options                  | `(string \| number \| { value, label?, disabled? })[]`     | `[]`                      | 候选项；string/number 形态的 label = value       |
| placeholder              | string                                                     | --                        | 占位文案                                         |
| disabled                 | boolean                                                    | `false`                   | 是否禁用                                         |
| allowClear               | boolean                                                    | `false`                   | 显示一键清空按钮                                 |
| size                     | `'small' \| 'default' \| 'large'`                          | `'default'`               | 输入框尺寸                                       |
| status                   | `'' \| 'error' \| 'warning' \| 'success' \| 'validating'`  | `''`                      | 校验状态；置于 `FormItem` 时自动继承             |
| filterOption             | `boolean \| (input, option) => boolean`                    | `true`                    | 过滤逻辑                                         |
| caseSensitive            | boolean                                                    | `false`                   | 是否区分大小写（仅默认 includes 过滤生效）       |
| notFoundContent          | string                                                     | `暂无数据`                | 空数据占位                                       |
| placement                | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`            | 浮层方位                                         |
| popupClassName           | string                                                     | --                        | 浮层根元素自定义 class                           |
| popupAppendToBody        | boolean                                                    | `false`                   | Teleport 到 `document.body`                      |
| getPopupContainer        | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                        | 自定义浮层挂载点，优先级高于 `popupAppendToBody` |
| transitionName           | string                                                     | `ccui-auto-complete-fade` | 浮层过渡名                                       |
| popupMaxHeight           | number                                                     | `256`                     | 浮层最大高度（px）                               |
| defaultActiveFirstOption | boolean                                                    | `false`                   | 打开浮层时是否默认高亮第一项                     |
| backfill                 | boolean                                                    | `false`                   | 键盘导航时是否把高亮项 label 写回 input          |
| searchDebounce           | number                                                     | `0`                       | 搜索防抖延迟（毫秒），`0` 不防抖                 |

### Events

| 事件名            | 回调签名                                                | 触发时机                            |
| ----------------- | ------------------------------------------------------- | ----------------------------------- |
| update:modelValue | `(value: string \| number)`                             | 输入或选中时                        |
| change            | `(value: string \| number)`                             | 同 update:modelValue                |
| search            | `(keyword: string)`                                     | 同 update:modelValue（search 别名） |
| select            | `(value: string \| number, option: AutoCompleteOption)` | 选中候选项时                        |
| open-change       | `(open: boolean)`                                       | 浮层打开 / 关闭时                   |
| focus             | `(e: FocusEvent)`                                       | 输入框聚焦                          |
| blur              | `(e: FocusEvent)`                                       | 输入框失焦                          |

### Slots

| 名称    | 参数                                                                    | 说明                        |
| ------- | ----------------------------------------------------------------------- | --------------------------- |
| option  | `{ option: AutoCompleteOption, index: number }`                         | 自定义单项渲染              |
| trigger | `{ value, onInput, onFocus, onBlur, onKeydown, placeholder, disabled }` | 自定义输入框（如 textarea） |

## 已知限制（未交付）

- **virtual list（候选项虚拟滚动）**：选项 > 1000 时性能未优化，复用 Tree/Select 的 use-virtual-list 留后续。


---

# Avatar 头像

> 文档链接：https://vaebe.github.io/ccui/components/avatar/index.html

代表用户或对象的图标，支持图片、文字、自定义文本。

## 何时使用

- 用户列表、评论、消息中显示用户身份
- 当头像没有图片时，用文字首字母替代

## 基本使用

最简单的方式 —— 传 `name`，组件按规则提取最后/前两个字符。

:::demo

```vue
<template>
  <c-avatar name="张三" />
  &nbsp;
  <c-avatar name="李四" />
  &nbsp;
  <c-avatar name="lihua" />
  &nbsp;
  <c-avatar name="hua li" />
</template>
```

:::

## 不同尺寸

`width` / `height` 控制头像大小（单位 px）。

:::demo

```vue
<template>
  <c-avatar :width="24" :height="24" name="张三" />
  &nbsp;
  <c-avatar :width="32" :height="32" name="张三" />
  &nbsp;
  <c-avatar :width="40" :height="40" name="张三" />
  &nbsp;
  <c-avatar :width="56" :height="56" name="张三" />
</template>
```

:::

## 方形头像

`is-round=false` 渲染为方形，常用于品牌、产品图标。

:::demo

```vue
<template>
  <c-avatar name="张三" :is-round="false" />
  &nbsp;
  <c-avatar :width="40" :height="40" name="hua li" :is-round="false" />
</template>
```

:::

## 图片头像

`img-src` 指定图片地址。图片加载失败时回退到文字。`fit` 控制图片填充方式（同 CSS `object-fit`）。

:::demo

```vue
<template>
  <c-avatar name="刘武" img-src="https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg" />
  &nbsp;
  <c-avatar
    name="刘武"
    fit="contain"
    img-src="https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg"
  />
  &nbsp;
  <c-avatar name="孙六" :is-round="false" img-src="https://invalid-url.example/x.png" />
</template>
```

:::

## 自定义显示文字

`custom-text` 优先级高于 `name`，按原文展示，不做提取。

:::demo

```vue
<template>
  <c-avatar name="李六" custom-text="王二" />
  &nbsp;
  <c-avatar name="anything" custom-text="VIP" />
</template>
```

:::

## 性别配色

`gender` 影响默认背景色。

:::demo

```vue
<template>
  <c-avatar name="女用户" gender="female" />
  &nbsp;
  <c-avatar name="男用户" gender="male" />
  &nbsp;
  <c-avatar name="未知" />
</template>
```

:::

## 单字符 / Emoji 头像

`custom-text` 可放任意字符（emoji / 符号 / 单汉字），适合代表「身份徽章」「机器人 / 系统」「VIP」等。

:::demo

```vue
<template>
  <c-avatar custom-text="👤" gender="male" />
  &nbsp;
  <c-avatar custom-text="🤖" />
  &nbsp;
  <c-avatar custom-text="VIP" gender="female" />
  &nbsp;
  <c-avatar custom-text="管" gender="male" />
  &nbsp;
  <c-avatar custom-text="🎉" :width="48" :height="48" />
</template>
```

:::

## 加载失败回退

`img-src` 加载失败时，自动回退到文字头像（`custom-text` > `name` 的字符提取）。

:::demo

```vue
<template>
  <c-avatar name="张三" img-src="https://invalid-url.example/x.png" />
  &nbsp;
  <c-avatar custom-text="VIP" img-src="https://still-invalid.example/y.jpg" gender="female" />
  &nbsp;
  <c-avatar name="default fallback" img-src="https://broken.example/z.png" :is-round="false" />
</template>
```

:::

## 用户列表场景

头像 + 姓名 + 描述的典型列表项排版。

:::demo

```vue
<template>
  <div style="display: grid; gap: 12px">
    <div
      v-for="u in [
        { name: '张三', gender: 'male', desc: '前端工程师 · 上海' },
        { name: '王芳', gender: 'female', desc: '产品经理 · 北京' },
        { name: 'Alex Liu', desc: 'Tech Lead · 杭州' },
      ]"
      :key="u.name"
      style="display: flex; align-items: center; gap: 12px"
    >
      <c-avatar :name="u.name" :gender="u.gender" />
      <div>
        <div style="font-weight: 600">{{ u.name }}</div>
        <div style="font-size: 12px; color: var(--ccui-color-text-tertiary)">{{ u.desc }}</div>
      </div>
    </div>
  </div>
</template>
```

:::

## 评论头像

评论场景下头像在左、内容在右的典型布局。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px; padding: 12px; border: 1px solid var(--ccui-color-border-secondary); border-radius: 8px">
    <c-avatar name="李四" gender="male" :width="40" :height="40" />
    <div style="flex: 1">
      <div style="font-weight: 600">
        李四 <span style="color: var(--ccui-color-text-tertiary); font-weight: 400; margin-inline-start: 8px; font-size: 12px">2 小时前</span>
      </div>
      <div style="margin-top: 4px; color: var(--ccui-color-text-secondary)">很好用的组件库，文档示例齐全！</div>
    </div>
  </div>
</template>
```

:::

## 显示规则

- 优先级：`imgSrc > customText > name`
- 文字提取规则：
  1. 中文开头：取最后两个字符
  2. 英文开头：取前两个字符
  3. 多个英文名连用：取每个英文名的首字母
  4. 非中英文开头：取前两个字符

## API

### Props

| 参数       | 类型                                                       | 默认值  | 说明                                       |
| ---------- | ---------------------------------------------------------- | ------- | ------------------------------------------ |
| name       | string                                                     | -       | 用于生成头像文字（可不传，回退到默认占位） |
| gender     | `'male' \| 'female' \| string`                             | -       | 影响默认背景色                             |
| width      | number                                                     | `36`    | 宽度（px）                                 |
| height     | number                                                     | `36`    | 高度（px）                                 |
| isRound    | boolean                                                    | `true`  | 是否圆形                                   |
| imgSrc     | string                                                     | -       | 自定义图片                                 |
| customText | string                                                     | -       | 自定义文字（不做提取）                     |
| fit        | `'fill' \| 'contain' \| 'cover' \| 'none' \| 'scale-down'` | `cover` | 图片填充方式                               |


---

# Badge 徽标数

> 文档链接：https://vaebe.github.io/ccui/components/badge/index.html

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

## 何时使用

- 一般出现在通知图标或头像的右上角，用于显示需要处理的消息条数。
- 用于其他需要展示状态的场景。

## 基本使用

:::demo

```vue
<template>
  <c-badge :count="5" class="head-badge">
    <span class="head-example" />
  </c-badge>

  <c-badge :count="0" show-zero class="head-badge">
    <span class="head-example" />
  </c-badge>

  <c-badge :count="99" class="head-badge">
    <span class="head-example" />
  </c-badge>

  <c-badge :count="100" class="head-badge">
    <span class="head-example" />
  </c-badge>

  <c-badge :count="200" :overflow-count="99" class="head-badge">
    <span class="head-example" />
  </c-badge>
</template>

<style>
/* 间距加在 badge 外层；若加在被包裹的 .head-example 上，会把徽标锚点一起推开，
   导致窄徽标（如 0）离右上角有空隙 */
.head-badge {
  margin-right: 16px;
}
.head-example {
  width: 42px;
  height: 42px;
  background: var(--ccui-area);
  border-radius: 4px;
  display: inline-block;
}
</style>
```

:::

## 独立使用

:::demo

```vue
<template>
  <c-badge :count="25" />
  <c-badge :count="4" :style="{ backgroundColor: '#52c41a', marginLeft: '12px' }" />
</template>
```

:::

## 小红点

:::demo

```vue
<template>
  <c-badge dot>
    <span class="head-example" />
  </c-badge>
</template>

<style>
.head-example {
  width: 42px;
  height: 42px;
  background: var(--ccui-area);
  border-radius: 4px;
  display: inline-block;
}
</style>
```

:::

## 状态点

:::demo

```vue
<template>
  <c-badge status="success" text="Success" />
  <br />
  <c-badge status="error" text="Error" />
  <br />
  <c-badge status="default" text="Default" />
  <br />
  <c-badge status="processing" text="Processing" />
  <br />
  <c-badge status="warning" text="Warning" />
</template>
```

:::

## 自定义颜色

`color` 接受任意 CSS 颜色字符串（预设色名 / 十六进制 / rgb 都行）。

:::demo

```vue
<template>
  <c-badge :count="5" color="#fa541c" class="head-badge">
    <span class="head-example" />
  </c-badge>
  <c-badge :count="5" color="#52c41a" class="head-badge">
    <span class="head-example" />
  </c-badge>
  <c-badge :count="5" color="#722ed1" class="head-badge">
    <span class="head-example" />
  </c-badge>
  <c-badge :count="5" color="#13c2c2" class="head-badge">
    <span class="head-example" />
  </c-badge>
</template>

<style>
/* 间距加在 badge 外层，避免推开徽标锚点 */
.head-badge {
  margin-right: 16px;
}
.head-example {
  width: 42px;
  height: 42px;
  background: var(--ccui-area);
  border-radius: 4px;
  display: inline-block;
}
</style>
```

:::

## 偏移设置（offset）

`offset: [x, y]` 调整徽标相对默认位置的偏移量（单位 px）。

:::demo

```vue
<template>
  <c-badge :count="5" class="head-badge">
    <span class="head-example" />
  </c-badge>
  默认 &nbsp;&nbsp;&nbsp;
  <c-badge :count="5" :offset="[-4, 4]" class="head-badge">
    <span class="head-example" />
  </c-badge>
  offset=[-4, 4] &nbsp;&nbsp;&nbsp;
  <c-badge :count="5" :offset="[10, -10]" class="head-badge">
    <span class="head-example" />
  </c-badge>
  offset=[10, -10]
</template>

<style>
/* 间距加在 badge 外层，避免推开徽标锚点 */
.head-badge {
  margin-right: 8px;
}
.head-example {
  width: 42px;
  height: 42px;
  background: var(--ccui-area);
  border-radius: 4px;
  display: inline-block;
}
</style>
```

:::

## 字符串 count（NEW / HOT 标签）

`count` 也接受字符串，常用作产品列表的「NEW / HOT / 限时」角标。

:::demo

```vue
<template>
  <c-badge count="NEW" class="head-badge">
    <span class="head-example-lg" />
  </c-badge>
  <c-badge count="HOT" color="#fa541c" class="head-badge">
    <span class="head-example-lg" />
  </c-badge>
  <c-badge count="限时" color="#722ed1" class="head-badge">
    <span class="head-example-lg" />
  </c-badge>
</template>

<style>
/* 间距加在 badge 外层，避免推开徽标锚点 */
.head-badge {
  margin-right: 16px;
}
.head-example-lg {
  width: 60px;
  height: 60px;
  background: var(--ccui-area);
  border-radius: 4px;
  display: inline-block;
}
</style>
```

:::

## 与 Avatar 组合（消息中心常见）

头像 + 消息数徽标，常见于头部导航的「消息中心 / 通知」按钮。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const count = ref(8)
</script>

<template>
  <c-badge :count="count">
    <c-avatar custom-text="🔔" :width="40" :height="40" />
  </c-badge>
  &nbsp;&nbsp;
  <c-badge dot>
    <c-avatar custom-text="📩" :width="40" :height="40" gender="male" />
  </c-badge>
  <br /><br />
  <c-button @click="count += 1">+1</c-button>
  <c-button style="margin-inline-start: 8px" @click="count = 0">清零</c-button>
</template>
```

:::

## Badge 参数

| 参数          | 类型                                                       | 默认值 | 说明                       |
| ------------- | ---------------------------------------------------------- | ------ | -------------------------- |
| count         | number / string                                            | --     | 展示数字，0 默认隐藏       |
| showZero      | boolean                                                    | false  | 当数值为 0 时是否展示      |
| overflowCount | number                                                     | 99     | 展示封顶的数字值           |
| dot           | boolean                                                    | false  | 不展示数字，只有一个小红点 |
| status        | 'success' / 'processing' / 'default' / 'error' / 'warning' | --     | 状态点的颜色               |
| text          | string                                                     | --     | 状态点的文字               |
| color         | string                                                     | --     | 自定义小圆点颜色           |
| offset        | [number, number]                                           | --     | 设置徽标数偏移             |


---

# BadgeRibbon 缎带徽标

> 文档链接：https://vaebe.github.io/ccui/components/badge-ribbon/index.html

带折角缎带的徽标，作为独立顶层组件存在（不挂在 Badge 命名空间下）。

## 何时使用

- 卡片 / 商品 / 列表项需要在角落标注「新」「热」「限时」等带视觉冲击的徽标。

## 基本使用

`text` 设置缎带文字，默认 slot 是被装饰的内容。

:::demo

```vue
<template>
  <c-badge-ribbon text="Hippies">
    <c-card title="缎带示例" style="width: 280px"> 内容主体... </c-card>
  </c-badge-ribbon>
</template>
```

:::

## 不同位置

`placement: 'start' | 'end'`，默认 `end`（右上）。

:::demo

```vue
<template>
  <c-badge-ribbon text="右上" placement="end">
    <div style="width: 200px; height: 80px; background: var(--ccui-area); border-radius: 4px"></div>
  </c-badge-ribbon>
  <br />
  <c-badge-ribbon text="左上" placement="start" style="margin-top: 12px">
    <div style="width: 200px; height: 80px; background: var(--ccui-area); border-radius: 4px"></div>
  </c-badge-ribbon>
</template>
```

:::

## 预设色

13 种预设色名：`pink` / `magenta` / `red` / `volcano` / `orange` / `yellow` / `gold` / `cyan` / `lime` / `green` / `blue` / `geekblue` / `purple`。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      colors: [
        'pink',
        'red',
        'volcano',
        'orange',
        'gold',
        'lime',
        'green',
        'cyan',
        'blue',
        'geekblue',
        'purple',
        'magenta',
      ],
    }
  },
})
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <c-badge-ribbon v-for="c in colors" :key="c" :text="c" :color="c">
      <div style="width: 120px; height: 56px; background: var(--ccui-area); border-radius: 4px"></div>
    </c-badge-ribbon>
  </div>
</template>
```

:::

## 自定义色

非预设字符串作为 CSS color 字面量（`#hex` / `rgb()` / 命名色）。

:::demo

```vue
<template>
  <c-badge-ribbon text="自定义" color="#ff5500">
    <div style="width: 200px; height: 80px; background: var(--ccui-area); border-radius: 4px"></div>
  </c-badge-ribbon>
  <br />
  <c-badge-ribbon text="渐变色" color="hotpink" style="margin-top: 12px">
    <div style="width: 200px; height: 80px; background: var(--ccui-area); border-radius: 4px"></div>
  </c-badge-ribbon>
</template>
```

:::

## 文字 slot

需要图标 + 文字时用 `text` slot 完全自定义。

:::demo

```vue
<template>
  <c-badge-ribbon color="red">
    <template #text>
      <span>🔥 限时</span>
    </template>
    <div style="width: 200px; height: 80px; background: var(--ccui-area); border-radius: 4px"></div>
  </c-badge-ribbon>
</template>
```

:::

## BadgeRibbon 参数

| 参数      | 类型             | 默认 | 说明                                                               |
| --------- | ---------------- | ---- | ------------------------------------------------------------------ |
| text      | string           | ''   | 缎带文字（slot `text` 优先）                                       |
| color     | string           | ''   | 预设色名 / CSS color 字符串；预设色走 modifier，其余走 inline 背景 |
| placement | 'start' \| 'end' | end  | 缎带位置（右上 / 左上）                                            |

## BadgeRibbon 插槽

| 插槽名  | 说明                                      |
| ------- | ----------------------------------------- |
| default | 被装饰的内容（缎带浮于其右/左上角）       |
| text    | 缎带内文字 / 节点，优先级高于 `text` prop |


---

# BorderBeam 边框流光

> 文档链接：https://vaebe.github.io/ccui/components/border-beam/index.html

一道渐变光沿容器边框循环流动，用于给卡片、容器等内容加一层灵动的视觉强调。

## 何时使用

- 想突出某个卡片 / 面板，让它在页面中更吸睛。
- 营销页、活动入口、AI 能力卡片等需要动态氛围感的场景。

## 基本使用

默认插槽放置被包裹的内容，流光会绕着容器边框流动。`borderRadius` 默认 `8`，与 `c-card` 圆角一致，直接包裹卡片即可严丝合缝；不传 `color` 时使用主题主色渐变。

:::demo

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

<template>
  <c-border-beam style="width: 280px">
    <c-card header="智能助手">边框流光让卡片更有氛围感。</c-card>
  </c-border-beam>
</template>
```

:::

## 自定义配色

通过 `color` 传入单个颜色字符串。

:::demo

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

<template>
  <c-border-beam color="#ff4d4f" style="width: 280px">
    <c-card header="限时活动">距开始还有 2 天，先到先得。</c-card>
  </c-border-beam>
</template>
```

:::

## 渐变停靠点

`color` 传入停靠点数组（`percent` 取值 0 ~ 100）可得到多色渐变光带。

:::demo

```vue
<script setup lang="ts">
const beamColor = [
  { color: '#1677ff', percent: 0 },
  { color: '#36cfc9', percent: 52 },
  { color: '#95de64', percent: 100 },
]
</script>

<template>
  <c-border-beam :color="beamColor" style="width: 280px">
    <c-card header="多色渐变">蓝 → 青 → 绿 的流光。</c-card>
  </c-border-beam>
</template>
```

:::

## 内置配色预设

内置 6 套配色预设（Ocean / Sunset / Aurora / Forest / Ember / Nebula），从 `@vaebe/ccui` 导出 `borderBeamPresets`，直接把 `preset.color` 传给 `color` 即可。下方可切换预览。

:::demo

```vue
<script setup lang="ts">
import { borderBeamPresetKeys, borderBeamPresets } from '@vaebe/ccui'
import { computed, ref } from 'vue'

const current = ref('ocean')
const options = borderBeamPresetKeys.map((key) => ({ label: borderBeamPresets[key].name, value: key }))
const preset = computed(() => borderBeamPresets[current.value])
</script>

<template>
  <div style="max-width: 380px">
    <c-segmented v-model="current" :options="options" block style="margin-bottom: 16px" />
    <c-border-beam :color="preset.color">
      <c-card :header="preset.name">
        内置 {{ borderBeamPresetKeys.length }} 套配色，可直接传给 <code>color</code>。
      </c-card>
    </c-border-beam>
  </div>
</template>
```

:::

## 调速

`duration` 控制跑完一圈的时长（秒），值越小越快。

:::demo

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

<template>
  <div style="display: flex; gap: 24px">
    <c-border-beam :duration="3" style="width: 200px">
      <c-card header="快速">3s 一圈</c-card>
    </c-border-beam>
    <c-border-beam :duration="10" style="width: 200px">
      <c-card header="慢速">10s 一圈</c-card>
    </c-border-beam>
  </div>
</template>
```

:::

## 外扩与圆角

`outset` 让流光层相对容器边缘向外扩展，`borderWidth` 调整光带粗细，`borderRadius` 决定边框环圆角。

:::demo

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

<template>
  <c-border-beam :outset="6" :border-width="2" :border-radius="16" style="width: 240px">
    <c-card>外扩 6px、2px 粗光带</c-card>
  </c-border-beam>
</template>
```

:::

## API

### Props

| 参数         | 说明                                                       | 类型                                | 默认值 |
| ------------ | ---------------------------------------------------------- | ----------------------------------- | ------ |
| color        | 流光颜色，单色字符串或渐变停靠点数组；不传时用主题主色渐变 | [BorderBeamColor](#borderbeamcolor) | -      |
| outset       | 流光层相对容器边缘的外扩距离（number 视为 px）             | `number \| string`                  | `0`    |
| borderWidth  | 边框 / 光带粗细（px）                                      | `number`                            | `1`    |
| borderRadius | 容器圆角（px），与被包裹内容保持一致即可严丝合缝           | `number`                            | `8`    |
| duration     | 跑完一圈的时长（秒）                                       | `number`                            | `6`    |

### Slots

| 插槽名  | 说明             |
| ------- | ---------------- |
| default | 被流光包裹的内容 |

## BorderBeam 类型定义

### BorderBeamColor

```ts
export interface BorderBeamColorStop {
  /** 颜色值，支持任意 CSS 颜色 */
  color: string
  /** 渐变停靠位置，取值 0 ~ 100 */
  percent: number
}

export type BorderBeamColor = string | BorderBeamColorStop[]
```

## 内置预设

从 `@vaebe/ccui` 导出，按定义顺序提供 6 套配色：

```ts
import { borderBeamPresetKeys, borderBeamPresets } from '@vaebe/ccui'

// borderBeamPresetKeys: ['ocean', 'sunset', 'aurora', 'forest', 'ember', 'nebula']
// borderBeamPresets.ocean.color → BorderBeamColorStop[]

export interface BorderBeamPreset {
  key: string
  name: string
  color: BorderBeamColorStop[]
}
```


---

# Breadcrumb 面包屑

> 文档链接：https://vaebe.github.io/ccui/components/breadcrumb/index.html

显示当前页面在系统层级中的位置，并提供向上导航能力。

## 何时使用

- 系统层级 ≥ 3 级时辅助用户定位。
- 详情页头部展示 "返回路径"，支持多级跳转回。

## 基本使用

最常见的写法：用一组 `<c-breadcrumb-item>` 组合，最末一级是当前页（不带链接）。

:::demo

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item>
      <a href="#">首页</a>
    </c-breadcrumb-item>
    <c-breadcrumb-item>
      <a href="#">应用中心</a>
    </c-breadcrumb-item>
    <c-breadcrumb-item>
      <a href="#">应用列表</a>
    </c-breadcrumb-item>
    <c-breadcrumb-item>某个应用</c-breadcrumb-item>
  </c-breadcrumb>
</template>
```

:::

## 用 routes 数据驱动

适合从路由表 / 后端响应直接生成路径。`routes[i].href` 提供链接，`routes[i].breadcrumbName` 提供文字；最末一项不渲染为 `<a>`。

:::demo

```vue
<script setup>
const routes = [
  { breadcrumbName: '首页', href: '/' },
  { breadcrumbName: '应用列表', href: '/apps' },
  { breadcrumbName: '应用详情' },
]
</script>

<template>
  <c-breadcrumb :routes="routes" />
</template>
```

:::

## 自定义分隔符

`separator` 可以是任意字符串。

:::demo

```vue
<template>
  <c-breadcrumb separator=">">
    <c-breadcrumb-item><a href="#">Home</a></c-breadcrumb-item>
    <c-breadcrumb-item><a href="#">Docs</a></c-breadcrumb-item>
    <c-breadcrumb-item>Breadcrumb</c-breadcrumb-item>
  </c-breadcrumb>

  <c-breadcrumb separator="·" style="margin-top: 8px">
    <c-breadcrumb-item><a href="#">A</a></c-breadcrumb-item>
    <c-breadcrumb-item><a href="#">B</a></c-breadcrumb-item>
    <c-breadcrumb-item>C</c-breadcrumb-item>
  </c-breadcrumb>
</template>
```

:::

## 单项自定义分隔符

某项的 `separator` 属性会覆盖整组的分隔符。

:::demo

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item><a href="#">首页</a></c-breadcrumb-item>
    <c-breadcrumb-item separator="→"><a href="#">商品</a></c-breadcrumb-item>
    <c-breadcrumb-item>详情</c-breadcrumb-item>
  </c-breadcrumb>
</template>
```

:::

## 用 #separator 插槽

用 slot 写自定义分隔符，可以放图标 / SVG / 文字组合。

:::demo

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item href="#">
      首页
      <template #separator>
        <span style="color: var(--ccui-color-primary); margin: 0 8px">»</span>
      </template>
    </c-breadcrumb-item>
    <c-breadcrumb-item href="#">
      工单
      <template #separator>
        <span style="color: var(--ccui-color-primary); margin: 0 8px">»</span>
      </template>
    </c-breadcrumb-item>
    <c-breadcrumb-item>详情</c-breadcrumb-item>
  </c-breadcrumb>
</template>
```

:::

## 配合按钮

面包屑右侧常和操作按钮并列，可用 flex 布局。

:::demo

```vue
<template>
  <div
    style="display: flex; align-items: center; justify-content: space-between; padding: 8px 12px; background: var(--ccui-area); border-radius: 6px"
  >
    <c-breadcrumb>
      <c-breadcrumb-item><a href="#">首页</a></c-breadcrumb-item>
      <c-breadcrumb-item><a href="#">订单</a></c-breadcrumb-item>
      <c-breadcrumb-item>#202504</c-breadcrumb-item>
    </c-breadcrumb>
    <c-button type="primary">新建订单</c-button>
  </div>
</template>
```

:::

## API

### Breadcrumb Props

| 参数      | 类型                | 默认值 | 说明                           |
| --------- | ------------------- | ------ | ------------------------------ |
| separator | string              | `'/'`  | 分隔符                         |
| routes    | `BreadcrumbRoute[]` | `[]`   | 路由数据，提供时优先于默认插槽 |

### BreadcrumbRoute

| 字段           | 类型   | 说明                                 |
| -------------- | ------ | ------------------------------------ |
| breadcrumbName | string | 显示文本                             |
| title          | string | `breadcrumbName` 的别名              |
| href           | string | 链接地址                             |
| path           | string | 链接地址（兼容字段，与 `href` 等价） |

### BreadcrumbItem Props

| 参数      | 类型   | 默认值 | 说明                         |
| --------- | ------ | ------ | ---------------------------- |
| href      | string | `''`   | 设置后整项渲染为 `<a>`       |
| separator | string | `''`   | 单项级别覆盖父级 `separator` |

### BreadcrumbItem Slots

| 名称      | 说明                         |
| --------- | ---------------------------- |
| default   | 内容                         |
| separator | 自定义分隔符（覆盖字符形式） |


---

# Button 按钮

> 文档链接：https://vaebe.github.io/ccui/components/button/index.html

常用的操作按钮。

## 何时使用

按钮用于开始一个即时操作。

## 基本使用

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button>默认按钮</c-button>
    <c-button type="primary"> 主要按钮 </c-button>
    <c-button type="success"> 成功按钮 </c-button>
    <c-button type="warning"> 警告按钮 </c-button>
    <c-button type="danger"> 危险按钮 </c-button>
    <c-button type="info"> 信息按钮 </c-button>
    <c-button type="text"> 文字按钮 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
  margin-bottom: 10px;
}
</style>
```

:::

## 不同尺寸

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button type="primary" size="large"> 大型按钮 </c-button>
    <c-button type="primary"> 默认按钮 </c-button>
    <c-button type="primary" size="small"> 小型按钮 </c-button>
  </div>
  <div style="margin-top: 10px;">
    <c-button type="success" size="large" round> 大型按钮 </c-button>
    <c-button type="success" round> 默认按钮 </c-button>
    <c-button type="success" size="small" round> 小型按钮 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
}
</style>
```

:::

## 禁用状态

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button disabled> 默认按钮 </c-button>
    <c-button type="primary" disabled> 主要按钮 </c-button>
    <c-button type="success" disabled> 成功按钮 </c-button>
    <c-button type="warning" disabled> 警告按钮 </c-button>
    <c-button type="danger" disabled> 危险按钮 </c-button>
    <c-button type="info" disabled> 信息按钮 </c-button>
    <c-button type="text" disabled> 文字按钮 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
  margin-bottom: 10px;
}
</style>
```

:::

## 圆角按钮

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button type="primary" round> 圆角按钮 </c-button>
    <c-button type="success" round> 圆角按钮 </c-button>
    <c-button type="warning" size="small" round> 小型圆角 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
}
</style>
```

:::

## 圆形按钮

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button type="primary" circle> A </c-button>
    <c-button type="success" circle> B </c-button>
    <c-button type="warning" circle> C </c-button>
  </div>

  <div style="margin-top: 10px;">
    <c-button type="primary" size="large" circle> D </c-button>
    <c-button type="primary" circle> E </c-button>
    <c-button type="primary" size="small" circle> F </c-button>
  </div>

  <div style="margin-top: 10px;">
    <c-button type="primary" circle>
      <template #icon>
        <svg
          t="1649322922975"
          class="icon"
          viewBox="0 0 1024 1024"
          version="1.1"
          xmlns="http://www.w3.org/2000/svg"
          p-id="3628"
          width="16"
          height="16"
        >
          <path
            d="M943.273421 506.259252C906.84065 320.247768 724.900901 185.233772 510.685052 185.233772c-214.228129 0-396.154575 135.01502-432.589392 321.025481-0.529049 2.765997-0.529049 5.611811 0 8.376785C114.530476 700.66901 296.457946 835.685054 510.685052 835.685054c84.754313 0 166.926824-21.296025 237.682307-61.551868 10.854209-6.196119 14.542204-19.829628 8.197706-30.479175-6.341429-10.599406-20.225647-14.158465-31.172977-8.006348-63.754023 36.307927-138.010237 55.516408-214.709083 55.516408-190.771905 0-352.71932-117.805056-386.970402-280.715403 34.250058-162.89909 196.22101-280.690844 386.970402-280.690844 190.771905 0 352.71932 117.791753 386.969379 280.690844-12.098549 57.384965-41.084721 111.433952-84.026742 156.599617-8.574283 8.997931-8.032954 23.089881 1.174756 31.464619 9.184173 8.356318 23.608697 7.872295 32.207539-1.147126 49.846268-52.396347 83.111906-115.577319 96.265484-182.739974C943.813726 511.859807 943.813726 509.026272 943.273421 506.259252z"
            p-id="3629"
            fill="#ffffff"
          />
          <path
            d="M328.909032 515.482311c0 100.308567 81.792864 181.669596 182.689832 181.669596 100.872409 0 182.665273-81.362053 182.665273-181.669596 0.001023-100.307543-81.791841-181.634804-182.665273-181.634804l0 0C410.701896 333.847507 328.909032 415.174768 328.909032 515.482311zM648.616494 515.482311c0 75.237565-61.337997 136.257314-137.01763 136.257314l0 0c-75.67861 0-137.042189-61.018725-137.042189-136.257314 0-75.211982 61.362556-136.231731 137.042189-136.231731C587.277474 379.25058 648.616494 440.270329 648.616494 515.482311z"
            p-id="3630"
            fill="#ffffff"
          />
        </svg>
      </template>
    </c-button>

    <c-button type="success" circle>
      <template #icon>
        <svg
          t="1649322922975"
          class="icon"
          viewBox="0 0 1024 1024"
          version="1.1"
          xmlns="http://www.w3.org/2000/svg"
          p-id="3628"
          width="12"
          height="12"
        >
          <path
            d="M943.273421 506.259252C906.84065 320.247768 724.900901 185.233772 510.685052 185.233772c-214.228129 0-396.154575 135.01502-432.589392 321.025481-0.529049 2.765997-0.529049 5.611811 0 8.376785C114.530476 700.66901 296.457946 835.685054 510.685052 835.685054c84.754313 0 166.926824-21.296025 237.682307-61.551868 10.854209-6.196119 14.542204-19.829628 8.197706-30.479175-6.341429-10.599406-20.225647-14.158465-31.172977-8.006348-63.754023 36.307927-138.010237 55.516408-214.709083 55.516408-190.771905 0-352.71932-117.805056-386.970402-280.715403 34.250058-162.89909 196.22101-280.690844 386.970402-280.690844 190.771905 0 352.71932 117.791753 386.969379 280.690844-12.098549 57.384965-41.084721 111.433952-84.026742 156.599617-8.574283 8.997931-8.032954 23.089881 1.174756 31.464619 9.184173 8.356318 23.608697 7.872295 32.207539-1.147126 49.846268-52.396347 83.111906-115.577319 96.265484-182.739974C943.813726 511.859807 943.813726 509.026272 943.273421 506.259252z"
            p-id="3629"
            fill="#ffffff"
          />
          <path
            d="M328.909032 515.482311c0 100.308567 81.792864 181.669596 182.689832 181.669596 100.872409 0 182.665273-81.362053 182.665273-181.669596 0.001023-100.307543-81.791841-181.634804-182.665273-181.634804l0 0C410.701896 333.847507 328.909032 415.174768 328.909032 515.482311zM648.616494 515.482311c0 75.237565-61.337997 136.257314-137.01763 136.257314l0 0c-75.67861 0-137.042189-61.018725-137.042189-136.257314 0-75.211982 61.362556-136.231731 137.042189-136.231731C587.277474 379.25058 648.616494 440.270329 648.616494 515.482311z"
            p-id="3630"
            fill="#ffffff"
          />
        </svg>
      </template>
    </c-button>

    <c-button type="warning" size="small" circle>
      <template #icon>
        <svg
          t="1649322922975"
          class="icon"
          viewBox="0 0 1024 1024"
          version="1.1"
          xmlns="http://www.w3.org/2000/svg"
          p-id="3628"
          width="10"
          height="10"
        >
          <path
            d="M943.273421 506.259252C906.84065 320.247768 724.900901 185.233772 510.685052 185.233772c-214.228129 0-396.154575 135.01502-432.589392 321.025481-0.529049 2.765997-0.529049 5.611811 0 8.376785C114.530476 700.66901 296.457946 835.685054 510.685052 835.685054c84.754313 0 166.926824-21.296025 237.682307-61.551868 10.854209-6.196119 14.542204-19.829628 8.197706-30.479175-6.341429-10.599406-20.225647-14.158465-31.172977-8.006348-63.754023 36.307927-138.010237 55.516408-214.709083 55.516408-190.771905 0-352.71932-117.805056-386.970402-280.715403 34.250058-162.89909 196.22101-280.690844 386.970402-280.690844 190.771905 0 352.71932 117.791753 386.969379 280.690844-12.098549 57.384965-41.084721 111.433952-84.026742 156.599617-8.574283 8.997931-8.032954 23.089881 1.174756 31.464619 9.184173 8.356318 23.608697 7.872295 32.207539-1.147126 49.846268-52.396347 83.111906-115.577319 96.265484-182.739974C943.813726 511.859807 943.813726 509.026272 943.273421 506.259252z"
            p-id="3629"
            fill="#ffffff"
          />
          <path
            d="M328.909032 515.482311c0 100.308567 81.792864 181.669596 182.689832 181.669596 100.872409 0 182.665273-81.362053 182.665273-181.669596 0.001023-100.307543-81.791841-181.634804-182.665273-181.634804l0 0C410.701896 333.847507 328.909032 415.174768 328.909032 515.482311zM648.616494 515.482311c0 75.237565-61.337997 136.257314-137.01763 136.257314l0 0c-75.67861 0-137.042189-61.018725-137.042189-136.257314 0-75.211982 61.362556-136.231731 137.042189-136.231731C587.277474 379.25058 648.616494 440.270329 648.616494 515.482311z"
            p-id="3630"
            fill="#ffffff"
          />
        </svg>
      </template>
    </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
}
</style>
```

:::

## 朴素按钮

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button type="primary" plain> 朴素按钮 </c-button>
    <c-button type="success" plain> 朴素按钮 </c-button>
    <c-button type="warning" plain> 朴素按钮 </c-button>
    <c-button type="danger" plain> 朴素按钮 </c-button>
    <c-button type="info" plain> 朴素按钮 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
  margin-bottom: 10px;
}
</style>
```

:::

## 加载状态

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const loading = ref(false)

    const handleClick = () => {
      loading.value = true
      setTimeout(() => {
        loading.value = false
      }, 2000)
    }

    return {
      loading,
      handleClick,
    }
  },
})
</script>

<template>
  <div>
    <c-button type="primary" loading> 加载中 </c-button>
    <c-button type="success" loading> 提交中 </c-button>
    <c-button type="primary" :loading="loading" @click="handleClick"> 点击加载 </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
}
</style>
```

:::

## 图标按钮

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-button type="primary" icon="mdi:magnify"> 搜索 </c-button>
    <c-button type="success" icon="mdi:pencil"> 编辑 </c-button>
    <c-button type="warning" icon="mdi:delete"> 删除 </c-button>
    <c-button type="danger" icon="mdi:plus"> 添加 </c-button>
  </div>

  <div style="margin-top: 10px;">
    <c-button type="primary">
      <template #icon>
        <svg
          t="1649322922975"
          class="icon"
          viewBox="0 0 1024 1024"
          version="1.1"
          xmlns="http://www.w3.org/2000/svg"
          p-id="3628"
          width="16"
          height="16"
        >
          <path
            d="M943.273421 506.259252C906.84065 320.247768 724.900901 185.233772 510.685052 185.233772c-214.228129 0-396.154575 135.01502-432.589392 321.025481-0.529049 2.765997-0.529049 5.611811 0 8.376785C114.530476 700.66901 296.457946 835.685054 510.685052 835.685054c84.754313 0 166.926824-21.296025 237.682307-61.551868 10.854209-6.196119 14.542204-19.829628 8.197706-30.479175-6.341429-10.599406-20.225647-14.158465-31.172977-8.006348-63.754023 36.307927-138.010237 55.516408-214.709083 55.516408-190.771905 0-352.71932-117.805056-386.970402-280.715403 34.250058-162.89909 196.22101-280.690844 386.970402-280.690844 190.771905 0 352.71932 117.791753 386.969379 280.690844-12.098549 57.384965-41.084721 111.433952-84.026742 156.599617-8.574283 8.997931-8.032954 23.089881 1.174756 31.464619 9.184173 8.356318 23.608697 7.872295 32.207539-1.147126 49.846268-52.396347 83.111906-115.577319 96.265484-182.739974C943.813726 511.859807 943.813726 509.026272 943.273421 506.259252z"
            p-id="3629"
            fill="#ffffff"
          />
          <path
            d="M328.909032 515.482311c0 100.308567 81.792864 181.669596 182.689832 181.669596 100.872409 0 182.665273-81.362053 182.665273-181.669596 0.001023-100.307543-81.791841-181.634804-182.665273-181.634804l0 0C410.701896 333.847507 328.909032 415.174768 328.909032 515.482311zM648.616494 515.482311c0 75.237565-61.337997 136.257314-137.01763 136.257314l0 0c-75.67861 0-137.042189-61.018725-137.042189-136.257314 0-75.211982 61.362556-136.231731 137.042189-136.231731C587.277474 379.25058 648.616494 440.270329 648.616494 515.482311z"
            p-id="3630"
            fill="#ffffff"
          />
        </svg>
      </template>
      带图标的按钮
    </c-button>
  </div>
</template>

<style>
.ccui-button {
  margin-right: 10px;
  margin-bottom: 10px;
}
</style>
```

:::

## 自定义颜色 color

`color` 接受任意 CSS color 字符串。实心 type（`primary`/`success`/`warning`/`danger`/`info`）注入 `background-color + border-color`；描边 type（`''`/`default`/`dashed`）注入 `color + border-color`；`text`/`link` 仅注入 `color`。hover/active 联动由使用方用 CSS class 自兜底。

:::demo

```vue
<template>
  <div style="display: flex; flex-wrap: wrap; gap: 10px">
    <c-button type="primary" color="#722ed1">实心紫</c-button>
    <c-button type="success" color="#13c2c2">青色 success</c-button>
    <c-button color="#fa541c">描边橙</c-button>
    <c-button type="dashed" color="#eb2f96">描边粉</c-button>
    <c-button type="text" color="#1677ff">文字蓝</c-button>
    <c-button type="link" color="#52c41a">链接绿</c-button>
  </div>
</template>
```

:::

## Button参数

| 参数            | 类型                                                  | 默认    | 说明                                                                                                                    |
| --------------- | ----------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| size            | [ButtonSizeType](#buttonsizetype)                     | --      | 尺寸                                                                                                                    |
| type            | [ButtonType](#buttontype)                             | --      | 类型：`'primary' \| 'default' \| 'dashed' \| 'link' \| 'text'`，加语义色 `'success' \| 'warning' \| 'danger' \| 'info'` |
| plain           | boolean                                               | false   | 朴素按钮：背景透明，文字与边框跟主色                                                                                    |
| round           | boolean                                               | false   | 圆角按钮                                                                                                                |
| circle          | boolean                                               | false   | 圆形按钮（常用于纯图标场景）                                                                                            |
| native-type     | [ButtonNativeType](#buttonnativetype)                 | button  | 原生 `<button>` 的 type 属性                                                                                            |
| danger          | boolean                                               | false   | 危险按钮（与 `type` 任意值叠加，渲染 `--dangerous` 类）                                                                 |
| ghost           | boolean                                               | false   | 幽灵按钮（透明背景 + 描边色）                                                                                           |
| block           | boolean                                               | false   | 撑满父宽度                                                                                                              |
| autoInsertSpace | boolean                                               | true    | 两个 CJK 字符之间自动插入空格                                                                                           |
| href            | string                                                | --      | 设置后用 `<a role="button">` 渲染                                                                                       |
| target          | string                                                | --      | 配合 `href` 透传 `target`                                                                                               |
| icon            | string \| VNode                                       | --      | 图标（也可用 `icon` slot）                                                                                              |
| iconPosition    | 'start' \| 'end'                                      | start   | 图标位置                                                                                                                |
| disabled        | boolean                                               | false   | 是否为禁用状态                                                                                                          |
| autofocus       | boolean                                               | false   | 原生 autofocus 属性                                                                                                     |
| loading         | boolean \| { delay?: number; icon?: VNode \| string } | false   | 加载状态；对象形支持 `delay` 推迟显示与自定义 `icon`                                                                    |
| color           | string                                                | --      | 自定义按钮颜色（任意 CSS color 字符串）；实心型 type 注入 bg + border；描边型注入 color + border；text/link 仅 color    |

## ButtonGroup 参数

`ButtonGroup`（`<c-button-group>`）：按钮组，向子按钮注入 `size` / `disabled`，并让相邻边框对齐。

| 参数     | 类型                            | 默认    | 说明                                       |
| -------- | ------------------------------- | ------- | ------------------------------------------ |
| size     | 'large' \| 'default' \| 'small' | default | 注入给所有子按钮（子按钮显式 prop 仍优先） |
| disabled | boolean                         | false   | 注入给所有子按钮                           |

## Button类型定义

### ButtonType

```ts
export type ButtonType =
  // 标准取值
  | 'primary'
  | 'default'
  | 'dashed'
  | 'link'
  | 'text'
  // 语义色快捷
  | 'success'
  | 'warning'
  | 'danger'
  | 'info'
```

### ButtonSizeType

```ts
export type ButtonSizeType = 'large' | 'default' | 'small'
```

### ButtonNativeType

```ts
export type ButtonNativeType = 'button' | 'submit' | 'reset'
```

## Button插槽

| 插槽名 | 说明           |
| ------ | -------------- |
| icon   | 自定义图标组件 |


---

# Button3d 3D按钮

> 文档链接：https://vaebe.github.io/ccui/components/button-3d/index.html

3D 效果按钮，基于 [Building a Magical 3D Button](https://www.joshwcomeau.com/animation/3d-button/) 实现。

## 基础用法

:::demo

```vue
<template>
  <div>
    <c-button-3d>默认按钮</c-button-3d>
    <c-button-3d type="primary"> 主要按钮 </c-button-3d>
    <c-button-3d type="success"> 成功按钮 </c-button-3d>
    <c-button-3d type="warning"> 警告按钮 </c-button-3d>
    <c-button-3d type="danger"> 危险按钮 </c-button-3d>
    <c-button-3d type="info"> 信息按钮 </c-button-3d>
  </div>
</template>
```

:::

## 尺寸

:::demo

```vue
<template>
  <div>
    <c-button-3d size="large"> 大按钮 </c-button-3d>
    <c-button-3d type="primary"> 默认按钮 </c-button-3d>
    <c-button-3d size="small" type="success"> 小按钮 </c-button-3d>
  </div>
</template>
```

:::

## 禁用状态

:::demo

```vue
<template>
  <div>
    <c-button-3d disabled> 禁用按钮 </c-button-3d>

    <c-button-3d type="primary" disabled> 禁用按钮 primary 状态 </c-button-3d>
  </div>
</template>
```

:::

## 加载状态

:::demo

```vue
<template>
  <div>
    <c-button-3d loading> 加载中 </c-button-3d>
    <c-button-3d type="primary" loading> 加载中 </c-button-3d>
  </div>
</template>
```

:::

## API

### Props

| 参数       | 说明       | 类型                 | 可选值                                    | 默认值    |
| ---------- | ---------- | -------------------- | ----------------------------------------- | --------- |
| size       | 尺寸       | `Button3DSize`       | [Button3DSizeType](#button3dsizetype)     | `default` |
| type       | 类型       | `Button3DType`       | [Button3DType](#button3dtype)             |           |
| disabled   | 是否禁用   | `boolean`            | -                                         | `false`   |
| loading    | 是否加载中 | `boolean`            | -                                         | `false`   |
| nativeType | 原生类型   | `Button3DNativeType` | [Button3DNativeType](#button3dnativetype) | `button`  |

## Button-3d 类型定义

### Button3DType

```ts
export type Button3DType = 'primary' | 'success' | 'warning' | 'danger' | 'info'
```

### Button3DSizeType

```ts
export type Button3DSizeType = 'large' | 'default' | 'small'
```

### Button3DNativeType

```ts
export type Button3DNativeType = 'button' | 'submit' | 'reset'
```


---

# Calendar 日历

> 文档链接：https://vaebe.github.io/ccui/components/calendar/index.html

按月展示日期，常用于"日程 / 任务 / 排班"场景。

## 何时使用

- 单选某一天作为业务输入。
- 自定义每天的 cell，叠加业务标记（如待办数量、状态徽标）。

## 基本使用

`v-model` 默认绑定 `YYYY-MM-DD` 字符串，点击单元格切换选中日。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date().toISOString().slice(0, 10))
</script>

<template>
  <c-calendar v-model="date" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">已选：{{ date }}</p>
</template>
```

:::

## 监听变化

`change` 事件返回新选中的日期，类型随 `valueFormat`（默认 `'string'`）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date().toISOString().slice(0, 10))
const log = ref('（无）')

function onChange(val) {
  log.value = String(val)
}
</script>

<template>
  <c-calendar v-model="date" @change="onChange" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近 change：{{ log }}</p>
</template>
```

:::

## 只读模式

`read-only` 让用户无法点击切换，常用于"展示一份排期表"。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date().toISOString().slice(0, 10))
</script>

<template>
  <c-calendar v-model="date" read-only />
</template>
```

:::

## 自定义 header

`#header` 插槽接收作用域对象 `{ value, currentMonth, setDate, changeMonth }`，slot 内可直接调用月份切换 API，无需从外部维护状态。

| 字段         | 类型                                              | 说明                         |
| ------------ | ------------------------------------------------- | ---------------------------- |
| value        | `string`                                          | 当前选中日期（`YYYY-MM-DD`） |
| currentMonth | `string`                                          | 当前展示月份（`YYYY-MM`）    |
| setDate      | `(date: string) => void`                          | 跳转到任意 `YYYY-MM-DD`      |
| changeMonth  | `(direction: 'lastMonth' \| 'nextMonth') => void` | 上下月切换                   |

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date().toISOString().slice(0, 10))
</script>

<template>
  <c-calendar v-model="date">
    <template #header="{ value, currentMonth, setDate, changeMonth }">
      <div style="padding: 8px 12px; display: flex; align-items: center; gap: 8px; border-bottom: 1px solid var(--ccui-color-border-secondary)">
        <c-button size="small" @click="changeMonth('lastMonth')">‹ 上月</c-button>
        <c-button size="small" @click="changeMonth('nextMonth')">下月 ›</c-button>
        <c-button size="small" type="primary" @click="setDate(new Date().toISOString().slice(0, 10))">今天</c-button>
        <span style="margin-inline-start: auto; color: var(--ccui-color-text-secondary)">当前月：{{ currentMonth }}</span>
        <span style="color: var(--ccui-color-text-secondary)">选中：{{ value }}</span>
      </div>
    </template>
  </c-calendar>
</template>
```

:::

## 自定义日期 cell

`#dateCell` 插槽接收 `{ isSelected, date, day }`，可在每一天上叠加业务标记。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date().toISOString().slice(0, 10))

const events = {
  5: '订货',
  12: '复盘',
  18: '上线',
  25: '排班',
}
</script>

<template>
  <c-calendar v-model="date">
    <template #dateCell="{ isSelected, day }">
      <div :style="{ position: 'relative', height: '100%' }">
        <span>{{ day }}</span>
        <span
          v-if="events[day]"
          :style="{
            position: 'absolute',
            inset: 'auto 0 0 0',
            fontSize: '11px',
            color: isSelected ? 'var(--ccui-color-text-light-solid)' : 'var(--ccui-color-primary)',
          }"
        >
          • {{ events[day] }}
        </span>
      </div>
    </template>
  </c-calendar>
</template>
```

:::

## 选中信息回显

把 `dateCell` 的 `isSelected` 拿来显示"已选 / 未选"提示。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref('2026-03-15')
</script>

<template>
  <c-calendar v-model="date">
    <template #dateCell="{ isSelected, day }">
      <c-icon v-if="isSelected" name="mdi:check" />
      <template v-else>{{ day }}</template>
    </template>
  </c-calendar>
</template>
```

:::

## valueFormat='string'（默认）

字符串协议，便于 JSON 序列化和路由参数透传。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref('2026-03-15')
</script>

<template>
  <c-calendar v-model="date" />
  <p>当前值（string）：{{ date }}</p>
</template>
```

:::

## valueFormat='date'

输出原生 `Date`，便于与既有日期 API 互操作。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(new Date(2026, 2, 15))
</script>

<template>
  <c-calendar v-model="date" value-format="date" />
  <p>ISO：{{ date.toISOString() }}</p>
</template>
```

:::

## valueFormat='number' timestamp

毫秒级 timestamp，便于直接落库。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const ts = ref(Date.now())
</script>

<template>
  <c-calendar v-model="ts" value-format="number" />
  <p>timestamp：{{ ts }}</p>
  <p>反解：{{ new Date(ts).toLocaleDateString() }}</p>
</template>
```

:::

## 自定义 format

`format` 同时控制输入解析与字符串输出。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref('2026/03/15')
</script>

<template>
  <c-calendar v-model="date" format="YYYY/MM/DD" />
  <p>当前值：{{ date }}</p>
</template>
```

:::

## Dayjs 实例输入

直接传 `dayjs()` 实例做初始化，组件内部统一转 dayjs 处理。

:::demo

```vue
<script setup>
import { ref } from 'vue'
import dayjs from 'dayjs'

const date = ref(dayjs().add(7, 'day').format('YYYY-MM-DD'))
</script>

<template>
  <c-calendar v-model="date" />
  <p>七天后：{{ date }}</p>
</template>
```

:::

## 空值初始化

`null` 时回退到当天高亮。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const date = ref(null)
</script>

<template>
  <c-calendar v-model="date" />
  <p>当前值：{{ date ?? '（未选择）' }}</p>
</template>
```

:::

## 周末高亮

用 `dateCell` slot + dayjs 算出 `dayOfWeek`，给周六周日加视觉权重。

:::demo

```vue
<script setup>
import { ref } from 'vue'
import dayjs from 'dayjs'

const date = ref('2026-03-15')
function isWeekend(d) {
  const w = dayjs(d).day()
  return w === 0 || w === 6
}
</script>

<template>
  <c-calendar v-model="date">
    <template #dateCell="{ date: d, day }">
      <span :style="{ color: isWeekend(d) ? 'var(--c-color-error)' : 'inherit', fontWeight: isWeekend(d) ? 600 : 400 }">
        {{ day }}
      </span>
    </template>
  </c-calendar>
</template>
```

:::

## 双月对照

并列两个 Calendar 浏览跨月范围。

:::demo

```vue
<script setup>
import { ref } from 'vue'
import dayjs from 'dayjs'

const left = ref(dayjs().format('YYYY-MM-DD'))
const right = ref(dayjs().add(1, 'month').format('YYYY-MM-DD'))
</script>

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap;">
    <c-calendar v-model="left" style="flex: 1; min-width: 280px;" />
    <c-calendar v-model="right" style="flex: 1; min-width: 280px;" />
  </div>
</template>
```

:::

## API

### Props

| 参数        | 类型                                        | 默认值         | 说明                                                                           |
| ----------- | ------------------------------------------- | -------------- | ------------------------------------------------------------------------------ |
| modelValue  | `string \| number \| Date \| Dayjs \| null` | --             | 选中日期（v-model）；`null` 回退到今天                                         |
| format      | string                                      | `'YYYY-MM-DD'` | 字符串输入解析模板 + `valueFormat='string'` 时的输出模板（dayjs format token） |
| valueFormat | `'string' \| 'date' \| 'number'`            | `'string'`     | v-model 输出协议：字符串 / 原生 `Date` / 毫秒级 timestamp                      |
| readOnly    | boolean                                     | `false`        | 只读模式                                                                       |
| classNames  | `{ root?, header?, body?, cell? }`          | --             | 语义化 DOM className 注入                                                      |
| styles      | `{ root?, header?, body?, cell? }`          | --             | 语义化 DOM style 注入                                                          |

### Events

| 事件   | 回调签名                                    | 说明                               |
| ------ | ------------------------------------------- | ---------------------------------- |
| change | `(value: string \| Date \| number \| null)` | 选中日期变化；类型随 `valueFormat` |

### Slots

| 名称     | 说明                                                                                    |
| -------- | --------------------------------------------------------------------------------------- |
| header   | 自定义日历头部，作用域 `{ value, currentMonth, setDate, changeMonth }`（详见上方 demo） |
| dateCell | 自定义日期 cell，参数 `{ isSelected, date, day }`：是否选中 / 完整日期串 / 单元日号     |


---

# Card 卡片

> 文档链接：https://vaebe.github.io/ccui/components/card/index.html

将信息聚合在卡片容器中展示。

## 何时使用

- 概览展示一组信息
- 信息组合成的入口卡片
- 列表项的独立单元

## 基本使用

通过 `header` 设置卡片标题，默认插槽放内容。

:::demo

```vue
<template>
  <c-card header="基础卡片">
    我们终将远行，和过去稚嫩的自己告别。这是一个流行告别的时代，陪你颠沛流离的人越来越少，
    直至没有。我们也要习惯昔日好友的渐行渐远，因为我们终将长大，长大到可以独自一人抵挡风雨。
  </c-card>
</template>
```

:::

## 阴影效果

`shadow` 控制阴影显示时机：`always`（默认）/ `hover` / `never`。

:::demo

```vue
<template>
  <c-card header="一直显示阴影" style="margin-bottom: 12px"> shadow="always" </c-card>
  <c-card shadow="hover" header="鼠标悬停时显示阴影" style="margin-bottom: 12px"> shadow="hover" </c-card>
  <c-card shadow="never" header="不显示阴影"> shadow="never" </c-card>
</template>
```

:::

## 自定义标题区

`header` 插槽完全自定义标题，可以放图标、按钮、副标题等。

:::demo

```vue
<template>
  <c-card>
    <template #header>
      <div style="display: flex; align-items: center; justify-content: space-between">
        <span style="font-weight: 500">最近订单</span>
        <c-button type="text">查看全部</c-button>
      </div>
    </template>
    最近 7 天产生订单 32 笔，金额 ¥12,840。
  </c-card>
</template>
```

:::

## 不带标题

不传 `header` 也不传 `header` slot 时，卡片只显示内容区。

:::demo

```vue
<template>
  <c-card>
    <p style="margin: 0">没有标题的纯内容卡片，常用作信息聚合面板。</p>
  </c-card>
</template>
```

:::

## 自定义内容内边距

`body-style` 接受 CSS 对象，覆盖默认 20px padding。

:::demo

```vue
<template>
  <c-card header="紧凑模式" :body-style="{ padding: '8px 12px' }" style="margin-bottom: 12px">
    body padding 改为 8px 12px
  </c-card>
  <c-card header="去掉内边距" :body-style="{ padding: '0' }">
    <img
      src="https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg"
      style="display: block; width: 100%"
    />
  </c-card>
</template>
```

:::

## 卡片栅格

配合 `c-row` / `c-col` 实现卡片栅格，常见于仪表盘。

:::demo

```vue
<template>
  <c-row :gutter="12">
    <c-col :span="8">
      <c-card header="今日订单">128</c-card>
    </c-col>
    <c-col :span="8">
      <c-card header="今日访客">2,408</c-card>
    </c-col>
    <c-col :span="8">
      <c-card header="今日 GMV">¥38,420</c-card>
    </c-col>
  </c-row>
</template>
```

:::

## 卡片元数据（c-card-meta）

`<c-card-meta>` 提供「头像 + 标题 + 描述」标准三段元素，常用于商品 / 用户 / 文章卡片。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap">
    <c-card style="width: 240px" :body-style="{ padding: '16px' }">
      <div
        style="width: 100%; height: 120px; border-radius: 4px; margin-bottom: 12px; background: linear-gradient(135deg, #1677ff 0%, #69c0ff 100%); display: flex; align-items: center; justify-content: center; color: var(--ccui-color-text-light-solid); font-size: 20px; font-weight: 500"
      >
        Vue 3
      </div>
      <c-card-meta title="Vue 3 实战课" description="60 节系统课程，附完整源码" />
    </c-card>
    <c-card style="width: 240px" :body-style="{ padding: '16px' }">
      <c-card-meta title="张三 · 前端工程师" description="3 年 Vue 经验 / 北京">
        <template #avatar>
          <div
            style="width: 48px; height: 48px; border-radius: 50%; background: var(--ccui-color-primary); color: var(--ccui-color-text-light-solid); display: flex; align-items: center; justify-content: center; font-size: 20px"
          >
            张
          </div>
        </template>
      </c-card-meta>
    </c-card>
  </div>
</template>
```

:::

## 卡片底部操作

用 default slot 内部把内容与操作行分两段；`c-divider` 隔开，操作按钮靠右是常见排版。

:::demo

```vue
<template>
  <c-card header="确认删除" style="max-width: 360px">
    <p style="margin: 0">即将删除 3 条记录，删除后无法恢复。</p>
    <c-divider style="margin: 16px 0 12px" />
    <div style="display: flex; justify-content: flex-end; gap: 8px">
      <c-button>取消</c-button>
      <c-button type="primary" danger>确认删除</c-button>
    </div>
  </c-card>
</template>
```

:::

## 悬停高亮列表

`shadow="hover"` 让卡片只在鼠标悬停时显阴影，配合列表网格做「可点击的卡片入口」效果。

:::demo

```vue
<template>
  <c-row :gutter="12">
    <c-col v-for="i in 4" :key="i" :span="6">
      <c-card shadow="hover" :header="`方案 ${i}`" :body-style="{ padding: '12px' }" style="cursor: pointer">
        <p style="margin: 0; color: var(--ccui-color-text-secondary)">点击查看详情 / 移动到上方变高亮</p>
      </c-card>
    </c-col>
  </c-row>
</template>
```

:::

## API

### Props

| 参数      | 类型                             | 默认值                | 说明                                    |
| --------- | -------------------------------- | --------------------- | --------------------------------------- |
| header    | string                           | `''`                  | 卡片标题（也可用 `header` slot 自定义） |
| bodyStyle | object                           | `{ padding: '20px' }` | 内容区样式                              |
| shadow    | `'always' \| 'hover' \| 'never'` | `'always'`            | 阴影显示时机                            |

### Slots

| 名称    | 说明         |
| ------- | ------------ |
| default | 卡片内容     |
| header  | 自定义标题区 |


---

# CardMeta 卡片元信息

> 文档链接：https://vaebe.github.io/ccui/components/card-meta/index.html

卡片元信息组件，作为独立顶层组件存在（不挂在 Card 命名空间下）。

## 何时使用

- 卡片需要展示头像 + 标题 + 描述的标准元信息布局。
- 列表项、详情卡片的头部信息块。

## 基本使用

`title` / `description` 是字符串 prop，也可以用同名 slot 完全自定义。

:::demo

```vue
<template>
  <c-card style="width: 320px">
    <c-card-meta title="人称的太阳" description="来自瑞典斯德哥尔摩的乐队 Mando Diao" />
  </c-card>
</template>
```

:::

## 带头像

`avatar` slot 用于左侧头像。

:::demo

```vue
<template>
  <c-card style="width: 320px">
    <c-card-meta title="Mando Diao" description="瑞典摇滚乐队">
      <template #avatar>
        <c-avatar name="MD" :width="48" :height="48" />
      </template>
    </c-card-meta>
  </c-card>
</template>
```

:::

## title / description slot

需要标题旁带图标或描述里带富文本时用 slot。

:::demo

```vue
<template>
  <c-card style="width: 360px">
    <c-card-meta>
      <template #title>
        <span>🔥 限时活动</span>
      </template>
      <template #description>
        <span>距结束还有 <b style="color: #f5222d">3 小时</b></span>
      </template>
    </c-card-meta>
  </c-card>
</template>
```

:::

## CardMeta 参数

| 参数        | 类型   | 默认 | 说明                  |
| ----------- | ------ | ---- | --------------------- |
| title       | string | ''   | 标题文字（slot 优先） |
| description | string | ''   | 描述文字（slot 优先） |

## CardMeta 插槽

| 插槽名      | 说明       |
| ----------- | ---------- |
| avatar      | 左侧头像区 |
| title       | 标题区     |
| description | 描述区     |


---

# Carousel 走马灯

> 文档链接：https://vaebe.github.io/ccui/components/carousel/index.html

旋转切换图像或卡片的容器组件。支持自动播放、循环、四向指示器、`scrollx` / `fade` 两种切换效果、前后切换箭头、键盘导航和触摸滑动手势。当一组同等内容需要在水平方向轮播展示时使用。

## 基本使用

每个直接子节点会被当作一帧，`Carousel` 自动渲染指示器。

:::demo

```vue
<template>
  <c-carousel style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">第 1 帧</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">第 2 帧</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">第 3 帧</div>
  </c-carousel>
</template>
```

:::

## 自动播放

`autoplay` 开启自动播放，`autoplay-speed` 控制间隔。

:::demo

```vue
<template>
  <c-carousel autoplay :autoplay-speed="2000" style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">A</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">B</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">C</div>
  </c-carousel>
</template>
```

:::

## 悬停暂停

配合 `autoplay` 启用 `pause-on-hover`，鼠标移入时挂起轮播计时器，移出后立即恢复。常用于「Banner / 推荐位」让用户可以从容查看当前帧内容。

:::demo

```vue
<template>
  <c-carousel autoplay pause-on-hover :autoplay-speed="1500" style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">
      鼠标移入即暂停 1
    </div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">
      鼠标移入即暂停 2
    </div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">
      鼠标移入即暂停 3
    </div>
  </c-carousel>
</template>
```

:::

## 多卡片展示（slidesToShow）

`slides-to-show` 让一次显示多张帧，常用于商品卡片墙 / 头像列表横向轮播。当 `total <= slidesToShow` 时只渲染 1 个指示器。

:::demo

```vue
<template>
  <c-carousel :slides-to-show="3" arrows style="height: 140px">
    <div
      v-for="i in 6"
      :key="i"
      :style="{
        height: '140px',
        margin: '0 6px',
        borderRadius: '8px',
        background: '#f0f5ff',
        color: '#1677ff',
        textAlign: 'center',
        lineHeight: '140px',
        fontSize: '20px',
      }"
    >
      商品 {{ i }}
    </div>
  </c-carousel>
</template>
```

:::

## 一次滚动多张（slidesToScroll）

搭配 `slides-to-show` 一起使用，`slides-to-scroll` 控制 next/prev/autoplay 每次推进的步幅。下例每屏 3 张、每次切 2 张，常用于「成组翻页」式横向列表。

:::demo

```vue
<template>
  <c-carousel :slides-to-show="3" :slides-to-scroll="2" autoplay :autoplay-speed="2000" style="height: 140px">
    <div
      v-for="i in 8"
      :key="i"
      :style="{
        height: '140px',
        margin: '0 6px',
        borderRadius: '8px',
        background: i % 2 ? '#fff7e6' : '#fff1f0',
        color: '#d4380d',
        textAlign: 'center',
        lineHeight: '140px',
        fontSize: '20px',
      }"
    >
      卡片 {{ i }}
    </div>
  </c-carousel>
</template>
```

:::

## 指示器位置

`dot-position` 支持 `top` / `bottom`（默认）/ `left` / `right`。

:::demo

```vue
<template>
  <c-carousel dot-position="top" style="height: 140px">
    <div style="height: 140px; background: #1677ff; color: #fff; line-height: 140px; text-align: center">top</div>
    <div style="height: 140px; background: #36ad6a; color: #fff; line-height: 140px; text-align: center">top</div>
  </c-carousel>
  <c-carousel dot-position="left" style="height: 140px; margin-top: 16px">
    <div style="height: 140px; background: #1677ff; color: #fff; line-height: 140px; text-align: center">left</div>
    <div style="height: 140px; background: #36ad6a; color: #fff; line-height: 140px; text-align: center">left</div>
  </c-carousel>
</template>
```

:::

## 渐隐切换

`effect="fade"` 用透明度做切换，适合海报类内容。

:::demo

```vue
<template>
  <c-carousel effect="fade" autoplay :autoplay-speed="2500" style="height: 160px">
    <div style="height: 160px; background: linear-gradient(135deg, #1677ff, #69c0ff)" />
    <div style="height: 160px; background: linear-gradient(135deg, #36ad6a, #95de64)" />
    <div style="height: 160px; background: linear-gradient(135deg, #f7b500, #ffd666)" />
  </c-carousel>
</template>
```

:::

## 前后切换箭头

`arrows` 显示左右切换箭头。配合 `infinite="false"` 在边界停住。

:::demo

```vue
<template>
  <c-carousel arrows :infinite="false" style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">1</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">2</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">3</div>
  </c-carousel>
</template>
```

:::

## 触摸滑动

默认启用 swipe 手势（`swipeable`），左右滑动切换帧。`swipe-threshold` 控制触发阈值（默认 40px）。

:::demo

```vue
<template>
  <c-carousel style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">
      ← 左滑下一帧 / 右滑上一帧 →
    </div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">B</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">C</div>
  </c-carousel>
</template>
```

:::

## 自定义指示器

通过 `customDot` 作用域插槽自定义每个指示器的渲染内容，接收 `{ index, isActive }`。

:::demo

```vue
<template>
  <c-carousel style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">1</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">2</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">3</div>
    <template #customDot="{ index, isActive }">
      <span
        :style="{
          display: 'inline-block',
          width: '20px',
          height: '20px',
          borderRadius: '50%',
          background: isActive ? '#1677ff' : 'rgba(0,0,0,0.15)',
          cursor: 'pointer',
          transition: 'background 0.3s',
        }"
      >
        {{ index + 1 }}
      </span>
    </template>
  </c-carousel>
</template>
```

:::

## 受控模式

通过 `v-model` 接管激活索引，外部按钮也能驱动跳转。

:::demo

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

const active = ref(0)
</script>

<template>
  <c-carousel v-model="active" style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">0</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">1</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">2</div>
  </c-carousel>
  <div style="margin-top: 12px; display: flex; gap: 8px">
    <c-button @click="active = (active + 2) % 3">上一帧</c-button>
    <c-button @click="active = (active + 1) % 3">下一帧</c-button>
    <c-button @click="active = 0">回到首帧</c-button>
  </div>
</template>
```

:::

## 命令式调用

通过模板 ref 拿到 `next` / `prev` / `goTo` 三个方法，做更复杂的外部联动。

:::demo

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

const carouselRef = ref<{
  next: () => void
  prev: () => void
  goTo: (i: number, dontAnimate?: boolean) => void
} | null>(null)
</script>

<template>
  <c-carousel ref="carouselRef" style="height: 160px">
    <div style="height: 160px; background: #1677ff; color: #fff; line-height: 160px; text-align: center">A</div>
    <div style="height: 160px; background: #36ad6a; color: #fff; line-height: 160px; text-align: center">B</div>
    <div style="height: 160px; background: #f7b500; color: #fff; line-height: 160px; text-align: center">C</div>
  </c-carousel>
  <div style="margin-top: 12px; display: flex; gap: 8px">
    <c-button @click="carouselRef?.prev()">prev()</c-button>
    <c-button @click="carouselRef?.next()">next()</c-button>
    <c-button @click="carouselRef?.goTo(2, true)">goTo(2, true)</c-button>
  </div>
</template>
```

:::

## API

### Props

| 参数           | 类型                                     | 默认值      | 说明                                               |
| -------------- | ---------------------------------------- | ----------- | -------------------------------------------------- |
| modelValue     | number                                   | --          | 当前激活索引，支持 `v-model`；不传则非受控         |
| defaultActive  | number                                   | `0`         | 非受控初始索引                                     |
| autoplay       | boolean                                  | `false`     | 是否自动播放                                       |
| autoplaySpeed  | number                                   | `3000`      | 自动播放间隔（毫秒）                               |
| dots           | boolean                                  | `true`      | 是否显示指示器                                     |
| dotPosition    | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'`  | 指示器位置                                         |
| effect         | `'scrollx' \| 'fade'`                    | `'scrollx'` | 切换动效。`scrollx` 横向位移；`fade` 透明度交替    |
| infinite       | boolean                                  | `true`      | 是否循环；末尾点 next 回到 0、首位点 prev 跳到末尾 |
| arrows         | boolean                                  | `false`     | 是否显示前后切换箭头                               |
| pauseOnHover   | boolean                                  | `false`     | autoplay 模式下鼠标 hover 是否暂停                 |
| slidesToShow   | number                                   | `1`         | 一次展示几张幻灯片，仅 `effect='scrollx'` 生效     |
| slidesToScroll | number                                   | `1`         | 一次切换几张幻灯片，仅 `effect='scrollx'` 生效     |
| duration       | number                                   | `500`       | 切换动画时长（毫秒），同时控制 transition-duration |
| swipeable      | boolean                                  | `true`      | 是否启用触摸/指针 swipe 手势                       |
| swipeThreshold | number                                   | `40`        | swipe 触发阈值（像素），滑动距离超过此值才切换     |

### Events

| 事件名            | 回调签名                          | 触发时机                    |
| ----------------- | --------------------------------- | --------------------------- |
| update:modelValue | `(value: number)`                 | 切换时（受控/非受控均触发） |
| change            | `(current: number, prev: number)` | 实际切换帧时（动画开始）    |
| afterChange       | `(current: number)`               | 切换动画结束后              |

### Slots

| 插槽名    | 作用域                                 | 说明                                   |
| --------- | -------------------------------------- | -------------------------------------- |
| default   | --                                     | 每个直接子节点作为一帧                 |
| customDot | `{ index: number, isActive: boolean }` | 自定义每个指示器内容，点击外层 li 跳转 |

### Exposed methods

| 方法            | 签名                                             | 说明                                      |
| --------------- | ------------------------------------------------ | ----------------------------------------- |
| next            | `() => void`                                     | 切到下一帧（受 `infinite` 影响）          |
| prev            | `() => void`                                     | 切到上一帧（受 `infinite` 影响）          |
| goTo            | `(index: number, dontAnimate?: boolean) => void` | 跳到指定索引；`dontAnimate=true` 跳过动画 |
| getCurrentIndex | `() => number`                                   | 获取当前激活索引                          |

### 键盘导航

组件容器 `tabindex=0`，聚焦后可用以下按键：

| 按键                   | 操作         |
| ---------------------- | ------------ |
| ArrowRight / ArrowDown | 切到下一帧   |
| ArrowLeft / ArrowUp    | 切到上一帧   |
| Home                   | 跳到第一帧   |
| End                    | 跳到最后一帧 |

## 已知限制（未交付）

- **adaptiveHeight**：当前所有帧共用容器高度，按内容自适应留给后续。
- **responsive 断点配置**：暂未支持按断点动态切换 `slidesToShow` / `slidesToScroll`。


---

# Cascader 级联选择

> 文档链接：https://vaebe.github.io/ccui/components/cascader/index.html

多级联动选择控件。每一列展示一级选项，点击非叶子节点自动展开下一级。`v-model` 是路径数组 `[v1, v2, v3]`，输入框默认按 `separator` 拼接每级 label。

## 基本使用

`options` 是递归 `children` 的树结构，叶子节点点击后提交完整路径。

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'binjiang', label: '滨江' },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      {
        value: 'nanjing',
        label: '南京',
        children: [{ value: 'gulou', label: '鼓楼' }],
      },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" />
</template>
```

:::

## 中间节点也可选 (changeOnSelect)

`change-on-select` 让任何一级都能触发提交，面板继续保持打开直到点击叶子或点击外部关闭。

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    value: 'a',
    label: 'A',
    children: [
      { value: 'a1', label: 'A1', children: [{ value: 'a11', label: 'A1-1' }] },
      { value: 'a2', label: 'A2' },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" change-on-select />
</template>
```

:::

## 自定义字段名 (fieldNames)

如果数据源字段不叫 `label / value / children / disabled`，用 `fieldNames` 映射。

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    v: 'cn',
    l: '中国',
    kids: [
      {
        v: 'zj',
        l: '浙江',
        kids: [{ v: 'hz', l: '杭州' }],
      },
    ],
  },
]
const fieldNames = { label: 'l', value: 'v', children: 'kids' }
</script>

<template>
  <c-cascader v-model="value" :options="options" :field-names="fieldNames" />
</template>
```

:::

## 禁用某项

在选项上设 `disabled: true`，整个节点不可点击；其子树仍可通过其他路径到达。

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    value: 'a',
    label: 'A',
    children: [
      { value: 'a1', label: 'A1（可选）' },
      { value: 'a2', label: 'A2（禁用）', disabled: true, children: [{ value: 'a21', label: 'A2-1' }] },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" />
</template>
```

:::

## 自定义路径展示

`display-render` 接收 `(labels: string[], selectedOptions: CascaderOption[])`，返回想要的展示文本。

:::demo

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

const value = ref<string[] | null>(['zhejiang', 'hangzhou'])
const options = [{ value: 'zhejiang', label: '浙江', children: [{ value: 'hangzhou', label: '杭州' }] }]
const displayRender = (labels: string[]) => labels.map((l) => `「${l}」`).join('')
</script>

<template>
  <c-cascader v-model="value" :options="options" :display-render="displayRender" />
</template>
```

:::

## 三种尺寸

:::demo

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

const value = ref<string[] | null>(null)
const options = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <c-cascader v-model="value" :options="options" size="small" />
  <c-cascader v-model="value" :options="options" />
  <c-cascader v-model="value" :options="options" size="large" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive<{ region: string[] | null }>({ region: null })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { region: [{ required: true, message: '请选择地区' }] }
const options = [{ value: 'zhejiang', label: '浙江', children: [{ value: 'hangzhou', label: '杭州' }] }]
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="region" label="地区" prop="region">
      <c-cascader v-model="form.region" :options="options" />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()"> 校验 </c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

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

const value = ref<string[] | null>(null)
const options = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <c-cascader v-model="value" :options="options" popup-append-to-body />
</template>
```

:::

## hover 触发

`expand-trigger="hover"` 时，鼠标移到非叶子节点即展开下一列；hover 不触发 emit。

:::demo

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

const value = ref([])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" expand-trigger="hover" />
</template>
```

:::

## showSearch 搜索

`show-search` 时 input 可输入，面板换成扁平匹配列表；默认按 label includes 匹配，传 `{ filter }` 可自定义。

:::demo

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

const value = ref([])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京', children: [{ value: 'gulou', label: '鼓楼' }] }],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" show-search />
</template>
```

:::

## 搜索结果上限与排序 showSearch.limit / sort

`show-search` 还支持 `limit`（命中数上限，默认 `50`，超出后只渲染前 N 条）和 `sort`（命中结果排序器，签名同 `Array.sort` 比较器但多接 `input`）。例如「按命中节点 label 长度优先短的」帮助用户先看到精确匹配。

:::demo

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

const value = ref([])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
  { value: 'jiangsu', label: '江苏', children: [{ value: 'nanjing', label: '南京' }] },
]

// 业务：客服工单只展示 8 条候选避免视觉过载，命中末级 label 短的优先
const showSearch = {
  limit: 8,
  sort: (a: { label: string }[], b: { label: string }[]) => a[a.length - 1].label.length - b[b.length - 1].label.length,
}
</script>

<template>
  <c-cascader v-model="value" :options="options" :show-search="showSearch" placeholder="搜地名（最多 8 条）" />
</template>
```

:::

## loadData 异步加载

非叶子节点用 `isLeaf: false` 显式标记，配合 `loadData` 在展开时拉取 children；加载中显示 `⟳`。

:::demo

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

const value = ref([])
const options = reactive([
  { value: 'a', label: '根 A', isLeaf: false },
  { value: 'b', label: '根 B', isLeaf: false },
])

function loadData(path) {
  return new Promise<void>((resolve) => {
    setTimeout(() => {
      const target = path[path.length - 1]
      target.children = [
        { value: `${target.value}-1`, label: `${target.label} 子 1` },
        { value: `${target.value}-2`, label: `${target.label} 子 2` },
      ]
      target.isLeaf = undefined
      resolve()
    }, 800)
  })
}
</script>

<template>
  <c-cascader v-model="value" :options="options" :load-data="loadData" />
</template>
```

:::

## 空数据占位 notFoundContent

`options` 为空时显示自定义文案；不传则取 ConfigProvider locale（默认中文「暂无数据」）。

:::demo

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

const value = ref([])
</script>

<template>
  <c-cascader v-model="value" :options="[]" not-found-content="🙈 当前角色无任何可分配的部门" />
</template>
```

:::

## 校验状态 status

`status` 支持 `'error'` / `'warning'` / `'success'` / `'validating'`，置于 `<c-form-item>` 时会自动继承。

:::demo

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

const v1 = ref(null)
const v2 = ref(null)
const v3 = ref(null)
const options = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 300px">
    <c-cascader v-model="v1" :options="options" status="error" placeholder="error" />
    <c-cascader v-model="v2" :options="options" status="warning" placeholder="warning" />
    <c-cascader v-model="v3" :options="options" status="success" placeholder="success" />
  </div>
</template>
```

:::

## 不可清除 clearable=false

锁定已选路径，避免误清除。常用于「填了就不能撤」的关键字段（如归属部门）。

:::demo

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

const value = ref(['zhejiang', 'hangzhou'])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [{ value: 'hangzhou', label: '杭州' }],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" :clearable="false" />
</template>
```

:::

## 浮层方位 placement

`placement` 控制浮层四向起点，配合 `popup-append-to-body` 解决滚动容器内裁切。

:::demo

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

const v1 = ref(null)
const v2 = ref(null)
const v3 = ref(null)
const v4 = ref(null)
const options = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <div style="display: flex; gap: 12px; flex-wrap: wrap">
    <c-cascader v-model="v1" :options="options" placement="bottomLeft" placeholder="bottomLeft（默认）" />
    <c-cascader v-model="v2" :options="options" placement="bottomRight" placeholder="bottomRight" />
    <c-cascader v-model="v3" :options="options" placement="topLeft" placeholder="topLeft" />
    <c-cascader v-model="v4" :options="options" placement="topRight" placeholder="topRight" />
  </div>
</template>
```

:::

## 自定义展开图标 expandIcon + 自动聚焦

`expandIcon` 替换默认 `›`；`autoFocus` 让组件挂载后立即聚焦输入框，常用于「打开弹窗后第一个表单项」场景。

:::demo

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

const v1 = ref(null)
const v2 = ref(null)
const options = [
  { value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] },
  { value: 'b', label: 'B', children: [{ value: 'b1', label: 'B1' }] },
]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 300px">
    <c-cascader v-model="v1" :options="options" expand-icon="→" placeholder="自定义箭头 →" />
    <c-cascader v-model="v2" :options="options" auto-focus placeholder="autoFocus 自动聚焦" />
  </div>
</template>
```

:::

## multiple 多选

`multiple` 时叶子节点渲染 checkbox，勾选聚合写入；input wrap 展示 tag，点 × 移除。`modelValue` 变 `CascaderValuePath[]`。

:::demo

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

const value = ref([['zhejiang', 'hangzhou', 'xihu']])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'binjiang', label: '滨江' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" multiple placeholder="多选城市" />
  <p style="margin-top: 8px">v-model: {{ value }}</p>
</template>
```

:::

## tag 折叠 maxTagCount / max-tag-placeholder

多选超出 `max-tag-count` 时，多余 tag 折叠为「+N」摘要；`#max-tag-placeholder` slot 接 `{ omittedValues }` 可自定义折叠文案。常用于一行 input 容纳不下的勾选列表场景（如「批量推送地区」表单字段）。

:::demo

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

const cities = ref<Array<Array<string>>>([
  ['zhejiang', 'hangzhou', 'xihu'],
  ['zhejiang', 'hangzhou', 'binjiang'],
  ['zhejiang', 'ningbo', 'haishu'],
  ['jiangsu', 'nanjing', 'gulou'],
])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'binjiang', label: '滨江' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京', children: [{ value: 'gulou', label: '鼓楼' }] }],
  },
]
</script>

<template>
  <c-cascader v-model="cities" :options="options" multiple :max-tag-count="2" placeholder="批量推送地区">
    <template #max-tag-placeholder="{ omittedValues }"> 还有 {{ omittedValues.length }} 个地区 </template>
  </c-cascader>
</template>
```

:::

## tag 文本截断 maxTagTextLength

`max-tag-text-length` 限制单个 tag 显示的最大字符数，超出末尾以 `…` 截断。适合「行政区全名过长」「角色名缩写」等场景。

:::demo

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

const value = ref([
  ['org', 'tech-platform-group-supply-chain'],
  ['org', 'customer-success-international-team'],
])
const options = [
  {
    value: 'org',
    label: '组织',
    children: [
      { value: 'tech-platform-group-supply-chain', label: '技术平台部供应链组' },
      { value: 'customer-success-international-team', label: '客户成功国际化小组' },
    ],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" multiple :max-tag-text-length="6" placeholder="选择团队" />
</template>
```

:::

## 键盘导航

输入框聚焦时可全键盘操作：

- 关闭状态下：`Enter` / `Space` / `↓` 打开面板
- 打开状态下：`Esc` / `Tab` 关闭面板
- 列模式：`↑ ↓` 在当前列移动 focus / `→` 在非叶子上展开下一列 / `←` 回到上一列 / `Enter` 选中
- 搜索模式：`↑ ↓` 在结果列表移动 / `Enter` 选中

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'binjiang', label: '滨江' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [{ value: 'nanjing', label: '南京', children: [{ value: 'gulou', label: '鼓楼' }] }],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" placeholder="试试 Enter / 方向键 / Esc" />
</template>
```

:::

## 自定义选项渲染 #option slot

`#option` slot 接 `{ option, path, index }`，替换列内每个 option 的 label 渲染区，可加图标、徽标、说明文字等。适合「显示部门 + 在编人数」「带状态点的地区列表」。

:::demo

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

interface Dept {
  value: string
  label: string
  staff?: number
  children?: Dept[]
}

const value = ref<string[] | null>(null)
const options: Dept[] = [
  {
    value: 'tech',
    label: '技术中心',
    staff: 320,
    children: [
      { value: 'frontend', label: '前端', staff: 28 },
      { value: 'backend', label: '后端', staff: 64 },
    ],
  },
  {
    value: 'sales',
    label: '销售中心',
    staff: 180,
    children: [{ value: 'enterprise', label: '企业销售', staff: 42 }],
  },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" placeholder="选择部门">
    <template #option="{ option }">
      <span style="display: inline-flex; align-items: center; gap: 8px">
        <span>{{ option.label }}</span>
        <span v-if="option.staff" style="font-size: 12px; color: var(--ccui-color-text-tertiary)">{{ option.staff }} 人</span>
      </span>
    </template>
  </c-cascader>
</template>
```

:::

## 自定义面板容器 #popup slot

`#popup` slot 包裹整个 popup 内容，scope 暴露 `default()` 用于渲染默认面板（列 / 搜索结果）。常用于在面板顶部追加标题 / 操作条、底部追加说明。

:::demo

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

const value = ref<string[] | null>(null)
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  { value: 'jiangsu', label: '江苏', children: [{ value: 'nanjing', label: '南京' }] },
]
</script>

<template>
  <c-cascader v-model="value" :options="options" placeholder="选择派送区域">
    <template #popup="{ default: defaultPopup }">
      <div style="padding: 8px 12px; border-bottom: 1px solid var(--ccui-color-border-secondary); font-size: 12px; color: var(--ccui-color-text-tertiary)">
        派送区域影响时效与运费
      </div>
      <component :is="defaultPopup" />
    </template>
  </c-cascader>
</template>
```

:::

## 自定义搜索结果 #search-option slot

`#search-option` 接 `{ option, path, query }`，控制搜索面板内每条结果的渲染。常配合 `query` 做命中关键字高亮。

:::demo

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

const value = ref([])
const options = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖' },
          { value: 'binjiang', label: '滨江' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙' }] },
    ],
  },
  { value: 'jiangsu', label: '江苏', children: [{ value: 'nanjing', label: '南京' }] },
]

// 把 label 切成 [{ text, match }] 段；用 <mark> 渲染命中段、文本节点渲染其它段。
// 不要直接 v-html 拼字符串——一旦 label 是服务端返回的不可信值就会变 XSS。
function splitForHighlight(label: string, q: string) {
  if (!q) return [{ text: label, match: false }]
  const idx = label.indexOf(q)
  if (idx < 0) return [{ text: label, match: false }]
  return [
    { text: label.slice(0, idx), match: false },
    { text: q, match: true },
    { text: label.slice(idx + q.length), match: false },
  ]
}
</script>

<template>
  <c-cascader v-model="value" :options="options" show-search placeholder="输入「江」试试高亮">
    <template #search-option="{ path, query }">
      <span>
        <template v-for="(node, i) in path" :key="i">
          <span v-if="i > 0"> / </span>
          <template v-for="(seg, j) in splitForHighlight(node.label, query)" :key="j">
            <mark v-if="seg.match">{{ seg.text }}</mark>
            <template v-else>{{ seg.text }}</template>
          </template>
        </template>
      </span>
    </template>
  </c-cascader>
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-cascader v-model="value" :variant="variant" :options="opts" placeholder="请选择" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref([])
const opts = [
  {
    label: '浙江',
    value: 'zj',
    children: [
      { label: '杭州', value: 'hz' },
      { label: '宁波', value: 'nb' },
    ],
  },
  { label: '江苏', value: 'js', children: [{ label: '南京', value: 'nj' }] },
]
</script>
```

:::

## API

### Props

| 参数              | 类型                                                       | 默认值               | 说明                                                          |
| ----------------- | ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------- |
| modelValue        | `(string \| number)[] \| (string \| number)[][] \| null`   | --                   | 单选：路径数组；多选：路径数组的数组                          |
| options           | `CascaderOption[]`                                         | `[]`                 | 数据源（递归 children）                                       |
| fieldNames        | `{ label?, value?, children?, disabled? }`                 | `{}`                 | 字段名映射                                                    |
| placeholder       | string                                                     | `请选择`             | 占位文案                                                      |
| separator         | string                                                     | `/`                  | 默认 displayRender 的拼接符                                   |
| displayRender     | `(labels, selectedOptions) => string`                      | --                   | 自定义路径展示                                                |
| changeOnSelect    | boolean                                                    | `false`              | 中间节点也可选并提交                                          |
| disabled          | boolean                                                    | `false`              | 是否禁用                                                      |
| clearable         | boolean                                                    | `true`               | 是否显示清除按钮                                              |
| size              | `'small' \| 'default' \| 'large'`                          | `'default'`          | 输入框尺寸                                                    |
| status            | `'' \| 'error' \| 'warning' \| ...`                        | `''`                 | 校验状态；置于 `FormItem` 时自动继承                          |
| placement         | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`       | 浮层方位                                                      |
| popupClassName    | string                                                     | --                   | 浮层根元素自定义 class                                        |
| popupAppendToBody | boolean                                                    | `false`              | 是否把浮层 Teleport 到 `document.body`                        |
| getPopupContainer | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                   | 自定义浮层挂载点                                              |
| autoFocus         | boolean                                                    | `false`              | 挂载后自动 focus 输入框                                       |
| inputReadOnly     | boolean                                                    | `true`               | 输入框只读                                                    |
| transitionName    | string                                                     | `ccui-cascader-fade` | 浮层过渡名                                                    |
| expandIcon        | string                                                     | `›`                  | 非叶子节点的展开图标                                          |
| notFoundContent   | string                                                     | `暂无数据`           | 空数据文案                                                    |
| expandTrigger     | `'click' \| 'hover'`                                       | `'click'`            | 列展开触发方式                                                |
| multiple          | boolean                                                    | `false`              | 多选模式，modelValue 类型变为路径数组的数组                   |
| maxTagCount       | number                                                     | `0`                  | 多选时 tag 最多显示数，超出折叠为「+N」摘要；0 表示不折叠     |
| maxTagTextLength  | number                                                     | `0`                  | 单个 tag 显示的最大字符数，超出末尾以 `…` 截断；0 不截断      |
| showSearch        | `boolean \| { filter?, sort?, limit? }`                    | `false`              | 启用搜索；对象形态支持 `filter` / `sort` / `limit`（默认 50） |
| loadData          | `(path: CascaderOption[]) => Promise<void> \| void`        | --                   | 异步加载非叶子 children；option 用 `isLeaf:false` 显式标记    |

### Events

| 事件名               | 回调签名                                     | 触发时机                           |
| -------------------- | -------------------------------------------- | ---------------------------------- |
| update:modelValue    | `(value: (string \| number)[] \| null)`      | 路径提交或清除时                   |
| change               | `(value, selectedOptions: CascaderOption[])` | 路径提交或清除时（带原始节点路径） |
| popup-visible-change | `(open: boolean)`                            | 浮层打开 / 关闭时                  |
| focus                | --                                           | 输入框聚焦                         |
| blur                 | --                                           | 输入框失焦                         |

### Slots

| 名称                | scope                                    | 说明                                            |
| ------------------- | ---------------------------------------- | ----------------------------------------------- |
| option              | `{ option, path, index }`                | 自定义列内 option 渲染                          |
| popup               | `{ default: () => VNode }`               | 包裹整个浮层内容；调用 `default()` 渲染默认面板 |
| search-option       | `{ option, path, query }`                | 自定义搜索结果项渲染                            |
| max-tag-placeholder | `{ omittedValues: CascaderValuePath[] }` | 多选 `maxTagCount` 折叠摘要 tag 内容            |
| expandIcon          | `{ item, level }`                        | 非叶子节点展开箭头                              |
| suffixIcon          | --                                       | 输入框后缀图标                                  |
| clearIcon           | --                                       | 清除按钮图标                                    |
| removeIcon          | --                                       | 多选 tag 删除图标                               |

## 顶层常量

`showCheckedStrategy` 的取值常量：**不挂命名空间**，从 `@vaebe/ccui` 顶层 export。

```ts
import { CASCADER_SHOW_CHILD, CASCADER_SHOW_PARENT } from '@vaebe/ccui'

// CASCADER_SHOW_CHILD === 'SHOW_CHILD'
// CASCADER_SHOW_PARENT === 'SHOW_PARENT'
```

| 常量                 | 说明                                                             |
| -------------------- | ---------------------------------------------------------------- |
| CASCADER_SHOW_CHILD  | `showCheckedStrategy` 取值：只输出最末级叶子节点（默认）         |
| CASCADER_SHOW_PARENT | `showCheckedStrategy` 取值：父节点全部子节点都选中时只输出父节点 |

> 当前 Cascader 尚未接入 `showCheckedStrategy` 这条 API；常量先 export 出去，方便外部代码提前引用，待后续接入实际逻辑时直接对接。

## 已知限制（未交付）

- **showCheckedStrategy**：multiple 模式下当前为「all」语义（每条勾选路径独立提交），未提供 `parent` / `child` 折叠策略。常量符号已顶层 export，未来接入实际逻辑后即可直接使用。


---

# CheckBox 多选框

> 文档链接：https://vaebe.github.io/ccui/components/check-box/index.html

在一组备选项中可选多个。

## 何时使用

- 在一组选项中进行多项选择。
- 单独使用时表示"是 / 否"两态切换。

## 基本使用

`v-model` 直接绑定布尔值，默认插槽是右侧文字。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const checked = ref(true)
</script>

<template>
  <c-check-box v-model="checked">这是一个多选框</c-check-box>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前：{{ checked ? '选中' : '未选中' }}</p>
</template>
```

:::

## 用 label 属性显示文字

不写默认插槽时，`label` 属性直接作为说明文字。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(false)
const b = ref(true)
</script>

<template>
  <c-check-box v-model="a" label="使用 label 作为文案" />
  <c-check-box v-model="b" label="另一个" />
</template>
```

:::

## 禁用

`disabled` 让选项不可切换。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(true)
const b = ref(false)
</script>

<template>
  <c-check-box v-model="a" disabled>禁用且选中</c-check-box>
  <c-check-box v-model="b" disabled>禁用未选</c-check-box>
</template>
```

:::

## 自定义颜色

`color` 改变选中态色块（与品牌色冲突时常用，如警示型业务）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(true)
const b = ref(true)
const c = ref(true)
</script>

<template>
  <c-check-box v-model="a" color="#52c41a">绿色</c-check-box>
  <c-check-box v-model="b" color="#fa541c">橙色</c-check-box>
  <c-check-box v-model="c" color="#722ed1">紫色</c-check-box>
</template>
```

:::

## 多选框组

`<c-check-box-group>` 把一组 CheckBox 放进同一个数组 `v-model`。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const cities = ref(['shanghai'])
</script>

<template>
  <c-check-box-group v-model="cities">
    <c-check-box label="beijing">北京</c-check-box>
    <c-check-box label="shanghai">上海</c-check-box>
    <c-check-box label="guangzhou">广州</c-check-box>
    <c-check-box label="shenzhen">深圳</c-check-box>
  </c-check-box-group>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">已选：{{ cities.join(', ') || '（空）' }}</p>
</template>
```

:::

## 排列方向

`direction` 切换纵向（默认）/ 横向。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref([])
const b = ref([])
</script>

<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">column（默认）</p>
  <c-check-box-group v-model="a" direction="column">
    <c-check-box label="1">选项 1</c-check-box>
    <c-check-box label="2">选项 2</c-check-box>
    <c-check-box label="3">选项 3</c-check-box>
  </c-check-box-group>

  <p style="color: var(--ccui-color-text-secondary); margin: 16px 0 4px">row</p>
  <c-check-box-group v-model="b" direction="row">
    <c-check-box label="1">选项 1</c-check-box>
    <c-check-box label="2">选项 2</c-check-box>
    <c-check-box label="3">选项 3</c-check-box>
  </c-check-box-group>
</template>
```

:::

## 整组禁用 / 整组着色

在 group 上设置 `disabled` 或 `color` 一次性应用到组内所有项。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(['1', '2'])
const b = ref(['1'])
</script>

<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">整组禁用</p>
  <c-check-box-group v-model="a" disabled direction="row">
    <c-check-box label="1">选项 1</c-check-box>
    <c-check-box label="2">选项 2</c-check-box>
    <c-check-box label="3">选项 3</c-check-box>
  </c-check-box-group>

  <p style="color: var(--ccui-color-text-secondary); margin: 16px 0 4px">整组改颜色</p>
  <c-check-box-group v-model="b" color="#fa541c" direction="row">
    <c-check-box label="1">选项 1</c-check-box>
    <c-check-box label="2">选项 2</c-check-box>
    <c-check-box label="3">选项 3</c-check-box>
  </c-check-box-group>
</template>
```

:::

## 切换前钩子

group 的 `before-change` 接收 `(isChecked, label)`，返回 `false` 阻止本次操作。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref(['a'])
const log = ref('（无）')

function beforeChange(isChecked, label) {
  log.value = `${isChecked ? '尝试选中' : '尝试取消'} "${label}"`
  if (label === 'locked') {
    log.value += ' → 被钩子拦截'
    return false
  }
  return true
}
</script>

<template>
  <c-check-box-group v-model="v" :before-change="beforeChange" direction="row">
    <c-check-box label="a">A</c-check-box>
    <c-check-box label="b">B</c-check-box>
    <c-check-box label="locked">锁定项（被禁切换）</c-check-box>
  </c-check-box-group>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">日志：{{ log }}</p>
</template>
```

:::

## API

### CheckBox Props

| 参数         | 类型                                                             | 默认值  | 说明                                                    |
| ------------ | ---------------------------------------------------------------- | ------- | ------------------------------------------------------- |
| modelValue   | boolean                                                          | —       | 必选，单独使用时绑定布尔；group 内由 group 接管         |
| label        | `string \| number \| boolean`                                    | —       | 单独使用且无插槽时作为文案；与 group 配合时作为本项的值 |
| disabled     | boolean                                                          | `false` | 是否禁用                                                |
| color        | string                                                           | —       | 自定义选中色                                            |
| beforeChange | `(isChecked: boolean, v: string) => boolean \| Promise<boolean>` | —       | 切换前的钩子                                            |

### CheckBox Events

| 事件   | 回调签名           | 说明         |
| ------ | ------------------ | ------------ |
| change | `(value: boolean)` | 值改变时触发 |

### CheckBoxGroup Props

| 参数         | 类型                                                             | 默认值     | 说明                       |
| ------------ | ---------------------------------------------------------------- | ---------- | -------------------------- |
| modelValue   | `Array<string \| number>`                                        | `[]`       | 已选项数组，支持 `v-model` |
| disabled     | boolean                                                          | `false`    | 整组禁用                   |
| color        | string                                                           | —          | 整组的选中色               |
| direction    | `'row' \| 'column'`                                              | `'column'` | 排列方向                   |
| beforeChange | `(isChecked: boolean, v: string) => boolean \| Promise<boolean>` | —          | 切换前的钩子               |

### CheckBoxGroup Events

| 事件   | 回调签名             | 说明             |
| ------ | -------------------- | ---------------- |
| change | `(values: string[])` | 选中项改变时触发 |

### Slots

| 名称    | 说明           |
| ------- | -------------- |
| default | 多选框右侧文本 |


---

# CheckableTag 可勾选标签

> 文档链接：https://vaebe.github.io/ccui/components/checkable-tag/index.html

可勾选切换的标签，作为独立顶层组件存在（不挂在 Tag 命名空间下）。配套 `CheckableTagGroup` 容器组件支持多选。

## 何时使用

- 需要标签形态的开关 / 多选筛选（如话题标签、兴趣分类）。
- 替代 Checkbox 的轻量场景。

## 单独使用

`v-model:checked` 受控；点击 / Space / Enter 切换。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const checked = ref(false)
    return { checked }
  },
})
</script>

<template>
  <c-checkable-tag v-model:checked="checked">前端</c-checkable-tag>
  <span style="margin-left: 16px">当前：{{ checked ? '已选' : '未选' }}</span>
</template>
```

:::

## 多选 group（options 模式）

`CheckableTagGroup` 配合 `options` 声明式渲染。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const selected = ref(['vue'])
    const options = [
      { label: 'Vue', value: 'vue' },
      { label: 'React', value: 'react' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid', disabled: true },
    ]
    return { selected, options }
  },
})
</script>

<template>
  <c-checkable-tag-group v-model="selected" :options="options" />
  <div style="margin-top: 8px">已选：{{ selected.join(', ') || '空' }}</div>
</template>
```

:::

## 多选 group（默认 slot 模式）

也可以在默认 slot 里直接放 `<c-checkable-tag :value="...">`，由 group 自动接管勾选状态。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const selected = ref([])
    return { selected }
  },
})
</script>

<template>
  <c-checkable-tag-group v-model="selected">
    <c-checkable-tag value="cn">中国</c-checkable-tag>
    <c-checkable-tag value="us">美国</c-checkable-tag>
    <c-checkable-tag value="jp">日本</c-checkable-tag>
  </c-checkable-tag-group>
</template>
```

:::

## 最大勾选数

`maxCount` 达到上限后未勾选项的 click 被忽略；已勾选项仍可取消。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const selected = ref([])
    const options = [
      { label: 'A', value: 'a' },
      { label: 'B', value: 'b' },
      { label: 'C', value: 'c' },
      { label: 'D', value: 'd' },
    ]
    return { selected, options }
  },
})
</script>

<template>
  <c-checkable-tag-group v-model="selected" :options="options" :max-count="2" />
  <div style="margin-top: 8px">最多 2 个：{{ selected.join(', ') || '空' }}</div>
</template>
```

:::

## 禁用整个 group

:::demo

```vue
<template>
  <c-checkable-tag-group
    :model-value="['a']"
    :options="[
      { label: 'A', value: 'a' },
      { label: 'B', value: 'b' },
    ]"
    disabled
  />
</template>
```

:::

## 尺寸

:::demo

```vue
<template>
  <c-checkable-tag-group
    size="large"
    :options="[
      { label: '大', value: '1' },
      { label: '号', value: '2' },
    ]"
  />
  <c-checkable-tag-group
    :options="[
      { label: '默', value: '1' },
      { label: '认', value: '2' },
    ]"
    style="margin-top: 8px"
  />
  <c-checkable-tag-group
    size="small"
    :options="[
      { label: '小', value: '1' },
      { label: '号', value: '2' },
    ]"
    style="margin-top: 8px"
  />
</template>
```

:::

## CheckableTag 参数

| 参数     | 类型             | 默认  | 说明                                        |
| -------- | ---------------- | ----- | ------------------------------------------- |
| checked  | boolean          | --    | 受控勾选状态；group 模式下由 group 注入决定 |
| value    | string \| number | --    | group 模式下匹配 group 的 modelValue        |
| disabled | boolean          | false | 是否禁用                                    |

## CheckableTag 事件

| 事件名         | 参数    | 说明                                |
| -------------- | ------- | ----------------------------------- |
| update:checked | boolean | v-model:checked（仅独立使用时触发） |
| change         | boolean | 状态切换（仅独立使用时触发）        |

## CheckableTag 插槽

| 插槽名  | 说明         |
| ------- | ------------ |
| default | 标签文本内容 |

## CheckableTagGroup 参数

| 参数       | 类型                            | 默认    | 说明                                        |
| ---------- | ------------------------------- | ------- | ------------------------------------------- |
| modelValue | (string \| number)[]            | []      | 已勾选值列表（v-model）                     |
| options    | CheckableTagOption[]            | --      | 声明式选项 `{ label, value, disabled? }`    |
| disabled   | boolean                         | false   | 是否禁用整个 group                          |
| maxCount   | number                          | --      | 最大勾选数量；达上限后未勾选项 click 被忽略 |
| size       | 'large' \| 'default' \| 'small' | default | 子标签尺寸                                  |

## CheckableTagGroup 事件

| 事件名            | 参数                 | 说明     |
| ----------------- | -------------------- | -------- |
| update:modelValue | (string \| number)[] | v-model  |
| change            | (string \| number)[] | 选中变化 |

## CheckableTagGroup 插槽

| 插槽名  | 说明                                                        |
| ------- | ----------------------------------------------------------- |
| default | 内嵌 `<c-checkable-tag :value="...">` 子标签，由 group 接管 |


---

# Collapse 折叠面板

> 文档链接：https://vaebe.github.io/ccui/components/collapse/index.html

将复杂的内容折叠收起，按需展开。常用于"分组配置"、"问答列表"、"层级日志"。

## 基本使用

`v-model` 绑定数组，元素是当前展开的 `name`。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(['1'])
</script>

<template>
  <c-collapse v-model="value">
    <c-collapse-item name="1" title="面板一">默认展开的内容。</c-collapse-item>
    <c-collapse-item name="2" title="面板二">点击标题展开。</c-collapse-item>
    <c-collapse-item name="3" title="面板三（禁用）" disabled> 面板被禁用，无法展开。 </c-collapse-item>
  </c-collapse>
</template>
```

:::

## 手风琴模式

`accordion` 让任意时刻最多只展开一项；此时 `v-model` 是单值。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('a')
</script>

<template>
  <c-collapse v-model="v" accordion>
    <c-collapse-item name="a" title="A 面板">A 的详情内容</c-collapse-item>
    <c-collapse-item name="b" title="B 面板">B 的详情内容</c-collapse-item>
    <c-collapse-item name="c" title="C 面板">C 的详情内容</c-collapse-item>
  </c-collapse>
</template>
```

:::

## 无边框 / 幽灵风格

`bordered={false}` 去掉外圈描边；`ghost` 进一步去掉背景色，与页面融为一体。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(['1'])
const b = ref(['1'])
</script>

<template>
  <p style="color: var(--ccui-color-text-secondary); margin-bottom: 4px">bordered=false</p>
  <c-collapse v-model="a" :bordered="false">
    <c-collapse-item name="1" title="无边框面板一">内容</c-collapse-item>
    <c-collapse-item name="2" title="无边框面板二">内容</c-collapse-item>
  </c-collapse>

  <p style="color: var(--ccui-color-text-secondary); margin-top: 16px; margin-bottom: 4px">ghost</p>
  <c-collapse v-model="b" ghost>
    <c-collapse-item name="1" title="幽灵面板一">内容</c-collapse-item>
    <c-collapse-item name="2" title="幽灵面板二">内容</c-collapse-item>
  </c-collapse>
</template>
```

:::

## 展开图标位置

`expand-icon-position` 把箭头放在 `start`（默认）或 `end`（标题右端）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref(['1'])
</script>

<template>
  <c-collapse v-model="v" expand-icon-position="end">
    <c-collapse-item name="1" title="箭头放右边">内容靠右展开图标</c-collapse-item>
    <c-collapse-item name="2" title="另一面板">内容</c-collapse-item>
  </c-collapse>
</template>
```

:::

## 自定义标题

每个 item 都可用 `#title` slot 自定义标题，放图标 / 标签 / 副文案都可以。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref(['1'])
</script>

<template>
  <c-collapse v-model="v">
    <c-collapse-item name="1">
      <template #title>
        <span style="font-weight: 600">订单 #2025-001</span>
        <c-tag color="success" style="margin-inline-start: 8px">已发货</c-tag>
      </template>
      <p>订单详情内容…</p>
    </c-collapse-item>
    <c-collapse-item name="2" title="订单 #2025-002">
      <p>另一笔订单</p>
    </c-collapse-item>
  </c-collapse>
</template>
```

:::

## 监听变化

`change` 事件在展开 / 收起时触发，参数是当前激活的 name 数组（accordion 模式下是单值）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref(['1'])
const log = ref('（无）')

function onChange(names) {
  log.value = JSON.stringify(names)
}
</script>

<template>
  <c-collapse v-model="v" @change="onChange">
    <c-collapse-item name="1" title="面板一">内容 1</c-collapse-item>
    <c-collapse-item name="2" title="面板二">内容 2</c-collapse-item>
    <c-collapse-item name="3" title="面板三">内容 3</c-collapse-item>
  </c-collapse>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近一次激活：{{ log }}</p>
</template>
```

:::

## 单项 disabled 与隐藏箭头

可以对单个 item 设置 `disabled`（禁止展开 / 收起）或 `:show-arrow="false"`（隐藏箭头但仍可点击）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref(['1'])
</script>

<template>
  <c-collapse v-model="v">
    <c-collapse-item name="1" title="正常面板">默认状态</c-collapse-item>
    <c-collapse-item name="2" title="禁用面板" disabled>无法展开</c-collapse-item>
    <c-collapse-item name="3" title="无箭头面板" :show-arrow="false">仍可点击展开 / 收起</c-collapse-item>
  </c-collapse>
</template>
```

:::

## 嵌套面板

Collapse 支持嵌套；外层 ghost / 内层带边框是常见组合，强调层级关系。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const outer = ref(['1'])
const inner = ref(['1-1'])
</script>

<template>
  <c-collapse v-model="outer" ghost>
    <c-collapse-item name="1" title="项目 Alpha">
      <c-collapse v-model="inner">
        <c-collapse-item name="1-1" title="开发任务">开发任务详情…</c-collapse-item>
        <c-collapse-item name="1-2" title="测试任务">测试任务详情…</c-collapse-item>
      </c-collapse>
    </c-collapse-item>
    <c-collapse-item name="2" title="项目 Beta">
      <p style="margin: 0">尚未拆分子任务</p>
    </c-collapse-item>
  </c-collapse>
</template>
```

:::

## FAQ 常见问答

最典型的业务场景：accordion 模式 + 自定义标题（带角标 / 副标题）+ 长描述。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('1')

const faqs = [
  { name: '1', q: '如何重置密码？', a: '在登录页点击「忘记密码」，输入注册邮箱后按邮件指引重置。' },
  { name: '2', q: '账号被锁怎么办？', a: '连续 5 次错误密码会临时锁定 30 分钟，或联系客服立即解锁。' },
  { name: '3', q: '能否更换绑定手机？', a: '可以。进入「账号设置 → 安全中心」，验证旧手机后更换新号码。' },
]
</script>

<template>
  <c-collapse v-model="v" accordion>
    <c-collapse-item v-for="(faq, i) in faqs" :key="faq.name" :name="faq.name">
      <template #title>
        <span style="color: var(--ccui-color-primary); font-weight: 500; margin-inline-end: 6px">Q{{ i + 1 }}</span>
        <span>{{ faq.q }}</span>
      </template>
      <p style="margin: 0; color: var(--ccui-color-text-secondary); line-height: 1.6">{{ faq.a }}</p>
    </c-collapse-item>
  </c-collapse>
</template>
```

:::

## 外部按钮全展全收

`v-model` 受控时，外部按钮可以直接修改激活 name 列表，实现「全部展开 / 全部收起」操作。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const items = [
  { name: '1', title: '第 1 节' },
  { name: '2', title: '第 2 节' },
  { name: '3', title: '第 3 节' },
  { name: '4', title: '第 4 节' },
]

const v = ref(['1'])

function expandAll() {
  v.value = items.map((i) => i.name)
}
function collapseAll() {
  v.value = []
}
</script>

<template>
  <div style="display: flex; gap: 8px; margin-bottom: 12px">
    <c-button size="small" @click="expandAll">全部展开</c-button>
    <c-button size="small" @click="collapseAll">全部收起</c-button>
  </div>
  <c-collapse v-model="v">
    <c-collapse-item v-for="item in items" :key="item.name" :name="item.name" :title="item.title">
      {{ item.title }} 的详细内容
    </c-collapse-item>
  </c-collapse>
</template>
```

:::

## 表单分组

后台「字段太多怕一屏放不下」时常把表单按段落折叠：基础信息默认展开 + 进阶配置默认收起。

:::demo

```vue
<script setup>
import { reactive, ref } from 'vue'

const v = ref(['basic'])
const form = reactive({
  name: '',
  email: '',
  webhook: '',
  retryLimit: 3,
})
</script>

<template>
  <c-collapse v-model="v">
    <c-collapse-item name="basic" title="基础信息">
      <c-form :model="form" label-width="80px">
        <c-form-item label="名称" prop="name">
          <c-input v-model="form.name" placeholder="请输入" />
        </c-form-item>
        <c-form-item label="邮箱" prop="email">
          <c-input v-model="form.email" placeholder="example@x.com" />
        </c-form-item>
      </c-form>
    </c-collapse-item>
    <c-collapse-item name="advanced" title="高级配置（默认收起）">
      <c-form :model="form" label-width="80px">
        <c-form-item label="Webhook" prop="webhook">
          <c-input v-model="form.webhook" placeholder="https://..." />
        </c-form-item>
        <c-form-item label="重试次数" prop="retryLimit">
          <c-input-number v-model="form.retryLimit" :min="0" :max="10" />
        </c-form-item>
      </c-form>
    </c-collapse-item>
  </c-collapse>
</template>
```

:::

## API

### Collapse Props

| 参数               | 类型                                     | 默认值    | 说明                                |
| ------------------ | ---------------------------------------- | --------- | ----------------------------------- |
| modelValue         | `string \| number \| (string\|number)[]` | `[]`      | 展开的 name；accordion 模式下是单值 |
| accordion          | boolean                                  | `false`   | 手风琴模式（同时只展开一项）        |
| bordered           | boolean                                  | `true`    | 是否带外框                          |
| ghost              | boolean                                  | `false`   | 透明背景（无填充）                  |
| expandIconPosition | `'start' \| 'end'`                       | `'start'` | 展开图标位置                        |

### Collapse Events

| 事件名            | 回调签名                               | 触发时机           |
| ----------------- | -------------------------------------- | ------------------ |
| update:modelValue | `(names: string \| number \| (...)[])` | 激活项变化         |
| change            | 同上                                   | 同上（语义化别名） |

### CollapseItem Props

| 参数      | 类型               | 默认值  | 说明                         |
| --------- | ------------------ | ------- | ---------------------------- |
| name      | `string \| number` | —       | 必填，唯一标识               |
| title     | string             | `''`    | 标题（也可用 `#title` slot） |
| disabled  | boolean            | `false` | 禁用展开                     |
| showArrow | boolean            | `true`  | 是否显示展开箭头             |

### CollapseItem Slots

| 名称    | 说明       |
| ------- | ---------- |
| default | 面板内容   |
| title   | 自定义标题 |


---

# ColorPicker 颜色选择器

> 文档链接：https://vaebe.github.io/ccui/components/color-picker/index.html

可视化挑选颜色，支持 HEX / RGB / HSB 三种格式显示，alpha 透明度，预设色板，和受控/非受控两种模式。基于浏览器 Pointer Events 实现 SV / hue / alpha 三段拖拽，零外部颜色库依赖。

## 基本使用

`v-model` 绑定 hex 字符串。alpha < 1 时输出 8 位 hex（如 `#1677ff80`），否则输出 6 位。

:::demo

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

const color = ref('#1677ff')
</script>

<template>
  <c-color-picker v-model="color" show-text />
  <span style="margin-left: 12px">当前：{{ color }}</span>
</template>
```

:::

## 显示格式

`format` 切换 swatch 旁的文本显示格式（不影响 `v-model` 输出，输出始终是 hex）。

:::demo

```vue
<template>
  <c-color-picker default-value="#1677ff" show-text format="hex" />
  <c-color-picker default-value="#1677ff" show-text format="rgb" />
  <c-color-picker default-value="#1677ff" show-text format="hsb" />
</template>
```

:::

## 关闭 alpha

`disabled-alpha` 关掉透明度滑块，强制 alpha=1，输出始终是 6 位 hex。

:::demo

```vue
<template>
  <c-color-picker default-value="#36ad6a" show-text disabled-alpha />
</template>
```

:::

## 预设色板

`presets` 在面板上方显示预设色，点击直接套用。最简单形态是 hex 字符串列表。

:::demo

```vue
<script setup lang="ts">
const presets = ['#1677ff', '#36ad6a', '#f7b500', '#ff4d4f', '#722ed1', '#13c2c2', '#000000', '#ffffff']
</script>

<template>
  <c-color-picker default-value="#1677ff" :presets="presets" show-text />
</template>
```

:::

## 分组预设 / 带标签

`presets` 也接受 `{ label?, colors }[]` 分组形态。`colors` 内每一项可以是 hex 字符串，也可以是 `{ color, label? }` 对象（`label` 会写入按钮的 `aria-label` / `title`，便于无障碍）。

:::demo

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

const color = ref('#1677ff')

const presets = [
  {
    label: '品牌色板',
    colors: [
      { color: '#1677ff', label: '主品牌蓝' },
      { color: '#36ad6a', label: '辅助绿' },
      { color: '#f7b500', label: '强调黄' },
    ],
  },
  {
    label: '中性灰阶',
    colors: ['#000000', '#595959', '#bfbfbf', '#f0f0f0', '#ffffff'],
  },
]
</script>

<template>
  <c-color-picker v-model="color" :presets="presets" show-text />
</template>
```

:::

## 自定义面板 panel slot

`panel` slot 完全接管面板内容，scope 提供 `{ color, components }`，其中 `components.picker` / `components.presets` / `components.footer` 是渲染函数 —— 可以按需调用、重新排版、外面套自己的说明区。下例把预设放到拾色器右侧，并在底部追加一段提示。

:::demo

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

const color = ref('#1677ff')
const presets = [{ label: '主题色快选', colors: ['#1677ff', '#36ad6a', '#f7b500', '#ff4d4f', '#722ed1', '#13c2c2'] }]
</script>

<template>
  <c-color-picker v-model="color" :presets="presets" show-text>
    <template #panel="{ color: hex, components }">
      <div style="display: flex; gap: 12px; align-items: flex-start">
        <div style="flex: 1; min-width: 220px">
          <component :is="components.picker" />
        </div>
        <div style="width: 140px">
          <component :is="components.presets" />
        </div>
      </div>
      <div
        style="margin-top: 12px; padding-top: 12px; border-top: 1px solid var(--ccui-color-border-secondary); color: var(--ccui-color-text-secondary); font-size: 12px"
      >
        当前选中：{{ hex }} —— 上线前请走品牌色规范评审
      </div>
    </template>
  </c-color-picker>
</template>
```

:::

## 三种尺寸

:::demo

```vue
<template>
  <c-color-picker default-value="#1677ff" size="small" show-text />
  <c-color-picker default-value="#1677ff" show-text />
  <c-color-picker default-value="#1677ff" size="large" show-text />
</template>
```

:::

## 禁用

:::demo

```vue
<template>
  <c-color-picker default-value="#1677ff" disabled show-text />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive({ brand: '' })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { brand: [{ required: true, message: '请选择品牌色', trigger: 'change' }] }
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="brand" label="品牌色" prop="brand">
      <c-color-picker v-model="form.brand" show-text />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()">校验</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

```vue
<template>
  <c-color-picker default-value="#1677ff" show-text popup-append-to-body />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-color-picker v-model="value" :variant="variant" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('#1677ff')
</script>
```

:::

## API

### Props

| 参数              | 类型                                                       | 默认值                   | 说明                                                                              |
| ----------------- | ---------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| modelValue        | string \| null                                             | --                       | 当前颜色（hex 字符串），支持 `v-model`                                            |
| defaultValue      | string                                                     | `#1677ff`                | 非受控初始 hex 值                                                                 |
| format            | `'hex' \| 'rgb' \| 'hsb'`                                  | `'hex'`                  | swatch 文本显示格式（不影响 v-model 输出）                                        |
| disabled          | boolean                                                    | `false`                  | 是否禁用                                                                          |
| size              | `'small' \| 'default' \| 'large'`                          | `'default'`              | trigger 尺寸                                                                      |
| status            | `'' \| 'error' \| 'warning' \| 'success' \| 'validating'`  | `''`                     | 校验状态；置于 `FormItem` 时自动继承                                              |
| showText          | boolean                                                    | `false`                  | 是否在 swatch 旁显示色值文本                                                      |
| disabledAlpha     | boolean                                                    | `false`                  | 关闭 alpha 滑块，强制 alpha=1，输出 6 位 hex                                      |
| presets           | `Array<string \| { color, label? } \| { label?, colors }>` | `[]`                     | 预设色板。可传扁平 hex 列表、单色对象列表，或 `{ label?, colors }` 分组列表       |
| placement         | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`           | 浮层方位                                                                          |
| popupClassName    | string                                                     | --                       | 浮层根元素自定义 class                                                            |
| popupAppendToBody | boolean                                                    | `false`                  | 是否把浮层 Teleport 到 `document.body`                                            |
| getPopupContainer | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                       | 自定义浮层挂载点，优先级高于 `popupAppendToBody`                                  |
| transitionName    | string                                                     | `ccui-color-picker-fade` | 浮层过渡名                                                                        |
| allowClear        | boolean                                                    | `false`                  | 是否允许清空（显示 × 按钮，emit null）                                            |

### Slots

| 名称    | 作用域                                                                                                              | 说明                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| trigger | `{ color: string, open: boolean, disabled: boolean }`                                                               | 自定义触发器，替代默认 swatch 按钮                                                               |
| panel   | `{ color: string, components: { picker: () => VNode, presets: () => VNode \| null, footer: () => VNode \| null } }` | 自定义面板内容；`components.*` 为面板各子片段的渲染函数，可按需调用、重新排版                    |
| footer  | `{ color: string }`                                                                                                 | 面板底部追加区。默认面板：放在 picker 之后渲染；`panel` slot 内：通过 `components.footer()` 调用 |

### Events

| 事件名            | 回调签名                                      | 触发时机                                  |
| ----------------- | --------------------------------------------- | ----------------------------------------- |
| update:modelValue | `(hex: string)`                               | 颜色变化时（hex 字符串，alpha<1 时 8 位） |
| change            | `(hex: string, info: { rgb: RGB; hsv: HSV })` | 颜色变化时（同 update:modelValue）        |
| open-change       | `(open: boolean)`                             | 浮层打开 / 关闭时                         |

### 键盘导航

面板内 SV 区域、hue 滑块、alpha 滑块均支持 `tabindex=0` 聚焦和方向键微调：

| 区域  | 按键                     | 操作                       |
| ----- | ------------------------ | -------------------------- |
| SV    | Arrow Right/Left         | 饱和度 ±1（Shift ±10）     |
| SV    | Arrow Up/Down            | 明度 ±1（Shift ±10）       |
| Hue   | Arrow Right/Left/Up/Down | 色相 ±1（Shift ±10）       |
| Alpha | Arrow Right/Left/Up/Down | 透明度 ±0.01（Shift ±0.1） |


---

# ConfigProvider 全局配置

> 文档链接：https://vaebe.github.io/ccui/components/config-provider/index.html

为内部所有 ccui 组件提供统一的全局配置：尺寸、方向、品牌色、语言、类名前缀。

## 何时使用

- 应用根部统一覆盖：默认尺寸、文字方向、品牌色 token。
- 多语言场景下注入语言包。
- 与外部库共存时需要换 `prefixCls` 避免类名冲突。

## 自定义品牌色

`theme.token` 接收 camelCase 形式的 token（如 `colorPrimary`），ConfigProvider 会把它映射为对应 CSS 变量并下传到子组件。

:::demo

```vue
<template>
  <c-config-provider :theme="{ token: { colorPrimary: '#52c41a' } }">
    <c-button type="primary">绿色主题主按钮</c-button>
  </c-config-provider>
</template>
```

:::

## 同时调多个 token

`colorPrimary` / `borderRadius` / `colorError` 等都可以一起传。

:::demo

```vue
<template>
  <c-config-provider
    :theme="{
      token: {
        colorPrimary: '#722ed1',
        borderRadius: 16,
        colorError: '#ff7875',
      },
    }"
  >
    <c-button type="primary">紫色 + 大圆角</c-button>
    <c-button type="danger" style="margin-inline-start: 8px">浅红 danger</c-button>
  </c-config-provider>
</template>
```

:::

## 全局组件尺寸

`component-size` 让作用域内的 `c-button` / `c-input` 等组件默认走对应尺寸（仍可被组件自身的 `size` 覆盖）。

:::demo

```vue
<template>
  <c-config-provider component-size="small">
    <c-button>小尺寸默认</c-button>
    <c-button type="primary" style="margin-inline-start: 8px">小尺寸 primary</c-button>
  </c-config-provider>
  <div style="margin-top: 12px">
    <c-config-provider component-size="large">
      <c-button>大尺寸默认</c-button>
      <c-button type="primary" style="margin-inline-start: 8px">大尺寸 primary</c-button>
    </c-config-provider>
  </div>
</template>
```

:::

## 文字方向

`direction="rtl"` 让内部组件在阿拉伯语 / 希伯来语等场景下从右向左排布。

:::demo

```vue
<template>
  <c-config-provider direction="rtl">
    <c-button>زر</c-button>
    <c-button type="primary" style="margin-inline-start: 8px">زر رئيسي</c-button>
  </c-config-provider>
</template>
```

:::

## 多个 ConfigProvider 嵌套

后代的 ConfigProvider 会覆盖外层配置；这样可以在页面局部使用不同主题。

:::demo

```vue
<template>
  <c-config-provider :theme="{ token: { colorPrimary: '#1677ff' } }">
    <c-button type="primary">外层蓝</c-button>
    <c-config-provider :theme="{ token: { colorPrimary: '#fa541c' } }">
      <c-button type="primary" style="margin-inline-start: 8px">局部橙</c-button>
    </c-config-provider>
    <c-button type="primary" style="margin-inline-start: 8px">外层蓝</c-button>
  </c-config-provider>
</template>
```

:::

## 切换语言

传入 `locale` 把内部组件的默认文案换成对应语言。ccui 内置 `zhCN` / `enUS` / `jaJP` / `koKR` 四个语言包，可从 `@vaebe/ccui` 直接导出；未覆盖的 namespace 会自动回退到 `zhCN`。切换 locale 时全局 `dayjs.locale()` 也会同步切换。

下面用 Pagination 演示四语言切换：

:::demo

```vue
<template>
  <c-config-provider :locale="locale">
    <c-pagination :current="2" :total="55" :page-size="10" show-total show-quick-jumper />
  </c-config-provider>
  <div style="margin-top: 12px; display: flex; gap: 8px;">
    <c-button
      v-for="opt in locales"
      :key="opt.locale"
      :type="locale.locale === opt.locale ? 'primary' : 'default'"
      @click="locale = opt"
    >
      {{ opt.locale }}
    </c-button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { enUS, jaJP, koKR, zhCN } from '@vaebe/ccui'

const locales = [zhCN, enUS, jaJP, koKR]
const locale = ref(zhCN)
</script>
```

:::

DatePicker / TimePicker / RangePicker / Calendar 的 placeholder、周名、面板标题、按钮文案同样会跟着 `locale` 切换：

:::demo

```vue
<template>
  <c-config-provider :locale="enUS">
    <c-date-picker />
    <c-time-picker style="margin-inline-start: 8px" />
  </c-config-provider>
</template>

<script setup>
import { enUS } from '@vaebe/ccui'
</script>
```

:::

## 在组件内读取配置

业务组件用组合 API `useConfig` 读当前生效的配置。

```ts
import { useConfig } from '@vaebe/ccui'

const cfg = useConfig()
// cfg.componentSize / cfg.direction / cfg.locale / cfg.theme / cfg.prefixCls
```

## API

### Props

| 参数          | 类型                             | 默认值        | 说明                                                                                        |
| ------------- | -------------------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| prefixCls     | string                           | `'ccui'`      | 类名前缀                                                                                    |
| componentSize | `'small' \| 'middle' \| 'large'` | `'middle'`    | 默认组件尺寸                                                                                |
| direction     | `'ltr' \| 'rtl'`                 | `'ltr'`       | 文字方向                                                                                    |
| locale        | `Locale`                         | —             | 语言包                                                                                      |
| theme         | `{ token, algorithm }`           | —             | 主题配置：`token` 用 camelCase（colorPrimary / borderRadius 等），自动映射为 CSS 变量并下传 |
| iconPrefixCls | string                           | `'ccui-icon'` | 图标类名前缀                                                                                |

### useConfig

返回当前生效的 `ConfigContext`：`{ prefixCls, componentSize, direction, locale, theme, iconPrefixCls }`。


---

# DatePicker 日期选择框

> 文档链接：https://vaebe.github.io/ccui/components/date-picker/index.html

输入或选择日期/周/月/年/季度的控件。支持 `picker` 切换 5 种粒度、面板逐级展开（date → month → year）、`weekStart` 周起始、ConfigProvider 注入 locale 与周文案。

## 基本使用

最简单的用法。`v-model` 默认输出按 `format` 渲染的字符串。

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" />
</template>
```

:::

## 显示已选值

`modelValue` 可以是 `string` / `Date` / `Dayjs` / `number(ms)`，组件会自动按 `format` 解析与显示。

:::demo

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

const today = ref('2026-05-09')
</script>

<template>
  <c-date-picker v-model="today" />
</template>
```

:::

## 自定义格式

`format` 控制输入框展示与字符串解析；`valueFormat` 决定 `v-model` 输出形态。

- `valueFormat="string"`（默认）：按 `format` 输出字符串。
- `valueFormat="date"`：输出原生 `Date` 实例。
- `valueFormat="number"`：输出毫秒时间戳。

:::demo

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

const a = ref('')
const b = ref<Date | null>(null)
const c = ref<number | null>(null)
</script>

<template>
  <c-date-picker v-model="a" format="YYYY/MM/DD" />
  <c-date-picker v-model="b" value-format="date" />
  <c-date-picker v-model="c" value-format="number" />
</template>
```

:::

## 禁用日期

`disabledDate(current: Dayjs) => boolean` 用于禁用某些不可选日期。

:::demo

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

const value = ref('')

function disabledDate(current: Dayjs) {
  return current.isBefore(dayjs().startOf('day'))
}
</script>

<template>
  <c-date-picker v-model="value" :disabled-date="disabledDate" />
</template>
```

:::

## 限制可选范围 minDate / maxDate

`minDate` / `maxDate` 接受 `string / Date / Dayjs / number`，超出区间的 cell 自动 disabled，免去自己写 `disabledDate`。三者可叠加，命中任意一条即不可选。

对于 `picker='month' / 'year' / 'quarter'` 粒度，比较按对应单元进行（minDate 落在月中时不会把整月一刀切掉）。

:::demo

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

// 业务：预订未来 30 天内
const reserveDate = ref('')
const today = dayjs().startOf('day')
const max = today.add(30, 'day')
</script>

<template>
  <c-date-picker
    v-model="reserveDate"
    :min-date="today.toDate()"
    :max-date="max.toDate()"
    placeholder="只可选未来 30 天内"
  />
</template>
```

:::

## 三种尺寸

`size` 支持 `small` / `default` / `large`。

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" size="small" placeholder="small" />
  <c-date-picker v-model="value" placeholder="default" />
  <c-date-picker v-model="value" size="large" placeholder="large" />
</template>
```

:::

## 禁用 / 不可清除

:::demo

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

const value = ref('2026-05-09')
</script>

<template>
  <c-date-picker v-model="value" disabled />
  <c-date-picker v-model="value" :clearable="false" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive({ birthday: '' })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { birthday: [{ required: true, message: '请选择生日' }] }
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="birthday" label="生日" prop="birthday">
      <c-date-picker v-model="form.birthday" />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()"> 校验 </c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

默认浮层挂载在组件根元素内，溢出滚动容器时可能被裁切。把 `popup-append-to-body` 设为 `true` 或自定义 `getPopupContainer` 把面板挂到指定容器。

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" popup-append-to-body />
</template>
```

:::

## Picker 模式

通过 `picker` 切换选择粒度，未显式传入 `format` 时按粒度兜底。

:::demo

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

const week = ref('')
</script>

<template>
  <c-date-picker v-model="week" picker="week" />
  <p>当前值：{{ week || '（未选择）' }}</p>
</template>
```

:::

:::demo

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

const month = ref('2026-05')
const monthDisabled = ref('2026-01')
</script>

<template>
  <c-date-picker v-model="month" picker="month" />
  <c-date-picker v-model="monthDisabled" picker="month" disabled />
</template>
```

:::

:::demo

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

const year = ref('')
const yearDefault = ref('2026')
</script>

<template>
  <c-date-picker v-model="year" picker="year" placeholder="请选择年份" />
  <c-date-picker v-model="yearDefault" picker="year" />
</template>
```

:::

:::demo

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

const quarter = ref('')
const quarterDefault = ref('2026-Q2')
</script>

<template>
  <c-date-picker v-model="quarter" picker="quarter" />
  <c-date-picker v-model="quarterDefault" picker="quarter" />
</template>
```

:::

## showTime 时间选择

仅 `picker="date"` 生效。开启后面板底部自动追加「此刻」+「确定」按钮，点击日期不会立即 emit，需点「确定」确认。

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" show-time />
  <p>v-model 值: {{ value }}</p>
</template>
```

:::

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" :show-time="{ format: 'HH:mm' }" />
</template>
```

:::

:::demo

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

const value = ref('')
const timeConfig = {
  hourStep: 2,
  defaultValue: dayjs('09:00:00', 'HH:mm:ss'),
}
</script>

<template>
  <c-date-picker v-model="value" :show-time="timeConfig" />
</template>
```

:::

:::demo

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

const value = ref('')
const timeConfig = {
  disabledHours: () => [0, 1, 2, 3, 4, 5, 6],
  disabledMinutes: () => [15, 30, 45],
}
</script>

<template>
  <c-date-picker v-model="value" :show-time="timeConfig" :show-now="false" />
</template>
```

:::

## 动态时间禁用 disabledTime

`disabledTime(current)` 接当前编辑日期（pending）作为入参，返回 `{ disabledHours, disabledMinutes, disabledSeconds }`。其中 `disabledMinutes` 接 `hour`、`disabledSeconds` 接 `hour + minute`，方便实现「8:00 后才可选 / 仅整点」等业务约束。

与 `showTime.disabledHours / Minutes / Seconds`（静态）取并集 —— 静态规则用作全表禁用，动态规则按 pending 时间联动。

:::demo

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

// 业务：营业时间 09:00 - 18:00，整点选择
const apptTime = ref('')

function disabledTime() {
  return {
    disabledHours: () => Array.from({ length: 24 }, (_, i) => i).filter((h) => h < 9 || h > 18),
    disabledMinutes: () => Array.from({ length: 60 }, (_, i) => i).filter((m) => m !== 0),
    disabledSeconds: () => Array.from({ length: 60 }, (_, i) => i).filter((s) => s !== 0),
  }
}
</script>

<template>
  <c-date-picker v-model="apptTime" show-time :disabled-time="disabledTime" placeholder="选择预约时间" />
</template>
```

:::

## 面板底部说明 extra-footer slot

`#extra-footer` slot 在面板底部追加自定义说明区域。未启用 `showTime` 时，footer 容器仍会渲染；启用 `showTime` 时该区域位于「此刻 / 确定」按钮上方。

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value">
    <template #extra-footer> 以最终下单时间为准，订单生成后不可修改 </template>
  </c-date-picker>
</template>
```

:::

## 自定义单元格 cell slot

`#cell` slot 以 `{ current, type, today }` 作 scope，可在不打破栅格的前提下追加节假日标记、价格、状态点等业务信息。`type` 取值为 `'date' | 'month' | 'year' | 'quarter'`，根据当前面板模式联动。

:::demo

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

const value = ref('2026-05-09')

// 业务：节假日红点
const HOLIDAYS = new Set(['2026-05-01', '2026-05-02', '2026-05-03'])

function isHoliday(d: Dayjs) {
  return HOLIDAYS.has(d.format('YYYY-MM-DD'))
}
</script>

<template>
  <c-date-picker v-model="value">
    <template #cell="{ current, type }">
      <span class="my-day-cell">
        {{ type === 'date' ? current.date() : current.month() + 1 }}
        <span v-if="type === 'date' && isHoliday(current)" class="my-holiday-dot" />
      </span>
    </template>
  </c-date-picker>
</template>

<style scoped>
.my-day-cell {
  position: relative;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 24px;
  height: 24px;
}
.my-holiday-dot {
  position: absolute;
  right: 2px;
  top: 2px;
  width: 4px;
  height: 4px;
  border-radius: 50%;
  background-color: #f5222d;
}
</style>
```

:::

## 键盘导航

输入框聚焦后支持键盘操作（`inputReadOnly=true` 仍可生效）：

- `Enter` / `Space` / `↓`：打开面板
- `Esc`：关闭面板
- `Tab`：关闭面板并切走焦点
- `← → ↑ ↓`：在 date 面板移动键盘 focus（跨月自动翻面板）
- `Enter`：选中当前 focus 单元格

:::demo

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

const value = ref('')
</script>

<template>
  <c-date-picker v-model="value" placeholder="聚焦后按方向键试试" />
</template>
```

:::

## presets 预设快捷项

`presets` 在面板左侧渲染一列快捷项，`label` / `value` 均支持函数形式延迟求值，便于「今天 / 昨天」这种相对时刻。

:::demo

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

const value = ref('')
const presets = [
  { label: '昨天', value: () => dayjs().subtract(1, 'day').format('YYYY-MM-DD') },
  { label: '今天', value: () => dayjs().format('YYYY-MM-DD') },
  { label: '一周后', value: () => dayjs().add(1, 'week').format('YYYY-MM-DD') },
]
</script>

<template>
  <c-date-picker v-model="value" :presets="presets" />
</template>
```

:::

与 `picker="week"` 共存：value 解析后按所在周的起始日提交。

:::demo

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

const week = ref('')
const presets = [
  { label: '本周', value: '2026-05-11' },
  { label: '上周', value: '2026-05-04' },
  { label: '下周', value: '2026-05-18' },
]
</script>

<template>
  <c-date-picker v-model="week" picker="week" :presets="presets" />
</template>
```

:::

与 `showTime` 共存：点击预设仅更新内部 pending，仍需点「确定」提交，可继续微调时间。

:::demo

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

const value = ref('')
const presets = [{ label: '上次会议', value: () => dayjs('2026-05-09 14:30:00').toDate() }]
</script>

<template>
  <c-date-picker v-model="value" show-time :presets="presets" />
  <p>v-model 值: {{ value }}</p>
</template>
```

:::

## 周起始 weekStart

`weekStart` 控制面板内每周的起始日：`0` 周日开头（默认）/ `1` 周一开头。

:::demo

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

const a = ref('')
const b = ref('')
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 280px">
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">weekStart=0（默认，周日开头）</p>
      <c-date-picker v-model="a" :week-start="0" />
    </div>
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">weekStart=1（周一开头）</p>
      <c-date-picker v-model="b" :week-start="1" />
    </div>
  </div>
</template>
```

:::

## 校验状态 status

`status` 支持 `'error'` / `'warning'` / `'success'` / `'validating'`，置于 `<c-form-item>` 时自动继承。

:::demo

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

const v1 = ref('')
const v2 = ref('')
const v3 = ref('')
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 280px">
    <c-date-picker v-model="v1" status="error" placeholder="error" />
    <c-date-picker v-model="v2" status="warning" placeholder="warning" />
    <c-date-picker v-model="v3" status="success" placeholder="success" />
  </div>
</template>
```

:::

## change 事件双参追踪

`change(value, dateString)` 第二个参数是按 format 格式化后的字符串，常用于「无论 valueFormat 是 string / date / number 都能拿到一致的展示字符串」。

:::demo

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

const value = ref<Date | null>(null)
const lastChange = ref('（无）')

function onChange(v, dateString) {
  lastChange.value = `value 类型 = ${v === null ? 'null' : v?.constructor?.name} · dateString = "${dateString}"`
}
</script>

<template>
  <c-date-picker v-model="value" value-format="date" @change="onChange" />
  <p style="margin: 8px 0 0; color: var(--ccui-color-text-secondary)">最近一次 change：</p>
  <p style="margin: 4px 0 0; color: var(--ccui-color-text-secondary); font-size: 12px">{{ lastChange }}</p>
</template>
```

:::

## panel-change 事件追踪

`panel-change(mode, viewMonth)` 在面板模式切换（date ↔ month ↔ year）或视图月份变化时触发，可联动日历埋点 / 上报。

:::demo

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

const value = ref('')
const lastPanel = ref('（无）')

function onPanelChange(mode, viewMonth) {
  lastPanel.value = `mode = ${mode} · 视图月份 = ${viewMonth?.format?.('YYYY-MM')}`
}
</script>

<template>
  <c-date-picker v-model="value" @panel-change="onPanelChange" />
  <p style="margin: 8px 0 0; color: var(--ccui-color-text-secondary)">最近一次 panel-change：</p>
  <p style="margin: 4px 0 0; color: var(--ccui-color-text-secondary); font-size: 12px">{{ lastPanel }}</p>
  <p style="margin: 8px 0 0; color: var(--ccui-color-text-tertiary); font-size: 12px">提示：点击年份 / 月份头部进入上钻视图触发该事件</p>
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-date-picker v-model="value" :variant="variant" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
</script>
```

:::

## API

### Props

| 参数              | 类型                                                       | 默认值                  | 说明                                                                                                                                                                                                                                                                                              |
| ----------------- | ---------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| modelValue        | string / Date / Dayjs / number / null                      | --                      | 当前选中日期，支持 `v-model`                                                                                                                                                                                                                                                                      |
| format            | string                                                     | `''`                    | 输入框显示与字符串解析格式（dayjs token）；为空时按 `picker` 兜底：date→`YYYY-MM-DD` / week→`YYYY-MM-DD` / month→`YYYY-MM` / year→`YYYY` / quarter→`YYYY-[Q]Q`                                                                                                                                    |
| valueFormat       | `'string' \| 'date' \| 'number'`                           | `'string'`              | `v-model` 输出形态：按 format 字符串 / Date 实例 / 毫秒时间戳                                                                                                                                                                                                                                     |
| placeholder       | string                                                     | `请选择日期`            | 占位文案                                                                                                                                                                                                                                                                                          |
| disabled          | boolean                                                    | `false`                 | 是否禁用                                                                                                                                                                                                                                                                                          |
| clearable         | boolean                                                    | `true`                  | 是否显示清除按钮                                                                                                                                                                                                                                                                                  |
| size              | `'small' \| 'default' \| 'large'`                          | `'default'`             | 输入框尺寸                                                                                                                                                                                                                                                                                        |
| status            | `'' \| 'error' \| 'warning' \| ...`                        | `''`                    | 校验状态；置于 `FormItem` 时自动继承                                                                                                                                                                                                                                                              |
| disabledDate      | `(current: Dayjs) => boolean`                              | --                      | 不可选日期回调，返回 `true` 表示禁用                                                                                                                                                                                                                                                              |
| minDate           | `string \| Date \| Dayjs \| number`                        | --                      | 最早可选日期；超出区间的 cell 自动 disabled。与 `disabledDate` / `maxDate` 取并集；非 `date` 粒度按对应单元（月 / 年 / 季度）比较                                                                                                                                                                 |
| maxDate           | `string \| Date \| Dayjs \| number`                        | --                      | 最晚可选日期。语义同 `minDate`                                                                                                                                                                                                                                                                    |
| disabledTime      | `(current: Dayjs \| null) => DisabledTimeReturn`           | --                      | 动态时间禁用，依赖正在编辑的日期；与 `showTime.disabledHours / Minutes / Seconds` 取并集。`DisabledTimeReturn = { disabledHours?(): number[]; disabledMinutes?(hour: number): number[]; disabledSeconds?(hour: number, minute: number): number[] }`                                               |
| placement         | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`          | 浮层方位，配合 `@floating-ui/vue` 自动 flip / shift                                                                                                                                                                                                                                               |
| popupClassName    | string                                                     | --                      | 浮层根元素自定义 class                                                                                                                                                                                                                                                                            |
| popupAppendToBody | boolean                                                    | `false`                 | 是否把浮层 Teleport 到 `document.body`                                                                                                                                                                                                                                                            |
| getPopupContainer | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                      | 自定义浮层挂载点，优先级高于 `popupAppendToBody`                                                                                                                                                                                                                                                  |
| autoFocus         | boolean                                                    | `false`                 | 挂载后自动 focus 输入框                                                                                                                                                                                                                                                                           |
| inputReadOnly     | boolean                                                    | `true`                  | 输入框只读（不允许键盘输入日期，仅通过面板选择）                                                                                                                                                                                                                                                  |
| transitionName    | string                                                     | `ccui-date-picker-fade` | 浮层过渡名                                                                                                                                                                                                                                                                                        |
| picker            | `'date' \| 'week' \| 'month' \| 'year' \| 'quarter'`       | `'date'`                | 选择粒度；面板形态、`format` 兜底与 emit 值随之变化                                                                                                                                                                                                                                               |
| showTime          | `boolean \| TimeShowConfig`                                | `false`                 | 仅 `picker="date"` 生效；开启后面板追加时间选择列与「此刻 / 确定」footer。`TimeShowConfig` 支持 `format`（默认 `'HH:mm:ss'`，含 `m` 显示分列、含 `s` 显示秒列）、`defaultValue`、`hourStep / minuteStep / secondStep`、`disabledHours / disabledMinutes / disabledSeconds`、`hideDisabledOptions` |
| showNow           | boolean                                                    | `true`                  | 启用 `showTime` 时是否显示 footer 的「此刻」按钮                                                                                                                                                                                                                                                  |
| presets           | `PresetItem[]`                                             | `[]`                    | 面板左侧快捷项列表；`PresetItem = { label: string \| (() => string); value: DateValue \| (() => DateValue) }`，`label` / `value` 均支持函数形式延迟求值。空数组不渲染 rail；与 `showTime` 共存时点击仅填充 pending，需点「确定」提交                                                              |
| weekStart         | `0 \| 1`                                                   | `0`                     | 周起始：`0` 周日开头，`1` 周一开头                                                                                                                                                                                                                                                                |

### Events

| 事件名            | 回调签名                                                             | 触发时机                           |
| ----------------- | -------------------------------------------------------------------- | ---------------------------------- |
| update:modelValue | `(value: string \| Date \| number \| null)`                          | 选中日期或清除时                   |
| change            | `(value, dateString: string)`                                        | 选中日期或清除时（带格式化字符串） |
| open-change       | `(open: boolean)`                                                    | 浮层打开 / 关闭时                  |
| focus             | --                                                                   | 输入框聚焦                         |
| blur              | --                                                                   | 输入框失焦                         |
| panel-change      | `(mode: 'date' \| 'month' \| 'year' \| 'quarter', viewMonth: Dayjs)` | 面板模式切换时触发（含逐级上钻）   |

### Slots

| 名称         | scope                                                                              | 说明                                                       |
| ------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| cell         | `{ current: Dayjs; type: 'date' \| 'month' \| 'year' \| 'quarter'; today: Dayjs }` | 自定义单元格内容，按当前面板模式取值；不传时走默认渲染     |
| extra-footer | --                                                                                 | 面板底部追加内容；未启用 `showTime` 时也会渲染 footer 容器 |
| clearIcon    | --                                                                                 | 自定义清除图标                                             |
| suffixIcon   | --                                                                                 | 自定义日历图标                                             |

## 已知限制

以下能力当前未覆盖：

- range 区间选择（请使用独立的 `RangePicker` 组件）。
- `TimePicker` 组件、`format` 含时分秒时的面板分栏。
- `showToday`。


---

# Descriptions 描述列表

> 文档链接：https://vaebe.github.io/ccui/components/descriptions/index.html

成组展示多个只读字段，常用于详情页 / 资料卡。

## 何时使用

- 详情页展示订单 / 用户 / 资源的属性。
- 接口返回的多字段以"标签 + 值"形式呈现。

## 基本使用

`items` 描述每条字段；默认 `column=3` 三列均分。

:::demo

```vue
<template>
  <c-descriptions
    title="用户信息"
    :items="[
      { label: '用户名', value: 'Alice' },
      { label: '电话', value: '13888888888' },
      { label: '住址', value: '北京' },
      { label: '余额', value: '¥168.00' },
      { label: '会员', value: '黄金' },
      { label: '状态', value: '在线' },
    ]"
  />
</template>
```

:::

## 带边框

`bordered` 切换为表格风格，每个 cell 都带边框，便于阅读。

:::demo

```vue
<template>
  <c-descriptions
    title="订阅详情"
    bordered
    :column="2"
    :items="[
      { label: '产品', value: 'Cloud DB' },
      { label: '订阅', value: 'Pro' },
      { label: '账单', value: '¥99/月' },
      { label: '到期', value: '2026-12-31' },
    ]"
  />
</template>
```

:::

## 控制列数

`column` 改变列数；某项的 `span` 可让它跨多列。

:::demo

```vue
<template>
  <c-descriptions
    bordered
    :column="3"
    :items="[
      { label: '订单号', value: '#202504-001', span: 2 },
      { label: '状态', value: '已发货' },
      { label: '收件人', value: '张三' },
      { label: '电话', value: '13800001234' },
      { label: '收件地址', value: '北京市朝阳区某街某号 12-3-4', span: 3 },
    ]"
  />
</template>
```

:::

## 不同尺寸

`size`：`small` / `default` / `middle`，影响 padding 和字号。

:::demo

```vue
<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 6px">small</p>
  <c-descriptions
    bordered
    size="small"
    :column="3"
    :items="[
      { label: 'A', value: '1' },
      { label: 'B', value: '2' },
      { label: 'C', value: '3' },
    ]"
  />

  <p style="color: var(--ccui-color-text-secondary); margin: 16px 0 6px">default</p>
  <c-descriptions
    bordered
    :column="3"
    :items="[
      { label: 'A', value: '1' },
      { label: 'B', value: '2' },
      { label: 'C', value: '3' },
    ]"
  />

  <p style="color: var(--ccui-color-text-secondary); margin: 16px 0 6px">middle</p>
  <c-descriptions
    bordered
    size="middle"
    :column="3"
    :items="[
      { label: 'A', value: '1' },
      { label: 'B', value: '2' },
      { label: 'C', value: '3' },
    ]"
  />
</template>
```

:::

## 纵向布局

`layout="vertical"` 把"标签 / 值"上下排，常用于较长内容。

:::demo

```vue
<template>
  <c-descriptions
    title="商品详情"
    layout="vertical"
    bordered
    :column="3"
    :items="[
      { label: '商品名', value: 'Cloud Database 高级版' },
      { label: '版本', value: 'v3.2.4' },
      { label: 'SLA', value: '99.95%' },
    ]"
  />
</template>
```

:::

## 隐藏冒号 / 自定义样式

`colon=false` 隐藏冒号；每项可单独传 `labelStyle` / `contentStyle`。

:::demo

```vue
<template>
  <c-descriptions
    :colon="false"
    :column="2"
    :items="[
      {
        label: '用户名',
        value: 'Alice',
        labelStyle: { color: '#1677ff', fontWeight: 600 },
      },
      {
        label: '余额',
        value: '¥168.00',
        contentStyle: { color: '#52c41a', fontWeight: 700 },
      },
    ]"
  />
</template>
```

:::

## API

### Descriptions Props

| 参数     | 类型                               | 默认值         | 说明               |
| -------- | ---------------------------------- | -------------- | ------------------ |
| title    | string                             | `''`           | 顶部标题           |
| extra    | string                             | `''`           | 标题右端附加内容   |
| bordered | boolean                            | `false`        | 表格风格的边框     |
| column   | number                             | `3`            | 列数               |
| size     | `'small' \| 'default' \| 'middle'` | `'default'`    | 尺寸               |
| layout   | `'horizontal' \| 'vertical'`       | `'horizontal'` | label / value 排布 |
| colon    | boolean                            | `true`         | 显示冒号           |
| items    | `DescriptionsItem[]`               | —              | 描述项数据         |

### DescriptionsItem

| 字段         | 类型               | 说明             |
| ------------ | ------------------ | ---------------- |
| label        | string             | 标签             |
| value        | `string \| number` | 值               |
| span         | number             | 跨列数（默认 1） |
| labelStyle   | `CSSProperties`    | 单项 label 样式  |
| contentStyle | `CSSProperties`    | 单项内容样式     |


---

# Divider 分隔线

> 文档链接：https://vaebe.github.io/ccui/components/divider/index.html

区隔内容的分隔线。

## 何时使用

- 对不同段落的文本进行分隔
- 对行内文字、链接进行分隔，例如表格的操作列
- 配合标题作为章节分割

## 基本使用

最常见的水平分隔线。

:::demo

```vue
<template>
  <p>第一段：我们终将远行，和过去稚嫩的自己告别。</p>
  <c-divider />
  <p>第二段：保持冷静，继续前行。</p>
</template>
```

:::

## 虚线

`border-style="dashed"` 渲染虚线。

:::demo

```vue
<template>
  <p>实线分隔</p>
  <c-divider />
  <p>虚线分隔</p>
  <c-divider border-style="dashed" />
  <p>结束</p>
</template>
```

:::

## 自定义颜色

`color` 改变分隔线颜色。

:::demo

```vue
<template>
  <p>默认</p>
  <c-divider />
  <p>自定义颜色</p>
  <c-divider color="#7693f5" />
</template>
```

:::

## 带文案

把文案放进默认插槽，分隔线会被中断；用 `content-position` 控制文案位置。

:::demo

```vue
<template>
  <c-divider>居中文案</c-divider>
  <c-divider content-position="left">左侧文案</c-divider>
  <c-divider content-position="right">右侧文案</c-divider>
</template>
```

:::

## 自定义文案样式

`content-color` 改文字颜色，`content-background-color` 改文字底色（在彩色背景上常用）。钉死一个固定浅色底时，记得同时钉死文字色，否则深色模式下文字会变白、落在浅底上不可读。

:::demo

```vue
<template>
  <c-divider content-color="#7693f5">蓝色文字</c-divider>
  <c-divider content-color="#874d00" content-background-color="#fff7e6">米色背景</c-divider>
</template>
```

:::

## 垂直分隔线

`direction="vertical"` 用于行内分隔，常见于操作列。

:::demo

```vue
<template>
  <c-button type="text">编辑</c-button>
  <c-divider direction="vertical" />
  <c-button type="text">复制</c-button>
  <c-divider direction="vertical" />
  <c-button type="text" danger>删除</c-button>
</template>
```

:::

## 虚线 + 文案

`border-style="dashed"` 与文案 / `content-position` 可以自由组合，常用于「可选区块分隔」「业务流程节点」。

:::demo

```vue
<template>
  <c-divider border-style="dashed">虚线居中</c-divider>
  <c-divider border-style="dashed" content-position="left">虚线靠左</c-divider>
  <c-divider border-style="dashed" content-position="right" content-color="#1677ff"> 可选区块 → </c-divider>
</template>
```

:::

## 章节标题分隔

把 `<h3>` 与 Divider 搭配使用，是长文档 / 长表单常见的「视觉分章」范式。

:::demo

```vue
<template>
  <h3 style="margin: 16px 0 0">基本信息</h3>
  <c-divider style="margin: 12px 0" />
  <p style="color: var(--ccui-color-text-secondary); margin: 0">姓名 / 头像 / 联系方式</p>

  <h3 style="margin: 24px 0 0">账号设置</h3>
  <c-divider style="margin: 12px 0" />
  <p style="color: var(--ccui-color-text-secondary); margin: 0">密码 / 双因素验证 / 登录历史</p>

  <h3 style="margin: 24px 0 0">通知偏好</h3>
  <c-divider style="margin: 12px 0" />
  <p style="color: var(--ccui-color-text-secondary); margin: 0">邮件 / 短信 / 站内消息</p>
</template>
```

:::

## 线型动态切换

`border-style` 接收响应式值，可以与开关 / 单选联动，便于业务上「打印模式 / 编辑模式」切换。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const styleMode = ref('solid')
</script>

<template>
  <c-segmented v-model="styleMode" :options="['solid', 'dashed']" style="margin-bottom: 12px" />
  <c-divider :border-style="styleMode">当前线型：{{ styleMode }}</c-divider>
</template>
```

:::

## 行内多段分组

垂直 Divider 配合一行多段操作时，可以用多个 `c-divider direction="vertical"` 把按钮分成「编辑组 / 状态组 / 危险操作组」三段。

:::demo

```vue
<template>
  <div style="display: flex; align-items: center; gap: 4px">
    <c-button type="text">复制</c-button>
    <c-button type="text">编辑</c-button>
    <c-divider direction="vertical" />
    <c-button type="text">归档</c-button>
    <c-button type="text">置顶</c-button>
    <c-divider direction="vertical" />
    <c-button type="text" danger>删除</c-button>
  </div>
</template>
```

:::

## API

### Props

| 参数                   | 类型                            | 默认值       | 说明           |
| ---------------------- | ------------------------------- | ------------ | -------------- |
| color                  | string                          | -            | 分隔线颜色     |
| direction              | `'horizontal' \| 'vertical'`    | `horizontal` | 分隔线方向     |
| borderStyle            | `'solid' \| 'dashed'`           | `solid`      | 线型           |
| contentPosition        | `'left' \| 'right' \| 'center'` | `center`     | 文案位置       |
| contentColor           | string                          | -            | 文案文字颜色   |
| contentBackgroundColor | string                          | -            | 文案文字背景色 |


---

# Drawer 抽屉

> 文档链接：https://vaebe.github.io/ccui/components/drawer/index.html

从屏幕侧边滑入的浮层，承载较多详情或表单。相比 Modal，Drawer 不打断当前页面纵深，更适合"补充信息"场景。

## 基本使用

通过 `v-model:visible` 控制开合；默认从右侧滑入。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <c-button type="primary" @click="open = true">打开抽屉</c-button>
  <c-drawer v-model:visible="open" title="详情">
    <p>抽屉里可以放任意复杂内容：表单、表格、富文本……</p>
  </c-drawer>
</template>
```

:::

## 四个方向

`placement` 可选 `right` / `left` / `top` / `bottom`。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const top = ref(false)
const bottom = ref(false)
const left = ref(false)
const right = ref(false)
</script>

<template>
  <c-button @click="top = true">上</c-button>
  <c-button @click="bottom = true">下</c-button>
  <c-button @click="left = true">左</c-button>
  <c-button @click="right = true">右</c-button>
  <c-drawer v-model:visible="top" placement="top" title="顶部">从上方滑入</c-drawer>
  <c-drawer v-model:visible="bottom" placement="bottom" title="底部">从下方滑入</c-drawer>
  <c-drawer v-model:visible="left" placement="left" title="左侧">从左侧滑入</c-drawer>
  <c-drawer v-model:visible="right" placement="right" title="右侧">从右侧滑入</c-drawer>
</template>
```

:::

## 自定义尺寸

`size` 接受数字（px）或字符串（带单位）。横向 placement 控制 width，纵向控制 height。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const small = ref(false)
const big = ref(false)
const half = ref(false)
</script>

<template>
  <c-button @click="small = true">小 (260)</c-button>
  <c-button @click="big = true">大 (640)</c-button>
  <c-button @click="half = true">百分比 (50%)</c-button>
  <c-drawer v-model:visible="small" :size="260" title="小抽屉">size=260</c-drawer>
  <c-drawer v-model:visible="big" :size="640" title="大抽屉">size=640</c-drawer>
  <c-drawer v-model:visible="half" size="50%" title="半屏">size='50%'</c-drawer>
</template>
```

:::

## 自定义底部按钮

带操作的抽屉常需要底部按钮区。用 `#footer` slot 自定义即可。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
const result = ref('（未操作）')

function ok() {
  result.value = '已保存'
  open.value = false
}
function cancel() {
  result.value = '已取消'
  open.value = false
}
</script>

<template>
  <c-button type="primary" @click="open = true">编辑</c-button>
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">最近操作：{{ result }}</span>
  <c-drawer v-model:visible="open" title="编辑信息">
    <p>这里放编辑表单……</p>
    <template #footer>
      <c-button @click="cancel">取消</c-button>
      <c-button type="primary" style="margin-inline-start: 8px" @click="ok">保存</c-button>
    </template>
  </c-drawer>
</template>
```

:::

## 关闭行为

`mask-closable` 控制点遮罩关；`close-on-esc` 控制 Esc 键关；都设为 `false` 时只能用 × 或外部代码关。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <c-button @click="open = true">打开（不可点蒙层关、Esc 不关）</c-button>
  <c-drawer v-model:visible="open" title="只能点 × 才能关" :mask-closable="false" :close-on-esc="false">
    <p>这种用法适合"必须显式确认"的流程。</p>
  </c-drawer>
</template>
```

:::

## 销毁内部 DOM

`destroy-on-close` 让抽屉关闭后清空内部内容（重置内嵌组件状态）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
const text = ref('')
</script>

<template>
  <c-button type="primary" @click="open = true">打开</c-button>
  <c-drawer v-model:visible="open" title="关后销毁" destroy-on-close>
    <p>关闭后下次重新打开，输入框会被清空：</p>
    <input
      v-model="text"
      placeholder="输点东西然后关掉再打开"
      style="width: 100%; padding: 6px 8px; border: 1px solid var(--ccui-color-border); border-radius: 4px"
    />
  </c-drawer>
</template>
```

:::

## API

### Props

| 参数                   | 类型                                                                                 | 默认值    | 说明                                                                |
| ---------------------- | ------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------- |
| visible                | boolean                                                                              | `false`   | 是否显示（支持 `v-model:visible`）                                  |
| title                  | string                                                                               | `''`      | 标题                                                                |
| placement              | `DrawerPlacement`                                                                    | `'right'` | 弹出方向：`left` / `right` / `top` / `bottom`                       |
| size                   | `number \| string`                                                                   | `378`     | 横向时为宽，纵向时为高（数字按 px，字符串按原值）                   |
| closable               | `boolean \| { closeIcon?: VNode \| string; disabled?: boolean; ariaLabel?: string }` | `true`    | 关闭按钮配置；对象形支持自定义图标 / 禁用 / aria-label              |
| maskClosable           | boolean                                                                              | `true`    | 点遮罩是否关闭                                                      |
| closeOnEsc             | boolean                                                                              | `true`    | Esc 键是否关闭                                                      |
| mask                   | boolean                                                                              | `true`    | 是否显示遮罩                                                        |
| loading                | boolean                                                                              | `false`   | 加载状态：渲染 3 行骨架占位 + `aria-busy="true"`，body 区被替换     |
| footer                 | `string \| VNode \| null \| undefined`                                               | --        | 底部内容（`null` 隐藏；string/VNode 直接渲染；undefined 启用 slot） |
| destroyOnClose         | boolean                                                                              | `false`   | 关闭后销毁内部 DOM                                                  |
| keepAlive              | boolean                                                                              | `false`   | 即使未打开也保留 DOM（与 `destroyOnClose` 互斥）                    |
| focusTriggerAfterClose | boolean                                                                              | `true`    | 关闭后聚焦回打开前的触发元素                                        |
| push                   | `boolean \| { distance?: number }`                                                   | `false`   | 嵌套抽屉时让位距离；父抽屉设 `push=false` 表示不让位                |
| zIndex                 | number                                                                               | `1000`    | 层级                                                                |
| appendToBody           | boolean                                                                              | `true`    | 是否把浮层 Teleport 到 `document.body`                              |

### Events

| 事件名            | 回调签名             | 触发时机                                                 |
| ----------------- | -------------------- | -------------------------------------------------------- |
| update:visible    | `(visible: boolean)` | 显示状态变化（v-model:visible）                          |
| after-open-change | `(open: boolean)`    | 打开 / 关闭动画完成后触发（immediate watch，首次 false） |
| open              | `()`                 | 开启动画开始                                             |
| opened            | `()`                 | 开启动画结束                                             |
| close             | `()`                 | 关闭被触发                                               |
| closed            | `()`                 | 关闭动画结束                                             |

### Slots

| 名称       | 说明                                              |
| ---------- | ------------------------------------------------- |
| default    | 抽屉主体内容                                      |
| title      | 自定义标题（覆盖 `title` 属性）                   |
| footer     | 自定义底部内容（优先级高于 `footer` prop）        |
| extra      | 标题右侧操作区（与 `title` 同行，inline-flex）    |
| close-icon | 自定义关闭图标（优先级高于 `closable.closeIcon`） |


---

# Dropdown 下拉菜单

> 文档链接：https://vaebe.github.io/ccui/components/dropdown/index.html

点击或悬停后弹出的菜单。

## 基本使用

`items` 提供菜单项，触发器写在默认插槽里。

:::demo

```vue
<template>
  <c-dropdown
    :items="[
      { key: '1', label: '编辑' },
      { key: '2', label: '复制' },
      { key: '3', label: '删除', danger: true, divided: true },
    ]"
  >
    <c-button>更多操作 ▾</c-button>
  </c-dropdown>
</template>
```

:::

## 触发方式

通过 `trigger` 切换触发方式：`hover`（默认）/ `click` / `contextmenu`（右键）。

:::demo

```vue
<template>
  <c-dropdown trigger="hover" :items="[{ key: '1', label: '悬停显示' }]">
    <c-button>hover 触发</c-button>
  </c-dropdown>
  &nbsp;
  <c-dropdown trigger="click" :items="[{ key: '1', label: '点我才显示' }]">
    <c-button>click 触发</c-button>
  </c-dropdown>
  &nbsp;
  <c-dropdown trigger="contextmenu" :items="[{ key: '1', label: '右键菜单' }]">
    <c-button>右键此处</c-button>
  </c-dropdown>
</template>
```

:::

## 禁用项与危险项

`disabled` 让单项不可点；`danger` 让单项使用错误色突出（常用于"删除"）；`divided` 在该项上方加分隔线。

:::demo

```vue
<template>
  <c-dropdown
    :items="[
      { key: '1', label: '查看' },
      { key: '2', label: '编辑（禁用）', disabled: true },
      { key: '3', label: '导出' },
      { key: '4', label: '删除', danger: true, divided: true },
    ]"
  >
    <c-button>操作</c-button>
  </c-dropdown>
</template>
```

:::

## 监听选择

`select` 事件返回被选中的菜单项对象。

:::demo

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

const last = ref('未选择')

function onSelect(item) {
  last.value = `${item.label}（key=${item.key}）`
}
</script>

<template>
  <c-dropdown
    :items="[
      { key: 'a', label: '选项 A' },
      { key: 'b', label: '选项 B' },
      { key: 'c', label: '选项 C' },
    ]"
    @select="onSelect"
  >
    <c-button>请选择</c-button>
  </c-dropdown>
  <p style="margin-top: 12px">最近选中：{{ last }}</p>
</template>
```

:::

## 弹出方位

`placement` 与 Popover 一致，支持 12 个方位。

:::demo

```vue
<template>
  <c-dropdown placement="top-start" :items="[{ key: '1', label: '弹向上方' }]">
    <c-button>top-start</c-button>
  </c-dropdown>
  &nbsp;
  <c-dropdown placement="bottom-end" :items="[{ key: '1', label: '右下对齐' }]">
    <c-button>bottom-end</c-button>
  </c-dropdown>
  &nbsp;
  <c-dropdown placement="right-start" :items="[{ key: '1', label: '弹向右侧' }]">
    <c-button>right-start</c-button>
  </c-dropdown>
</template>
```

:::

## 受控显示

通过 `v-model:visible` 自己控制开合，便于联动外部逻辑。

:::demo

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

const visible = ref(false)
</script>

<template>
  <c-button @click="visible = !visible">外部按钮：{{ visible ? '关闭' : '打开' }}</c-button>
  <c-dropdown
    v-model:visible="visible"
    trigger="click"
    :items="[
      { key: '1', label: '受控状态项 1' },
      { key: '2', label: '受控状态项 2' },
    ]"
  >
    <c-button style="margin-inline-start: 12px">触发器</c-button>
  </c-dropdown>
</template>
```

:::

## API

### Props

| 参数        | 类型                                  | 默认值           | 说明                                 |
| ----------- | ------------------------------------- | ---------------- | ------------------------------------ |
| items       | `DropdownItem[]`                      | `[]`             | 菜单项列表                           |
| trigger     | `'hover' \| 'click' \| 'contextmenu'` | `'hover'`        | 触发方式                             |
| placement   | `PopoverPlacement`                    | `'bottom-start'` | 弹出方位（与 Popover 一致）          |
| disabled    | boolean                               | `false`          | 禁用整个下拉                         |
| visible     | boolean                               | `undefined`      | 受控显示状态，支持 `v-model:visible` |
| hideOnClick | boolean                               | `true`           | 点击菜单项后是否自动收起             |
| width       | `number \| string`                    | `''`             | 弹层最小宽度                         |

### DropdownItem

| 字段     | 类型               | 说明                                   |
| -------- | ------------------ | -------------------------------------- |
| key      | `string \| number` | 唯一标识                               |
| label    | string             | 显示文本                               |
| icon     | string             | 图标 class（可选）                     |
| disabled | boolean            | 是否禁用                               |
| divided  | boolean            | 在该项上方加分隔线                     |
| danger   | boolean            | 危险项样式（红色文本，hover 红底白字） |

### Events

| 事件名         | 回调签名               | 触发时机            |
| -------------- | ---------------------- | ------------------- |
| select         | `(item: DropdownItem)` | 点击某一项时触发    |
| update:visible | `(visible: boolean)`   | 弹层显示状态变化    |
| visible-change | `(visible: boolean)`   | 同 `update:visible` |

### Slots

| 名称    | 说明                                                                      |
| ------- | ------------------------------------------------------------------------- |
| default | 触发器                                                                    |
| menu    | 自定义菜单内容（不使用 `items`），slot 参数 `{ select }` 用于主动收起菜单 |


---

# Empty 空状态

> 文档链接：https://vaebe.github.io/ccui/components/empty/index.html

数据缺失或还没创建时的占位提示。

## 何时使用

- 列表 / 表格当前没有任何数据。
- 详情页对应资源未创建（"创建第一个项目"）。
- 搜索、筛选后无结果。

## 基本使用

完全无参时显示默认插画 + 中文 "暂无数据"。

:::demo

```vue
<template>
  <c-empty />
</template>
```

:::

## 自定义文案

通过 `description` 改文案，让空态更贴合业务语义。

:::demo

```vue
<template>
  <c-empty description="还没有任何订单" />
  <c-empty description="未匹配到搜索结果" style="margin-top: 16px" />
</template>
```

:::

## 配合操作按钮

默认插槽放在描述下方，常用于"立即创建 / 重新搜索"等引导操作。

:::demo

```vue
<template>
  <c-empty description="还没有创建任何应用">
    <c-button type="primary">+ 立即创建</c-button>
  </c-empty>
</template>
```

:::

## 使用图片 URL

`image` 接受图片地址，替换默认插画。

:::demo

```vue
<template>
  <c-empty description="搜索没有命中任何条目" image="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI0MSIgdmlld0JveD0iMCAwIDY0IDQxIj48ZyBmaWxsPSJub25lIiBzdHJva2U9InJnYmEoMCwwLDAsMC4yNSkiIHN0cm9rZS13aWR0aD0iMS41IiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNOCAxNiBMMjAgMTYgTDI0IDIyIEw0MCAyMiBMNDQgMTYgTDU2IDE2IEw1MiAzNCBMMTIgMzQgWiIgZmlsbD0icmdiYSgwLDAsMCwwLjA0KSIvPjxwYXRoIGQ9Ik04IDE2IEwxNCA2IEw1MCA2IEw1NiAxNiIvPjwvZz48ZWxsaXBzZSBjeD0iMzIiIGN5PSIzOCIgcng9IjIyIiByeT0iMi41IiBmaWxsPSJyZ2JhKDAsMCwwLDAuMDYpIi8+PC9zdmc+" />
</template>
```

:::

## 调整图片尺寸

`image-style` 接受任意 CSSProperties 对象，常用来缩放或限高。

:::demo

```vue
<template>
  <c-empty description="迷你空态" :image-style="{ height: '32px' }" />
  <c-empty description="大插图空态" :image-style="{ height: '120px' }" style="margin-top: 16px" />
</template>
```

:::

## 自定义插画

`#image` slot 可塞入任意 VNode（SVG / 图标组件）实现完全自定义。

:::demo

```vue
<template>
  <c-empty description="自定义插图">
    <template #image>
      <div
        style="
          width: 80px;
          height: 80px;
          margin: 0 auto;
          border-radius: 50%;
          background: linear-gradient(135deg, #1677ff 0%, #69b1ff 100%);
          display: flex;
          align-items: center;
          justify-content: center;
          color: white;
          font-size: 32px;
        "
      >
        ?
      </div>
    </template>
    <c-button type="primary">了解更多</c-button>
  </c-empty>
</template>
```

:::

## 列表卡片内嵌

把 Empty 直接塞进 Card / 自定义边框容器里，配「立即创建」按钮做引导转化。

:::demo

```vue
<template>
  <div style="border: 1px solid var(--ccui-color-border-secondary); border-radius: 6px; padding: 24px 16px; background: var(--ccui-color-bg-container)">
    <c-empty description="该项目还没有任何成员" :image-style="{ height: '56px' }">
      <c-button type="primary">+ 邀请成员</c-button>
    </c-empty>
  </div>
</template>
```

:::

## 搜索无结果

搜索 / 筛选场景下空态附带「清除筛选」按钮，是一键重置的常用范式。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const keyword = ref('asdfqwer')
const results = ref([])
function reset() {
  keyword.value = ''
}
</script>

<template>
  <c-input v-model="keyword" placeholder="试着搜点什么" style="margin-bottom: 12px" />
  <c-empty v-if="results.length === 0" description="未匹配到任何结果" :image-style="{ height: '48px' }">
    <c-button @click="reset">清除筛选条件</c-button>
  </c-empty>
</template>
```

:::

## 复杂描述（description slot）

需要在描述里放链接 / 多行 / 富文本时改用 `#description` slot，`description` prop 主要面向单行短文案。

:::demo

```vue
<template>
  <c-empty>
    <template #description>
      <div style="color: var(--ccui-color-text-secondary); line-height: 1.6">
        当前账户尚未开通任何应用 <br />
        <a href="#" style="color: var(--ccui-color-primary)">查看接入指引 <c-icon name="mdi:arrow-right" /></a>
      </div>
    </template>
    <c-button type="primary">立即开通</c-button>
  </c-empty>
</template>
```

:::

## 三种尺寸

`imageStyle.height` 控制插图尺寸：32 适合表格内嵌、80 默认、120 用于专门的空页面。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px; align-items: flex-end; flex-wrap: wrap">
    <div>
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">迷你（嵌入式）</p>
      <c-empty description="无数据" :image-style="{ height: '32px' }" />
    </div>
    <div>
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">默认</p>
      <c-empty description="暂无数据" />
    </div>
    <div>
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">大插图（专题页）</p>
      <c-empty description="还没有任何项目" :image-style="{ height: '120px' }" />
    </div>
  </div>
</template>
```

:::

## Tabs 内嵌空态

不同 tab 下视为独立空状态：选中后展示对应文案，方便业务定位「具体哪个维度没数据」。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const active = ref('订单')
</script>

<template>
  <c-segmented v-model="active" :options="['订单', '退款', '评价']" style="margin-bottom: 16px" />
  <c-empty :description="`暂无任何${active}记录`" :image-style="{ height: '48px' }" />
</template>
```

:::

## API

### Props

| 参数        | 类型            | 默认值       | 说明           |
| ----------- | --------------- | ------------ | -------------- |
| description | string          | `'暂无数据'` | 描述文案       |
| image       | string          | `''`         | 自定义图片 URL |
| imageStyle  | `CSSProperties` | `{}`         | 图片元素样式   |

### Slots

| 名称        | 说明                                  |
| ----------- | ------------------------------------- |
| default     | 描述下方的额外内容                    |
| description | 自定义描述（覆盖 `description` 属性） |
| image       | 自定义插画                            |


---

# Flex 弹性布局

> 文档链接：https://vaebe.github.io/ccui/components/flex/index.html

封装 CSS flexbox 的常用属性，配合主题间距 token 让"行内 / 垂直 / 两端对齐"等场景更直白。

## 何时使用

- 行内或垂直排列一组组件，间距用 token 控制。
- 两端对齐：左侧标题 + 右侧操作按钮。
- 子元素需要 `flex-grow` 自动撑开剩余空间。

## 基本使用

默认水平方向，`gap` 决定间距（数字按 px，也可用 `small` / `middle` / `large`）。

:::demo

```vue
<template>
  <c-flex :gap="12">
    <c-button>Button 1</c-button>
    <c-button>Button 2</c-button>
    <c-button>Button 3</c-button>
  </c-flex>
</template>
```

:::

## 间距预设

`gap` 接收 `'small'` / `'middle'` / `'large'`，分别对应 8 / 16 / 24px。

:::demo

```vue
<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">small</p>
  <c-flex gap="small"><c-tag>tag</c-tag><c-tag>tag</c-tag><c-tag>tag</c-tag></c-flex>

  <p style="color: var(--ccui-color-text-secondary); margin: 12px 0 4px">middle</p>
  <c-flex gap="middle"><c-tag>tag</c-tag><c-tag>tag</c-tag><c-tag>tag</c-tag></c-flex>

  <p style="color: var(--ccui-color-text-secondary); margin: 12px 0 4px">large</p>
  <c-flex gap="large"><c-tag>tag</c-tag><c-tag>tag</c-tag><c-tag>tag</c-tag></c-flex>
</template>
```

:::

## 垂直布局

`vertical` 把方向切到列。

:::demo

```vue
<template>
  <c-flex vertical :gap="8" style="width: 200px">
    <c-button>Button 1</c-button>
    <c-button>Button 2</c-button>
    <c-button>Button 3</c-button>
  </c-flex>
</template>
```

:::

## 对齐方式

`justify` 对应 `justify-content`，`align` 对应 `align-items`。

:::demo

```vue
<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">justify="space-between"（两端对齐）</p>
  <c-flex justify="space-between" align="center" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-tag>左</c-tag>
    <c-button>右</c-button>
  </c-flex>

  <p style="color: var(--ccui-color-text-secondary); margin: 12px 0 4px">justify="space-evenly"（等距）</p>
  <c-flex justify="space-evenly" align="center" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-tag>1</c-tag>
    <c-tag>2</c-tag>
    <c-tag>3</c-tag>
  </c-flex>

  <p style="color: var(--ccui-color-text-secondary); margin: 12px 0 4px">justify="center"（居中）</p>
  <c-flex justify="center" align="center" gap="small" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-tag>居中</c-tag>
    <c-button type="primary">操作</c-button>
  </c-flex>
</template>
```

:::

## 自动换行

`wrap` 设为 `true`（或具体的 `wrap` / `wrap-reverse` / `nowrap`）控制超出容器时是否换行。

:::demo

```vue
<template>
  <c-flex wrap gap="small" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-tag v-for="i in 12" :key="i">Tag {{ i }}</c-tag>
  </c-flex>
</template>
```

:::

## 用 `flex` 简写撑满剩余空间

子组件包一层 `<c-flex>` 并设置 `flex="1"` 可以让它独占剩余空间。

:::demo

```vue
<template>
  <c-flex gap="middle" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-button>固定</c-button>
    <c-flex flex="1" justify="center" align="center" style="background: var(--ccui-color-bg-container); border-radius: 4px; padding: 8px">
      撑开剩余空间
    </c-flex>
    <c-button type="primary">固定</c-button>
  </c-flex>
</template>
```

:::

## 自定义元素

`component` 改变渲染的标签，常用于语义化（`section` / `nav` / `header` 等）。

:::demo

```vue
<template>
  <c-flex component="nav" gap="middle" style="background: var(--ccui-area); padding: 12px; border-radius: 6px">
    <a href="#" style="color: inherit">首页</a>
    <a href="#" style="color: inherit">文档</a>
    <a href="#" style="color: inherit">关于</a>
  </c-flex>
</template>
```

:::

## `justify` 全枚举

横轴对齐六种取值的视觉对照。

:::demo

```vue
<script setup>
const justifies = ['flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly']
</script>

<template>
  <c-flex vertical :gap="12">
    <div v-for="j in justifies" :key="j">
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">justify="{{ j }}"</p>
      <c-flex
        :justify="j"
        align="center"
        style="background: var(--ccui-area); padding: 8px; border-radius: 6px; min-height: 40px"
      >
        <c-tag>A</c-tag>
        <c-tag>B</c-tag>
        <c-tag>C</c-tag>
      </c-flex>
    </div>
  </c-flex>
</template>
```

:::

## `align` 全枚举

纵轴对齐五种取值的视觉对照（容器有显式高度时差异最明显）。

:::demo

```vue
<script setup>
const aligns = ['flex-start', 'center', 'flex-end', 'baseline', 'stretch']
</script>

<template>
  <c-flex vertical :gap="12">
    <div v-for="a in aligns" :key="a">
      <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">align="{{ a }}"</p>
      <c-flex :align="a" gap="small" style="background: var(--ccui-area); padding: 8px; border-radius: 6px; height: 80px">
        <c-tag style="font-size: 12px">12px</c-tag>
        <c-tag style="font-size: 20px">20px</c-tag>
        <c-tag style="font-size: 14px">14px</c-tag>
      </c-flex>
    </div>
  </c-flex>
</template>
```

:::

## 反向换行

`wrap="wrap-reverse"` 让超出的子项在前一行的上方折回。

:::demo

```vue
<template>
  <c-flex wrap="wrap-reverse" gap="small" style="background: var(--ccui-area); padding: 8px; border-radius: 6px">
    <c-tag v-for="i in 10" :key="i">Tag {{ i }}</c-tag>
  </c-flex>
</template>
```

:::

## 嵌套布局：页面骨架

`vertical` + 子级 `<c-flex>` 组合可以快速搭出「页头 / 主体（侧栏 + 内容）/ 页脚」三段式骨架。

:::demo

```vue
<template>
  <c-flex vertical style="background: var(--ccui-area); border-radius: 6px; height: 240px; overflow: hidden">
    <c-flex
      justify="space-between"
      align="center"
      style="padding: 12px 16px; background: var(--ccui-color-bg-container); border-bottom: 1px solid var(--ccui-color-border-secondary)"
    >
      <strong>页头</strong>
      <c-button size="small">登出</c-button>
    </c-flex>
    <c-flex flex="1" style="overflow: hidden">
      <c-flex
        vertical
        gap="small"
        style="width: 120px; padding: 12px; background: var(--ccui-area); border-right: 1px solid var(--ccui-color-border-secondary)"
      >
        <c-tag>菜单 1</c-tag>
        <c-tag>菜单 2</c-tag>
        <c-tag>菜单 3</c-tag>
      </c-flex>
      <c-flex flex="1" justify="center" align="center" style="padding: 16px; background: var(--ccui-color-bg-container)">
        <span style="color: var(--ccui-color-text-tertiary)">主内容区</span>
      </c-flex>
    </c-flex>
    <c-flex
      justify="center"
      align="center"
      style="padding: 8px; background: var(--ccui-color-bg-container); border-top: 1px solid var(--ccui-color-border-secondary); color: var(--ccui-color-text-tertiary); font-size: 12px"
    >
      © 2026 ccui
    </c-flex>
  </c-flex>
</template>
```

:::

## 业务工具栏（与 Space 区别）

`<c-flex justify="space-between">` 适合「左标题 / 右操作」两端分布；`<c-space>` 更适合一组按钮挨在一起的等距间隔。两者可以套用：外 Flex 分两端，内 Space 排操作组。

:::demo

```vue
<template>
  <c-flex
    justify="space-between"
    align="center"
    style="background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); padding: 12px 16px; border-radius: 6px"
  >
    <strong>订单列表</strong>
    <c-space>
      <c-button size="small">导出</c-button>
      <c-button size="small">筛选</c-button>
      <c-button size="small" type="primary">新建</c-button>
    </c-space>
  </c-flex>
</template>
```

:::

## API

### Props

| 参数      | 类型                                              | 默认值     | 说明                                      |
| --------- | ------------------------------------------------- | ---------- | ----------------------------------------- |
| vertical  | boolean                                           | `false`    | 垂直方向                                  |
| wrap      | `boolean \| 'wrap' \| 'nowrap' \| 'wrap-reverse'` | `false`    | 是否换行                                  |
| justify   | `CSSProperties['justifyContent']`                 | `'normal'` | 对应 `justify-content`                    |
| align     | `CSSProperties['alignItems']`                     | `'normal'` | 对应 `align-items`                        |
| flex      | string                                            | `'normal'` | flex 简写（如 `'1'`, `'0 0 auto'`）       |
| gap       | `string \| number`                                | —          | 间距：`small` / `middle` / `large` 或数字 |
| component | string                                            | `'div'`    | 渲染的标签                                |


---

# FloatButton 悬浮按钮

> 文档链接：https://vaebe.github.io/ccui/components/float-button/index.html

固定在视图角落的按钮。

## 基本使用

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }">
      <template #icon>
        <c-icon name="mdi:help-circle-outline" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 主色 + 徽标

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button
      type="primary"
      :badge="5"
      :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }"
    >
      <template #icon>
        <c-icon name="mdi:bell-outline" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 方形

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button shape="square" :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }">
      <template #icon>
        <c-icon name="mdi:home-outline" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 图标按钮

通过 `#icon` slot 放入任意图标组件（推荐 `<c-icon>`）；`description` 同时存在时图标在上、文字在下。`icon` prop 仅适用于 iconfont 类名（无内置字体图标时为空，按需使用）。

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button description="帮助" :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }">
      <template #icon>
        <c-icon name="mdi:help-circle-outline" :size="20" />
      </template>
    </c-float-button>
    <c-float-button
      type="primary"
      description="客服"
      :style="{ insetBlockEnd: '80px', insetInlineEnd: '16px', position: 'absolute' }"
    >
      <template #icon>
        <c-icon name="mdi:message-text-outline" :size="20" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 链接跳转

`href` + `target` 使按钮作为链接使用，例如「联系我们」「打开文档」。

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button
      href="https://github.com/vaebe/ccui"
      target="_blank"
      :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }"
    >
      <template #icon>
        <c-icon name="mdi:file-document-outline" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 悬浮提示（tooltip）

`tooltip` 鼠标 hover 时显示提示文字。

:::demo

```vue
<template>
  <div style="position: relative; height: 200px; background: var(--ccui-area)">
    <c-float-button
      type="primary"
      tooltip="点击查看帮助文档"
      :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }"
    >
      <template #icon>
        <c-icon name="mdi:help-circle-outline" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## 多按钮组合

通过 `inset-*` 偏移叠放多个 FloatButton，构成右下角操作组。

:::demo

```vue
<template>
  <div style="position: relative; height: 280px; background: var(--ccui-area)">
    <c-float-button tooltip="帮助" :style="{ insetBlockEnd: '16px', insetInlineEnd: '16px', position: 'absolute' }">
      <template #icon>
        <c-icon name="mdi:help-circle-outline" />
      </template>
    </c-float-button>
    <c-float-button tooltip="反馈" :style="{ insetBlockEnd: '80px', insetInlineEnd: '16px', position: 'absolute' }">
      <template #icon>
        <c-icon name="mdi:email-outline" />
      </template>
    </c-float-button>
    <c-float-button
      type="primary"
      :badge="3"
      tooltip="新建工单"
      :style="{ insetBlockEnd: '144px', insetInlineEnd: '16px', position: 'absolute' }"
    >
      <template #icon>
        <c-icon name="mdi:plus" />
      </template>
    </c-float-button>
  </div>
</template>
```

:::

## BackTop 回到顶部

> 滚动到 400px 以下后右下角出现「回到顶部」按钮，点击平滑滚回顶端。

:::demo

```vue
<template>
  <c-back-top />
</template>
```

:::

## BackTop 自定义阈值

`visibility-height` 控制按钮出现的滚动阈值（默认 400px），`duration` 控制滚回动画时长（默认 450ms）。

:::demo

```vue
<template>
  <c-back-top :visibility-height="100" :duration="800" />
  <div style="color: var(--ccui-color-text-tertiary); font-size: 12px">滚动超过 100px 即出现按钮，动画时长 800ms。</div>
</template>
```

:::

## BackTop 自定义形状 / 类型

`shape` / `type` / `icon` 与 FloatButton 一致，可定制按钮外观。

:::demo

```vue
<template>
  <c-back-top type="primary" shape="square" />
</template>
```

:::

## API

### FloatButton Props

| 参数        | 类型                     | 默认值      | 说明                                                   |
| ----------- | ------------------------ | ----------- | ------------------------------------------------------ |
| shape       | `'circle' \| 'square'`   | `'circle'`  | 形状                                                   |
| type        | `'default' \| 'primary'` | `'default'` | 类型                                                   |
| description | string                   | —           | 内部文字（与 icon 同时存在时在下方）                   |
| icon        | string                   | —           | iconfont CSS 类名；推荐改用 `#icon` slot 放 `<c-icon>` |
| badge       | `number \| string`       | —           | 右上角徽标数                                           |
| href        | string                   | —           | 链接地址                                               |
| target      | string                   | —           | 链接 target（`_blank` 等）                             |
| tooltip     | string                   | —           | 悬浮提示文字                                           |

### FloatButton Slots

| 名称        | 说明                                            |
| ----------- | ----------------------------------------------- |
| icon        | 自定义图标（覆盖 `icon` prop，推荐 `<c-icon>`） |
| description | 自定义文字内容（覆盖 `description` prop）       |

### BackTop Props

| 参数             | 类型                                           | 默认值      | 说明                                                   |
| ---------------- | ---------------------------------------------- | ----------- | ------------------------------------------------------ |
| visibilityHeight | number                                         | `400`       | 滚动条到达多少 px 时显示按钮                           |
| duration         | number                                         | `450`       | 滚回顶部的动画时长（ms）                               |
| target           | `string \| HTMLElement \| (() => HTMLElement)` | `window`    | 监听滚动的目标容器                                     |
| shape            | `'circle' \| 'square'`                         | `'circle'`  | 形状                                                   |
| type             | `'default' \| 'primary'`                       | `'default'` | 类型                                                   |
| icon             | string                                         | —           | iconfont CSS 类名；推荐改用 `#icon` slot 放 `<c-icon>` |


---

# Form 表单

> 文档链接：https://vaebe.github.io/ccui/components/form/index.html

用于收集、校验和提交一组输入项。`validateDebounce` / `normalize` 等边角能力后续迭代。

## 基本使用

:::demo

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

const model = reactive({
  name: '',
  city: '',
})

const cityOptions = [
  { label: 'Beijing', value: 'beijing' },
  { label: 'Shanghai', value: 'shanghai' },
]
</script>

<template>
  <c-form :model="model" label-width="88px">
    <c-form-item label="Name" name="name" required>
      <c-input v-model="model.name" placeholder="Enter name" />
    </c-form-item>
    <c-form-item label="City" name="city" extra="Choose the city used for delivery.">
      <c-select v-model="model.city" :options="cityOptions" placeholder="Select city" />
    </c-form-item>
  </c-form>
</template>
```

:::

## 表单校验

:::demo

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

const formRef = ref()
const model = reactive({
  email: '',
})
const rules = {
  email: [
    { required: true, message: 'Email is required', trigger: 'blur' },
    { type: 'email', message: 'Email is invalid', trigger: 'change' },
  ],
}

function submit() {
  formRef.value?.validate()
}
</script>

<template>
  <c-form ref="formRef" :model="model" :rules="rules" label-width="88px" scroll-to-first-error>
    <c-form-item label="Email" name="email">
      <c-input v-model="model.email" placeholder="name@example.com" />
    </c-form-item>
    <c-form-item>
      <c-button type="primary" @click="submit">Submit</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 初始值和依赖校验

:::demo

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

const model = reactive({
  user: { email: '' },
  password: '',
  confirm: '',
})

const initialValues = {
  user: { email: 'user@example.com' },
}

const confirmRule = {
  validator: (_rule, value) => value === model.password || 'Passwords differ',
}
</script>

<template>
  <c-form :model="model" :initial-values="initialValues" layout="vertical" required-mark="optional">
    <c-form-item label="Email" :name="['user', 'email']" :rules="{ type: 'email' }">
      <c-input v-model="model.user.email" />
    </c-form-item>
    <c-form-item label="Password" name="password" required>
      <c-input v-model="model.password" type="password" />
    </c-form-item>
    <c-form-item label="Confirm" name="confirm" :dependencies="['password']" :rules="confirmRule">
      <c-input v-model="model.confirm" type="password" />
    </c-form-item>
  </c-form>
</template>
```

:::

## 函数式 rules

`rules` 接受工厂函数 `(model) => Rule | Rule[]`，每次校验时执行，可基于当前 form model 派生动态规则。常见场景：confirm 字段对比 password、互斥字段（A 填了 B 必填）、长度跟随类型变化。

:::demo

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

const formRef = ref()
const model = reactive({
  password: '',
  confirm: '',
  phone: '',
  email: '',
})

const confirmRules = (m) => [
  { required: true, message: '请再次输入密码', trigger: 'blur' },
  {
    validator: (_r, v) => v === m.password || '两次密码不一致',
    trigger: 'change',
  },
]

const phoneRules = (m) => [
  {
    required: !m.email,
    message: '邮箱为空时手机必填',
    trigger: 'blur',
  },
]

async function submit() {
  try {
    await formRef.value.validate()
    alert('校验通过')
  } catch {}
}
</script>

<template>
  <c-form ref="formRef" :model="model" label-width="100px">
    <c-form-item label="密码" name="password" required>
      <c-input v-model="model.password" type="password" />
    </c-form-item>
    <c-form-item label="确认密码" name="confirm" :rules="confirmRules" :dependencies="['password']">
      <c-input v-model="model.confirm" type="password" />
    </c-form-item>
    <c-form-item label="邮箱" name="email">
      <c-input v-model="model.email" placeholder="可选" />
    </c-form-item>
    <c-form-item label="手机" name="phone" :rules="phoneRules" :dependencies="['email']">
      <c-input v-model="model.phone" placeholder="邮箱为空时必填" />
    </c-form-item>
    <c-form-item>
      <c-button type="primary" @click="submit">提交</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## warningOnly 警告级规则

规则上加 `warningOnly: true`，校验失败时 FormItem 状态降级为 `warning`，**不阻塞** form-level submit。适合「弱密码提醒」「价格异常但允许通过」等需要提示却不强制拦截的场景。

:::demo

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

const formRef = ref()
const log = ref('')
const model = reactive({
  password: '',
  price: 100,
})

const rules = {
  password: [
    { required: true, message: '请输入密码', trigger: 'blur' },
    {
      validator: (_r, v) => v.length >= 8 || '建议至少 8 个字符（弱密码）',
      warningOnly: true,
      trigger: 'change',
    },
  ],
  price: [
    {
      validator: (_r, v) => Number(v) <= 1000 || `当前 ${v} 已超 1000，请确认是否合理`,
      warningOnly: true,
      trigger: 'change',
    },
  ],
}

async function submit() {
  const valid = await formRef.value.validate()
  log.value = valid ? '提交成功（warningOnly 不阻塞）' : '校验失败被阻塞'
}
</script>

<template>
  <c-form ref="formRef" :model="model" :rules="rules" label-width="80px">
    <c-form-item label="密码" name="password">
      <c-input v-model="model.password" type="password" placeholder="试输入短于 8 字符" />
    </c-form-item>
    <c-form-item label="价格" name="price">
      <c-input-number v-model="model.price" />
    </c-form-item>
    <c-form-item>
      <c-button type="primary" @click="submit">提交</c-button>
    </c-form-item>
    <p style="color:var(--ccui-color-text-secondary);margin:0">{{ log || '弱密码 / 价格 > 1000 会显示 warning 但不阻塞提交' }}</p>
  </c-form>
</template>
```

:::

## hasFeedback 校验状态图标

`hasFeedback=true` 在控件右侧显示对应状态图标（`✓` success / `✕` error / `!` warning / `◌` validating）；可在 Form 级开关后所有 FormItem 默认显示，单 FormItem 可显式覆盖。

:::demo

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

const model = reactive({
  name: '',
  email: '',
  age: '',
  status: '',
})

const rules = {
  name: { required: true, message: '请输入姓名', trigger: 'blur' },
  email: { required: true, type: 'email', message: '邮箱格式不正确', trigger: 'change' },
}
</script>

<template>
  <c-form :model="model" :rules="rules" label-width="100px" has-feedback>
    <c-form-item label="姓名" name="name">
      <c-input v-model="model.name" placeholder="必填，校验后显示 ✓ / ✕" />
    </c-form-item>
    <c-form-item label="邮箱" name="email">
      <c-input v-model="model.email" placeholder="格式校验，change 触发" />
    </c-form-item>
    <c-form-item label="年龄（不显示）" name="age" :has-feedback="false">
      <c-input v-model="model.age" placeholder="单字段关掉 feedback" />
    </c-form-item>
    <c-form-item label="状态（强制 warning）" name="status" validate-status="warning" help="单独指定 warning 演示图标">
      <c-input v-model="model.status" />
    </c-form-item>
  </c-form>
</template>
```

:::

## 必填 / 可选标记

`requiredMark` 控制必填提示策略：`true`（默认，必填字段左侧加 `*`）/ `false`（不显示任何标记）/ `'optional'`（非必填字段右侧加 `(optional)`，移动端常用）。

:::demo

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

const mark = ref('true')
const value = computed(() => (mark.value === 'true' ? true : mark.value === 'false' ? false : mark.value))
const model = reactive({ name: '', desc: '' })
</script>

<template>
  <div style="margin-bottom:12px">
    <c-segmented v-model="mark" :options="['true', 'false', 'optional']" />
  </div>
  <c-form :model="model" :required-mark="value" label-width="80px">
    <c-form-item label="姓名" name="name" required>
      <c-input v-model="model.name" />
    </c-form-item>
    <c-form-item label="简介" name="desc">
      <c-input v-model="model.desc" placeholder="非必填字段" />
    </c-form-item>
  </c-form>
</template>
```

:::

## 动态字段 Form.List

通过 `<c-form-list>` 管理一组同构字段。默认作用域插槽提供 `(fields, { add, remove, move })`，每个 `field` 包含 `key`（稳定 key，移动后保持）和 `name`（当前下标，参与 name path 拼接）。

:::demo

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

const model = reactive<{ users: Array<{ name: string; email: string }> }>({
  users: [{ name: 'Alice', email: 'alice@example.com' }],
})
</script>

<template>
  <c-form :model="model" layout="vertical">
    <c-form-list name="users">
      <template #default="{ fields, add, remove, move }">
        <div v-for="field in fields" :key="field.key" style="display: flex; gap: 8px;">
          <c-form-item :name="[field.name, 'name']" :rules="{ required: true, message: 'Name required' }">
            <c-input v-model="model.users[field.name].name" placeholder="name" />
          </c-form-item>
          <c-form-item :name="[field.name, 'email']" :rules="{ type: 'email' }">
            <c-input v-model="model.users[field.name].email" placeholder="email" />
          </c-form-item>
          <c-button @click="move(field.name, Math.max(0, field.name - 1))"><c-icon name="mdi:arrow-up" /></c-button>
          <c-button @click="remove(field.name)">remove</c-button>
        </div>
        <c-button @click="add({ name: '', email: '' })">add user</c-button>
      </template>
    </c-form-list>
  </c-form>
</template>
```

:::

## 不同布局

`layout` 切换 `horizontal`（默认）/ `vertical`（标签在上，输入在下，常用于移动端）/ `inline`（行内紧凑布局，filter / search 场景）。

:::demo

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

const m1 = reactive({ name: '' })
const m2 = reactive({ name: '', email: '' })
const m3 = reactive({ keyword: '', status: '' })
</script>

<template>
  <p style="margin: 0 0 6px; color: var(--ccui-color-text-secondary)">layout="horizontal"（默认）</p>
  <c-form :model="m1" label-width="80px">
    <c-form-item label="姓名" name="name"><c-input v-model="m1.name" /></c-form-item>
  </c-form>

  <p style="margin: 16px 0 6px; color: var(--ccui-color-text-secondary)">layout="vertical"</p>
  <c-form :model="m2" layout="vertical">
    <c-form-item label="姓名" name="name"><c-input v-model="m2.name" /></c-form-item>
    <c-form-item label="邮箱" name="email"><c-input v-model="m2.email" /></c-form-item>
  </c-form>

  <p style="margin: 16px 0 6px; color: var(--ccui-color-text-secondary)">layout="inline"</p>
  <c-form :model="m3" layout="inline">
    <c-form-item label="关键词" name="keyword"><c-input v-model="m3.keyword" /></c-form-item>
    <c-form-item label="状态" name="status">
      <c-select
        v-model="m3.status"
        :options="[
          { label: '在售', value: 'on' },
          { label: '下架', value: 'off' },
        ]"
        style="width: 120px"
      />
    </c-form-item>
    <c-form-item><c-button type="primary">查询</c-button></c-form-item>
  </c-form>
</template>
```

:::

## 栅格 labelCol / wrapperCol

`labelCol` / `wrapperCol` 接收 24 栅格对象 `{ span?, offset?, flex? }`，按 `(span/24)*100%` 换算为宽度，比 `labelWidth` 的单一像素方案更适合响应式表单。Form 级配置作为默认；FormItem 显式同名 prop 优先覆盖。

:::demo

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

const model = reactive({ name: '', email: '', desc: '' })
</script>

<template>
  <c-form :model="model" :label-col="{ span: 6 }" :wrapper-col="{ span: 16 }">
    <c-form-item label="姓名" name="name">
      <c-input v-model="model.name" />
    </c-form-item>
    <c-form-item label="邮箱" name="email">
      <c-input v-model="model.email" />
    </c-form-item>
    <c-form-item label="个人简介" name="desc" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
      <c-input v-model="model.desc" placeholder="本行覆盖 form 级：label 4 / wrapper 20" />
    </c-form-item>
    <c-form-item :wrapper-col="{ offset: 6, span: 16 }">
      <c-button type="primary">保存</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 全表 disabled / 提交中态切换

`disabled` 在 Form 级开启会给整个 form 加上 disabled 样式标记，配合「保存中锁表」「待审核只读」业务非常常见。

:::demo

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

const formRef = ref()
const submitting = ref(false)
const log = ref('')
const model = reactive({ name: '', email: '' })
const rules = {
  name: { required: true, message: '请输入姓名', trigger: 'blur' },
  email: { required: true, type: 'email', message: '邮箱格式不正确', trigger: 'change' },
}

async function submit() {
  const valid = await formRef.value.validate()
  if (!valid) return
  submitting.value = true
  log.value = '提交中...'
  setTimeout(() => {
    submitting.value = false
    log.value = '提交完成'
  }, 1500)
}
</script>

<template>
  <c-form ref="formRef" :model="model" :rules="rules" label-width="80px" :disabled="submitting">
    <c-form-item label="姓名" name="name"><c-input v-model="model.name" /></c-form-item>
    <c-form-item label="邮箱" name="email"><c-input v-model="model.email" /></c-form-item>
    <c-form-item>
      <c-button type="primary" :loading="submitting" @click="submit">{{ submitting ? '提交中' : '提交' }}</c-button>
    </c-form-item>
  </c-form>
  <p style="color:var(--ccui-color-text-secondary)">{{ log || '提交后整个表单进入 disabled 状态，1.5s 后恢复' }}</p>
</template>
```

:::

## 实例方法

通过 `ref` 拿到 `FormInstance`，可调用 `validate` / `resetFields` / `clearValidate` / `scrollToField` 等方法。

:::demo

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

const formRef = ref()
const model = reactive({ name: '', email: '' })
const rules = {
  name: { required: true, message: '请输入姓名', trigger: 'blur' },
  email: { required: true, type: 'email', message: '邮箱格式不正确', trigger: 'change' },
}
const log = ref('（未操作）')

async function validate() {
  try {
    await formRef.value.validate()
    log.value = '校验通过'
  } catch {
    log.value = '校验未通过'
  }
}
function reset() {
  formRef.value.resetFields()
  log.value = '已重置'
}
function clear() {
  formRef.value.clearValidate()
  log.value = '已清空校验状态'
}
</script>

<template>
  <c-form ref="formRef" :model="model" :rules="rules" label-width="80px">
    <c-form-item label="姓名" name="name"><c-input v-model="model.name" /></c-form-item>
    <c-form-item label="邮箱" name="email"><c-input v-model="model.email" /></c-form-item>
    <c-form-item>
      <c-button type="primary" @click="validate">校验</c-button>
      <c-button style="margin-inline-start: 8px" @click="reset">重置</c-button>
      <c-button style="margin-inline-start: 8px" @click="clear">清空校验</c-button>
    </c-form-item>
  </c-form>
  <p style="color: var(--ccui-color-text-secondary)">{{ log }}</p>
</template>
```

:::

## 跨表单联动 Form.Provider

`<c-form-provider>` 包裹多个具名 `<c-form>`，在子表单提交成功后通过 `form-finish` 聚合 `forms` 注册表，常用于"同一页面里 A 表单提交后用 B 表单的当前值做联动"的场景。

`form-change` 在任意字段值变化时触发，回调签名同 `form-finish`。

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

const profile = reactive({ name: '' })
const billing = reactive({ address: '' })

function onFinish(name: string, info: { values: any; forms: Record<string, any> }) {
  if (name === 'profile') {
    billing.address = info.forms.billing.getFieldsValue().address
  }
}
</script>

<template>
  <c-form-provider @form-finish="onFinish">
    <c-form name="profile" :model="profile">
      <c-form-item name="name"><c-input v-model="profile.name" /></c-form-item>
      <c-button native-type="submit">Save</c-button>
    </c-form>
    <c-form name="billing" :model="billing">
      <c-form-item name="address"><c-input v-model="billing.address" /></c-form-item>
    </c-form>
  </c-form-provider>
</template>
```

## 字段保留策略 preserve

Form 默认在字段卸载时保留 `model` 中的值（`preserve=true`）。把 `preserve=false` 配置在表单上则全表单字段卸载即清理，单个 `c-form-item` 上的 `preserve` 优先于表单级配置：

```vue
<c-form :model="model" :preserve="false">
  <c-form-item v-if="advanced" name="apiKey" :preserve="true">
    <c-input v-model="model.apiKey" />
  </c-form-item>
</c-form>
```

## 参数

### Form

| 参数                 | 类型                                                          | 默认值     | 说明                                                         |
| -------------------- | ------------------------------------------------------------- | ---------- | ------------------------------------------------------------ |
| model                | object                                                        | {}         | 表单数据对象                                                 |
| rules                | FormRules                                                     | {}         | 表单校验规则                                                 |
| initialValues        | object                                                        | {}         | 表单初始值                                                   |
| labelWidth           | string / number                                               | --         | 标签宽度（简单场景）；`labelCol` 优先级更高                  |
| labelCol             | `{ span?: number; offset?: number; flex?: string \| number }` | --         | 24 栅格布局的 label 列配置，按 `(span/24)*100%` 换算为 width |
| wrapperCol           | 同 labelCol                                                   | --         | 表单控件区列配置                                             |
| labelPosition        | left / right / top                                            | right      | 标签位置                                                     |
| layout               | horizontal / vertical / inline                                | horizontal | 表单布局                                                     |
| disabled             | boolean                                                       | false      | 禁用态样式标记                                               |
| colon                | boolean                                                       | true       | 是否显示标签冒号                                             |
| requiredMark         | boolean / 'optional'                                          | true       | 必填/可选标记显示策略                                        |
| hasFeedback          | boolean                                                       | false      | 校验状态图标（FormItem 显式优先；图标随 currentStatus 切）   |
| validateMessages     | FormValidateMessages                                          | {}         | 校验消息模板                                                 |
| validateOnRuleChange | boolean                                                       | true       | 规则变化时清理校验状态                                       |
| scrollToFirstError   | boolean / ScrollIntoViewOptions                               | false      | 校验失败时滚动到首个错误字段                                 |
| name                 | string                                                        | --         | 表单名（接入 FormProvider）                                  |
| preserve             | boolean                                                       | true       | 字段卸载时是否保留 model 值                                  |

### FormItem

| 参数             | 类型                                                            | 默认值    | 说明                                                                             |
| ---------------- | --------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------- |
| name             | string / number / array                                         | --        | 字段路径，支持数组路径                                                           |
| label            | string                                                          | --        | 标签文本                                                                         |
| labelCol         | 同 Form 同名 prop                                               | --        | 当前项 label 列配置（显式优先于 Form 级）                                        |
| wrapperCol       | 同 Form 同名 prop                                               | --        | 当前项控件列配置                                                                 |
| initialValue     | any                                                             | --        | 字段初始值                                                                       |
| required         | boolean                                                         | false     | 是否必填                                                                         |
| rules            | `FormRule \| FormRule[] \| ((model) => FormRule \| FormRule[])` | --        | 字段校验规则（支持函数式动态生成）                                               |
| help             | string                                                          | --        | 帮助或外部错误文案                                                               |
| extra            | string                                                          | --        | 额外提示文案                                                                     |
| validateStatus   | success / error / warning / validating                          | --        | 外部校验状态（含 warning，配合 `warningOnly` rule）                              |
| hasFeedback      | boolean                                                         | 跟随 Form | 校验状态图标（图标 ✓ / ✕ / ! / ◌ 随 currentStatus 切，input padding-right 让位） |
| dependencies     | FormNamePath[]                                                  | []        | 依赖字段变化后重新校验当前项                                                     |
| validateDebounce | number                                                          | --        | 触发校验的 debounce ms                                                           |
| normalize        | `(value, prevValue, allValues) => any`                          | --        | 在校验/提交前 normalize 值                                                       |
| htmlFor          | string                                                          | --        | label 的 for 属性                                                                |
| colon            | boolean                                                         | 跟随 Form | 是否显示当前项冒号                                                               |
| hidden           | boolean                                                         | false     | 隐藏字段但保留注册                                                               |
| noStyle          | boolean                                                         | false     | 不显示标准表单项样式                                                             |
| preserve         | boolean                                                         | 跟随 Form | 字段卸载是否保留值，覆盖表单级配置                                               |

> **未实现的 API**：`valuePropName` / `getValueFromEvent` / `getValueProps` —— Vue 的 `v-model` 已统一协议。Vue 响应式自动处理依赖收集，无需 `shouldUpdate`。
>
> `FormRule.warningOnly: boolean`：失败时降级为 `warning`，不阻塞 form-level submit。

### FormRule

| 字段        | 类型                                                                   | 说明                                                      |
| ----------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| required    | boolean                                                                | 是否必填                                                  |
| message     | string                                                                 | 校验失败提示文案（不传时走 validateMessages 模板）        |
| trigger     | 'change' / 'blur' / 'submit' 或其数组                                  | 触发时机                                                  |
| type        | 'string' / 'number' / 'boolean' / 'array' / 'object' / 'email' / 'url' | 类型校验                                                  |
| min / max   | number                                                                 | 长度（string / array）或数值上下限                        |
| len         | number                                                                 | 精确长度                                                  |
| pattern     | RegExp                                                                 | 正则校验                                                  |
| enum        | any[]                                                                  | 枚举校验                                                  |
| whitespace  | boolean                                                                | 是否拒绝纯空白字符串                                      |
| warningOnly | boolean                                                                | 失败时降级为 warning 状态，不阻塞 form-level submit       |
| validator   | `(rule, value, model) => boolean \| string \| Error \| Promise<...>`   | 自定义同步 / 异步校验函数（返回 false / string 视为失败） |

### FormList

| 参数         | 类型                    | 默认值 | 说明                             |
| ------------ | ----------------------- | ------ | -------------------------------- |
| name         | string / number / array | --     | 列表字段路径                     |
| initialValue | any[]                   | --     | 列表初始值（model 中无值时使用） |

默认作用域插槽签名：`(fields: { key, name }[], { add, remove, move })`。`add(value?, insertIndex?)` / `remove(index | indices)` / `move(from, to)` 直接修改 `model[name]` 数组并维持稳定 key。

### FormProvider

无 props。事件：

| 事件        | 回调签名                         | 说明                       |
| ----------- | -------------------------------- | -------------------------- |
| form-change | (name, { changedFields, forms }) | 任意字段变化触发           |
| form-finish | (name, { values, forms })        | 子表单 submit 校验通过触发 |

`forms` 是 `Record<string, FormInstance>`，`FormInstance` 暴露 `validate / validateField / resetFields / clearValidate / scrollToField / getFieldsValue`。

## 方法

| 方法          | 说明             |
| ------------- | ---------------- |
| validate      | 校验全部字段     |
| validateField | 校验指定字段     |
| resetFields   | 重置字段值和状态 |
| clearValidate | 清理校验状态     |
| scrollToField | 滚动到指定字段   |

## 事件

| 事件            | 说明                                              |
| --------------- | ------------------------------------------------- |
| submit          | 表单提交后触发                                    |
| validate        | 字段校验完成后触发                                |
| validate-failed | 表单校验失败后触发                                |
| values-change   | 字段触发原生 change 时携带 `{ name, value }` 抛出 |

## 已完成功能

- 表单数据、规则、初始值、校验消息模板和禁用态上下文。
- 字段注册/卸载、全量校验、字段校验、重置、清理校验和滚动到字段。
- submit 自动校验、校验成功/失败事件、字段级 validate 事件。
- `prop` 和 `name` 字段路径，支持字符串、数字、数组路径和 `a[0].b` 写法。
- required、type、email、url、enum、whitespace、min、max、len、pattern、自定义同步/异步 validator。
- blur/change/submit 触发器过滤。
- horizontal/vertical/inline 布局、label 宽度/位置、冒号、必填/可选标记。
- FormItem 的 help、extra、validateStatus、htmlFor、hidden、noStyle、dependencies。
- `Form.List` 动态字段增删/移动、稳定 key、initialValue、与父级 name path 自动拼接。
- `Form.Provider` 跨表单注册表与 `form-change` / `form-finish` 聚合。
- form-level 与 item-level 双层 `preserve` 控制字段卸载值。
- `warningOnly` 规则降级、`hasFeedback` 状态图标、`labelCol` / `wrapperCol` 24 栅格。
- 函数式 `rules: (model) => Rule | Rule[]`。
- 基础 ARIA 错误状态和错误消息 `role="alert"`。

## 缺失功能

- render props 级别的复杂条件渲染。
- `validateDebounce`、`normalize`、`getValueProps` 等少量高级字段配置。
- 完整无障碍实现和与所有录入组件的深度状态联动。
- 更完整的滚动容器定位、复杂错误聚合展示和国际化包级别默认文案。


---

# Grid 栅格

> 文档链接：https://vaebe.github.io/ccui/components/grid/index.html

24 等分的响应式栅格系统。`<c-row>` 是行容器，`<c-col>` 是列；列的 `span` 之和满 24 即填满一行。

## 何时使用

- 需要在多列之间对齐内容。
- 不同屏幕宽度下要切换列数。

## 基本使用

`gutter` 控制列与列的间距（px）。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :span="6"><div class="g-block">col-6</div></c-col>
    <c-col :span="6"><div class="g-block">col-6</div></c-col>
    <c-col :span="6"><div class="g-block">col-6</div></c-col>
    <c-col :span="6"><div class="g-block">col-6</div></c-col>
  </c-row>
</template>

<style>
.g-block {
  background: #1677ff;
  color: #fff;
  text-align: center;
  padding: 8px 0;
  border-radius: 4px;
  margin-bottom: 8px;
}
</style>
```

:::

## 不等分

不同 `span` 拼成一行，剩余的列若不足 24 不会拉伸。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :span="16"><div class="g-block">col-16</div></c-col>
    <c-col :span="8"><div class="g-block">col-8</div></c-col>
  </c-row>
</template>
```

:::

## 偏移与对齐

`offset` 让列前置留白；`justify` / `align` 控制行内对齐方式。

:::demo

```vue
<template>
  <c-row :gutter="16" justify="center" align="middle">
    <c-col :span="8"><div class="g-block" style="height: 60px; line-height: 60px">col-8</div></c-col>
    <c-col :span="8" :offset="4"><div class="g-block">col-8 offset-4</div></c-col>
  </c-row>
</template>
```

:::

## 响应式列数

`xs` / `sm` / `md` / `lg` / `xl` / `xxl` 按断点切换列数。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col v-for="i in 4" :key="i" :xs="24" :sm="12" :md="8" :lg="6">
      <div class="g-block">xs=24 sm=12 md=8 lg=6</div>
    </c-col>
  </c-row>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">缩窄浏览器观察列数变化</p>
</template>
```

:::

## 响应式间距

`gutter` 也支持 `[h, v]` 二元组或 `{ xs, sm, md, lg, xl }` 对象。

:::demo

```vue
<template>
  <c-row :gutter="[24, 12]">
    <c-col v-for="i in 6" :key="i" :span="8">
      <div class="g-block">col-8</div>
    </c-col>
  </c-row>
</template>
```

:::

## 列排序

`order` 改变列在视觉上的顺序，常用于响应式下"内容前置 / 侧栏后置"。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :span="6" :order="4"><div class="g-block">DOM-1 / order=4</div></c-col>
    <c-col :span="6" :order="3"><div class="g-block">DOM-2 / order=3</div></c-col>
    <c-col :span="6" :order="2"><div class="g-block">DOM-3 / order=2</div></c-col>
    <c-col :span="6" :order="1"><div class="g-block">DOM-4 / order=1</div></c-col>
  </c-row>
</template>
```

:::

## flex 简写

`flex="1"` / `flex="0 0 200px"` 让列脱离 24 栅格，按 flex 行为分配空间。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col flex="120px"><div class="g-block">120px</div></c-col>
    <c-col flex="auto"><div class="g-block">auto（撑满）</div></c-col>
    <c-col flex="80px"><div class="g-block">80px</div></c-col>
  </c-row>
</template>
```

:::

## push / pull 移位

`push` 把列向右推，`pull` 把列向左拉。常用「侧栏代码先写 / 视觉右置」之类的反转布局。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :span="6" :push="18"><div class="g-block">DOM-1（push 18，视觉在最右）</div></c-col>
    <c-col :span="18" :pull="6"><div class="g-block">DOM-2（pull 6，视觉在左）</div></c-col>
  </c-row>
</template>
```

:::

## 嵌套行

Row 可以嵌套：外层切大块，内层在大块里再分。注意嵌套时内 Row 通常也加 `gutter`，与外层独立。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :span="8"><div class="g-block">外层 col-8</div></c-col>
    <c-col :span="16">
      <c-row :gutter="8">
        <c-col :span="12"><div class="g-block" style="background: #52c41a">内层 col-12</div></c-col>
        <c-col :span="12"><div class="g-block" style="background: #52c41a">内层 col-12</div></c-col>
      </c-row>
      <c-row :gutter="8">
        <c-col :span="24"><div class="g-block" style="background: #fa8c16">内层 col-24</div></c-col>
      </c-row>
    </c-col>
  </c-row>
</template>
```

:::

## 业务双栏布局

「侧栏 6 / 主内容 18」是后台管理最常见的双栏比例；配合响应式断点，移动端自动堆叠。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :xs="24" :md="6">
      <div class="g-block" style="height: 160px">侧栏（xs=24 md=6）</div>
    </c-col>
    <c-col :xs="24" :md="18">
      <div class="g-block" style="height: 160px; background: #52c41a">主内容（xs=24 md=18）</div>
    </c-col>
  </c-row>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">缩窄到 md（&lt;768px）以下时，侧栏与主内容会堆叠为单列</p>
</template>
```

:::

## 关闭换行

`wrap="false"` 强制 Row 单行展示，超出宽度的列会按 flex 缩压；常用于横向滚动条 / 关键指标条。

:::demo

```vue
<template>
  <div style="overflow-x: auto; padding-bottom: 4px">
    <c-row :gutter="12" :wrap="false">
      <c-col v-for="i in 8" :key="i" :flex="'200px'">
        <div class="g-block">card-{{ i }}（固定 200px）</div>
      </c-col>
    </c-row>
  </div>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">8 张卡片强制一行，超出横向滚动</p>
</template>
```

:::

## 响应式对象配置

`xs / sm / md / lg / xl / xxl` 不仅可以传数字（span 简写），还可以传 `{ span, offset, order }` 完整对象，按断点分别配置。

:::demo

```vue
<template>
  <c-row :gutter="16">
    <c-col :xs="{ span: 24 }" :md="{ span: 8, offset: 0 }" :lg="{ span: 6, offset: 3, order: 2 }">
      <div class="g-block">A（lg 起 offset=3 order=2）</div>
    </c-col>
    <c-col :xs="{ span: 24 }" :md="{ span: 8 }" :lg="{ span: 6, order: 1 }">
      <div class="g-block" style="background: #52c41a">B（lg 起 order=1 视觉前置）</div>
    </c-col>
    <c-col :xs="{ span: 24 }" :md="{ span: 8 }" :lg="{ span: 6, order: 3 }">
      <div class="g-block" style="background: #fa8c16">C（lg 起 order=3 后置）</div>
    </c-col>
  </c-row>
</template>
```

:::

## 断点

| 断点 | 触发宽度（px） |
| ---- | -------------- |
| xs   | 0              |
| sm   | 576            |
| md   | 768            |
| lg   | 992            |
| xl   | 1200           |
| xxl  | 1600           |

## API

### Row Props

| 参数    | 类型                                                                                  | 默认值    | 说明     |
| ------- | ------------------------------------------------------------------------------------- | --------- | -------- |
| justify | `'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'` | `'start'` | 水平对齐 |
| align   | `'top' \| 'middle' \| 'bottom' \| 'stretch'`                                          | `'top'`   | 垂直对齐 |
| gutter  | `number \| [number, number] \| Record<Breakpoint, number>`                            | `0`       | 栅格间距 |
| wrap    | boolean                                                                               | `true`    | 自动换行 |

### Col Props

| 参数               | 类型                                            | 默认值 | 说明                              |
| ------------------ | ----------------------------------------------- | ------ | --------------------------------- |
| span               | number                                          | —      | 占据的栅格数 0–24                 |
| order              | number                                          | —      | 排序                              |
| offset             | number                                          | —      | 左偏移                            |
| push               | number                                          | —      | 向右推                            |
| pull               | number                                          | —      | 向左拉                            |
| flex               | `number \| string`                              | —      | flex 简写（脱离栅格按 flex 分配） |
| xs/sm/md/lg/xl/xxl | `number \| { span, offset, order, push, pull }` | —      | 响应式配置                        |


---

# Icon 图标

> 文档链接：https://vaebe.github.io/ccui/components/icon/index.html

统一图标尺寸、颜色、旋转和无障碍属性的基础包装器，内置 [Iconify](https://iconify.design/) 适配，可直接通过 `name="<prefix>:<icon>"` 渲染来自 200+ 图标集的任意图标。

## 基本使用

通过 Iconify 命名（带冒号）直接渲染图标，无需注册：

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="mdi:home" />
    <c-icon name="mdi:home" size="20" color="#1677ff" />
    <c-icon name="mdi:reload" spin />
    <c-icon name="mdi:star" rotate="45" />
  </div>
</template>
```

:::

## 尺寸预设

支持 `small / default / large` 三档预设，也可以传 `number`（按 px 解析）或任意 CSS 长度字符串（例如 `1.5em`）。`default` 不设内联字号，由父级 `font-size` 级联决定。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="mdi:heart" size="small" />
    <c-icon name="mdi:heart" size="default" />
    <c-icon name="mdi:heart" size="large" />
    <c-icon name="mdi:heart" :size="32" />
    <c-icon name="mdi:heart" size="2em" />
  </div>
</template>
```

:::

## 主题样式

通过 `theme` 属性挂上 `outlined / filled / two-tone` 类名，配合 Iconify 不同前缀或自定义 CSS 切换观感。`two-tone` 主题下 `twoToneColor` 控制次色（通过 `--ccui-icon-two-tone-color` 暴露）。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="mdi:star-outline" theme="outlined" :size="24" />
    <c-icon name="mdi:star" theme="filled" :size="24" color="#faad14" />
    <c-icon name="mdi:star" theme="two-tone" two-tone-color="#1677ff" :size="24" />
  </div>
</template>
```

:::

## 自带注册表（项目内复用）

不依赖 Iconify、希望强类型按名取本地组件时，使用 `registerIcon` 把任意 Vue 组件注册到全局图标表。`name` 不含冒号才会走注册表，否则进 Iconify 通道。

:::demo

```vue
<script setup lang="ts">
import { defineComponent, h } from 'vue'
import { registerIcon } from '@vaebe/ccui'

const Logo = defineComponent({
  name: 'Logo',
  setup() {
    return () =>
      h('svg', { viewBox: '0 0 24 24', fill: 'currentColor', 'aria-hidden': 'true' }, [
        h('path', { d: 'M12 2 2 22h20L12 2z' }),
      ])
  },
})

registerIcon('app-logo', Logo)
</script>

<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="app-logo" :size="32" color="#52c41a" />
    <c-icon name="app-logo" spin />
  </div>
</template>
```

:::

## 可点击图标（按钮语义）

`clickable` 让图标变成无障碍按钮：自动挂 `role="button"` + `tabindex="0"`，支持 Enter / Space 键盘激活，hover 状态下自动降透明度。

:::demo

```vue
<script setup lang="ts">
function handleClick() {
  alert('clicked')
}
</script>

<template>
  <c-icon name="mdi:bell" :size="24" clickable aria-label="通知" @click="handleClick" />
</template>
```

:::

## 加载状态

`loading` 启用后图标内容被 spinner 替换，自动开 spin 动画并挂 `aria-busy="true"`，常用于异步操作中按钮的图标占位。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="mdi:cloud-upload" loading :size="24" />
    <c-icon name="mdi:reload" loading :size="24" color="#1677ff" />
  </div>
</template>
```

:::

## 禁用状态

`disabled` 仅对 `clickable=true` 生效：自动阻止 click 和键盘激活，挂 `aria-disabled="true"` + `tabindex="-1"`，外观降透明 + `cursor: not-allowed`。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <c-icon name="mdi:bell" :size="24" clickable aria-label="通知" />
    <c-icon name="mdi:bell" :size="24" clickable disabled aria-label="通知（禁用）" />
  </div>
</template>
```

:::

## 旋转方向

`spinDirection` 控制 spin 动画方向：`cw`（默认顺时针）或 `ccw`（逆时针）。

:::demo

```vue
<template>
  <div style="display: flex; gap: 16px;">
    <c-icon name="mdi:loading" spin :size="24" />
    <c-icon name="mdi:loading" spin spin-direction="ccw" :size="24" />
  </div>
</template>
```

:::

## 全局默认（ConfigProvider）

外层套 `<c-config-provider :component-size="..." :icon-prefix-cls="...">` 时，Icon 自动读取：

- `componentSize`：`small`/`middle`/`large` 映射为 14px / 默认级联 / 20px。`size` prop 显式覆盖。
- `iconPrefixCls`：作为字体图标兜底类名前缀（默认 `ccui-icon`）。`prefixCls` prop 显式覆盖。

```vue
<c-config-provider component-size="small" icon-prefix-cls="my-iconfont">
  <c-icon name="edit" />  <!-- 渲染 <i class="my-iconfont my-iconfont-edit"/>，14px -->
</c-config-provider>
```

## 离线 / 自带图标包

**ccui 内部使用的 mdi 图标默认已离线**。`@vaebe/ccui-icons` 把项目源码运行时使用的 14 个 mdi 图标 SVG 数据 inline 进包（gzip ~1.8 KB），ccui 入口在加载时自动 `addCollection` 注册到 Iconify 本地数据源。内网 / 无网环境下，浮层、表单状态、Tree 展开、上传进度、回顶按钮等组件的内置图标无需任何配置即可渲染。

> 内置覆盖清单详见下方「项目内 mdi 图标一览」节。

**扩展非 ccui 内置的图标**（业务层引入新 mdi / 其他 Iconify 图标集）时，仍可通过透传出的 API 把图标数据预先注入：

```ts
import { addCollection, addIcon } from '@vaebe/ccui'
import mdiHome from '@iconify-icons/mdi/home'

// 单图标
addIcon('mdi:home', mdiHome)

// 整个图标集（@iconify-json/mdi）
import mdiSet from '@iconify-json/mdi/icons.json'
addCollection(mdiSet)
```

注入后即使无网络也能正常渲染对应 `<c-icon name="mdi:home" />`。

## 直接传入插槽 SVG

需要一次性渲染某个 SVG 时，直接放在默认插槽里——尺寸、颜色、旋转、spin 一样有效。

:::demo

```vue
<template>
  <c-icon :size="24" color="#722ed1">
    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
      <path d="M12 2 2 22h20L12 2z" />
    </svg>
  </c-icon>
</template>
```

:::

## 项目内 mdi 图标一览

ccui 全部组件、demo 与文档统一使用 Iconify 的 [`mdi`](https://icon-sets.iconify.design/mdi/) 图标集（Material Design Icons），下表覆盖项目目前使用的全部图标，**按所属组件分组**。点击卡片复制图标名。

<ClientOnly>
  <IconShowcase
    :groups="[
      {
        title: '反馈状态（Alert / Message / Notification / Modal.Confirm / Form / Steps / Upload / Result / Progress）',
        icons: [
          'mdi:check',
          'mdi:check-circle',
          'mdi:check-circle-outline',
          'mdi:close',
          'mdi:close-circle',
          'mdi:close-circle-outline',
          'mdi:alert',
          'mdi:alert-circle',
          'mdi:alert-circle-outline',
          'mdi:information',
          'mdi:information-outline',
          'mdi:help-circle',
          'mdi:help-circle-outline',
        ],
      },
      {
        title: '输入与选择（AutoComplete / Select / Cascader / Tree / TreeSelect / DatePicker / TimePicker / InputSearch）',
        icons: [
          'mdi:magnify',
          'mdi:close',
          'mdi:close-circle',
          'mdi:chevron-down',
          'mdi:chevron-up',
          'mdi:chevron-left',
          'mdi:chevron-right',
          'mdi:menu-right',
          'mdi:menu-down',
          'mdi:calendar-outline',
          'mdi:clock-outline',
        ],
      },
      {
        title: '导航 / 链接（BackTop / Carousel / Empty / Pagination / Anchor）',
        icons: [
          'mdi:arrow-up',
          'mdi:arrow-down',
          'mdi:arrow-left',
          'mdi:arrow-right',
          'mdi:open-in-new',
          'mdi:link-variant',
        ],
      },
      {
        title: '操作（Typography / Tabs / Drawer / Modal / Upload / FloatButton）',
        icons: [
          'mdi:content-copy',
          'mdi:pencil-outline',
          'mdi:delete-outline',
          'mdi:plus',
          'mdi:minus',
          'mdi:reload',
          'mdi:upload',
          'mdi:cloud-upload-outline',
          'mdi:download',
          'mdi:file-document-outline',
          'mdi:eye-outline',
          'mdi:eye-off-outline',
        ],
      },
      {
        title: '账号 / 通用（FloatButton demo / Layout / Menu）',
        icons: [
          'mdi:account-circle-outline',
          'mdi:bell-outline',
          'mdi:home-outline',
          'mdi:cog-outline',
          'mdi:menu',
          'mdi:email-outline',
          'mdi:message-text-outline',
          'mdi:star',
          'mdi:star-outline',
          'mdi:heart',
          'mdi:loading',
        ],
      },
    ]"
  />
</ClientOnly>

> 在 [icon-sets.iconify.design/mdi](https://icon-sets.iconify.design/mdi/) 可在线检索新图标，命名规则即 `mdi:<kebab-case-name>`。新增使用前先在此速览补登记。

## 内置图标包 `@vaebe/ccui-icons`

独立 workspace 包，两块职责：

- **mdi 离线 collection** — 详见 [离线 / 自带图标包](#离线-自带图标包) 节，ccui 入口已自动注入，**业务层无感**。需要在 ccui 之外的早期阶段强制注入时，可手动 `installCcuiMdiIcons()` 或副作用 `import '@vaebe/ccui-icons/install'`。
- **SVG 函数组件** — 少量需要静态打包、不走 Iconify 体系的图标以独立 ESM 命名导出，`sideEffects` 仅含 install 入口，未使用的导出全程 tree-shake。

| 导出                    | 说明                                                                 |
| ----------------------- | -------------------------------------------------------------------- |
| `installCcuiMdiIcons()` | 幂等注册 `ccuiMdiCollection` 到 Iconify，ccui 入口已自动调用         |
| `ccuiMdiCollection`     | 原始 `IconifyJSON` 数据对象，自定义 Iconify 集成时可复用             |
| `CaretRightOutlined`    | SVG 函数组件，可独立渲染，也可塞进 `<c-icon :component="..." />`     |
| `createIcon({ ... })`   | 自定义 SVG 函数组件构造器，与内置组件同 `size / color / rotate` 协议 |

:::demo

```vue
<script setup lang="ts">
import { CaretRightOutlined } from '@vaebe/ccui-icons'
</script>

<template>
  <div style="display: flex; gap: 16px; align-items: center;">
    <CaretRightOutlined :size="20" color="#1677ff" />
    <c-icon :component="CaretRightOutlined" :size="20" />
  </div>
</template>
```

:::

## Props

| 参数           | 类型                                                  | 默认值 | 说明                                                      |
| -------------- | ----------------------------------------------------- | ------ | --------------------------------------------------------- |
| name           | `string`                                              | --     | 图标名。含 `:` 时走 Iconify，否则查注册表，再退化到字体类 |
| component      | `Component`                                           | --     | 直接传图标组件，优先级最高                                |
| size           | `'small' \| 'default' \| 'large' \| number \| string` | --     | 尺寸，预设/数字 px/任意 CSS 长度                          |
| color          | `string`                                              | --     | 主色，作用于 `color` / `fill` / `stroke`                  |
| theme          | `'outlined' \| 'filled' \| 'two-tone'`                | --     | 主题类名挂载，便于样式钩子                                |
| twoToneColor   | `string`                                              | --     | 次色，配合 `theme="two-tone"`                             |
| rotate         | `number`                                              | 0      | 旋转角度（deg）                                           |
| spin           | `boolean`                                             | false  | 是否旋转动画                                              |
| spinDirection  | `'cw' \| 'ccw'`                                       | `'cw'` | 旋转方向，`ccw` 反向                                      |
| loading        | `boolean`                                             | false  | 加载态：替换为 spinner，自动 spin + `aria-busy`           |
| clickable      | `boolean`                                             | false  | 渲染为按钮：`role="button"` + `tabindex="0"` + 键盘激活   |
| disabled       | `boolean`                                             | false  | 仅对 `clickable` 有效：阻止 click/键盘 + `aria-disabled`  |
| themePrefixMap | `Partial<Record<IconTheme, string>>`                  | --     | 按 theme 自动映射 Iconify 前缀，比 `iconifyPrefix` 优先   |
| iconifyPrefix  | `string`                                              | --     | 当 `name` 不含 `:` 时自动拼成 `${prefix}:${name}`         |
| title          | `string`                                              | --     | 可访问标题（同时设置 `role="img"`）                       |
| ariaLabel      | `string`                                              | --     | 可访问标签                                                |
| prefixCls      | `string`                                              | --     | 字体类名前缀，默认读 ConfigProvider 的 `iconPrefixCls`    |

## 解析优先级

`component` > Iconify 命名（`name` 含 `:`） > 注册表命中 > 字体图标类名（`<i class="ccui-icon-{name}">`） > 默认插槽内容。

## Registry API

| 方法                            | 说明                                   |
| ------------------------------- | -------------------------------------- |
| `registerIcon(name, component)` | 注册一个命名图标，`name` 不要含 `:`    |
| `resolveIcon(name)`             | 读取已注册图标，未命中返回 `undefined` |
| `unregisterIcon(name)`          | 移除已注册图标                         |
| `clearIconRegistry()`           | 清空注册表，常用于测试 setup           |

## Iconify 透传 API

直接 `import` 自 `@vaebe/ccui`：

| 方法                             | 说明                                       |
| -------------------------------- | ------------------------------------------ |
| `addCollection(collection)`      | 注入整个图标集（如 `@iconify-json/mdi`）   |
| `addIcon(name, data)`            | 注入单个图标                               |
| `loadIcon(name)`                 | 显式预加载某个图标，返回 Promise           |
| `loadIcons(names)`               | 批量预加载                                 |
| `addAPIProvider(provider, host)` | 自定义 Iconify API 服务器（私有部署/镜像） |

## 事件

| 事件  | 回调签名              | 说明                                              |
| ----- | --------------------- | ------------------------------------------------- |
| click | `(event: MouseEvent)` | 点击事件，`clickable=true` 时也响应 Enter / Space |


---

# Image 图片

> 文档链接：https://vaebe.github.io/ccui/components/image/index.html

带占位、错误兜底、懒加载和大图预览的图片组件。

## 基本使用

最简形式只需要 `src`，可加 `width` / `height` / `alt`。

:::demo

```vue
<template>
  <c-image src="https://picsum.photos/seed/c-image/600/400" width="200" alt="示例图" />
</template>
```

:::

## 大图预览

设置 `preview` 后，点击图片会弹出全屏预览，支持缩放 / 重置 / 关闭。

:::demo

```vue
<template>
  <c-image src="https://picsum.photos/seed/c-image-preview/600/400" :width="200" :height="200" fit="cover" preview />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">点击图片打开预览</p>
</template>
```

:::

## 适应方式

`fit` 与 CSS `object-fit` 一致：`fill` / `contain` / `cover` / `none` / `scale-down`。

:::demo

```vue
<script setup>
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down']
const url = 'https://picsum.photos/seed/c-image-fit/600/400'
</script>

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap">
    <div v-for="f in fits" :key="f" style="text-align: center">
      <c-image :src="url" :fit="f" :width="120" :height="80" />
      <div style="margin-top: 4px; color: var(--ccui-color-text-secondary)">{{ f }}</div>
    </div>
  </div>
</template>
```

:::

## 加载失败兜底

加载失败时优先显示 `fallback` 图，否则展示"加载失败"文案；也可用 `#error` slot 完全自定义。

:::demo

```vue
<template>
  <c-image
    src="https://invalid.example.com/x.png"
    width="160"
    height="120"
    fallback="https://picsum.photos/seed/c-image-fallback/600/400"
  />
  &nbsp;
  <c-image src="https://invalid.example.com/y.png" :width="160" :height="120">
    <template #error>
      <div style="display: flex; align-items: center; justify-content: center; height: 100%; color: var(--ccui-color-error)">
        资源已下线 <c-icon name="mdi:close-circle" />
      </div>
    </template>
  </c-image>
</template>
```

:::

## 懒加载

`lazy` 配合 IntersectionObserver，元素进入视口才请求图片，可降低首屏成本。

:::demo

```vue
<template>
  <div style="height: 200px; overflow: auto; border: 1px dashed var(--ccui-color-border); padding: 8px">
    <p style="color: var(--ccui-color-text-secondary)">滚动下方查看懒加载图片：</p>
    <div style="height: 240px"></div>
    <c-image src="https://picsum.photos/seed/c-image-lazy/600/400" :width="200" lazy root-margin="50px" />
  </div>
</template>
```

:::

## 自定义占位

`#placeholder` slot 替换默认的"加载中"提示。

:::demo

```vue
<template>
  <c-image src="https://picsum.photos/seed/c-image-ph/600/400" :width="200" :height="120">
    <template #placeholder>
      <div
        style="
          display: flex;
          align-items: center;
          justify-content: center;
          width: 100%;
          height: 100%;
          background: linear-gradient(90deg, var(--ccui-area) 25%, var(--ccui-color-border-secondary) 50%, var(--ccui-area) 75%);
          background-size: 200% 100%;
          animation: shimmer 1.5s infinite;
          color: var(--ccui-color-text-tertiary);
        "
      >
        loading…
      </div>
    </template>
  </c-image>
</template>

<style>
@keyframes shimmer {
  0% {
    background-position: 200% 0;
  }
  100% {
    background-position: -200% 0;
  }
}
</style>
```

:::

## 事件追踪（load / error / click）

`load` / `error` / `click` 三个事件覆盖图片完整生命周期，可用于埋点、上报、统计。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const logs = ref([])
function trace(type, e) {
  logs.value.unshift(`[${new Date().toLocaleTimeString()}] ${type}`)
  if (logs.value.length > 5) logs.value.length = 5
}
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: flex-start">
    <c-image
      src="https://picsum.photos/seed/c-image-event/600/400"
      :width="160"
      :height="120"
      @load="trace('load')"
      @error="trace('error')"
      @click="trace('click')"
    />
    <ul style="margin: 0; padding-left: 18px; color: var(--ccui-color-text-secondary); font-size: 12px">
      <li v-if="!logs.length">尚无事件</li>
      <li v-for="(log, i) in logs" :key="i">{{ log }}</li>
    </ul>
  </div>
</template>
```

:::

## 多张图片相册（ImagePreview）

`<c-image-preview>` 把多张图聚成一组，点击任一张进入统一预览：左右切换 / 缩放 / 关闭。

:::demo

```vue
<script setup>
const photos = [
  'https://picsum.photos/seed/c-image-g1/600/400',
  'https://picsum.photos/seed/c-image-g2/600/400',
  'https://picsum.photos/seed/c-image-g3/600/400',
]
</script>

<template>
  <c-image-preview :items="photos">
    <div style="display: flex; gap: 12px">
      <c-image v-for="(url, i) in photos" :key="i" :src="url" :width="120" :height="80" fit="cover" />
    </div>
  </c-image-preview>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">点击任一张图片打开相册预览</p>
</template>
```

:::

## 受控预览（外部按钮唤起）

`preview` 传对象进入受控模式：父组件决定 `visible` / `current`，预览状态变化通过 `update:preview` 与 `change` 回写。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const photos = ['https://picsum.photos/seed/c-image-ctl1/600/400', 'https://picsum.photos/seed/c-image-ctl2/600/400']
const previewState = ref({ visible: false, current: 0 })

function openAt(idx) {
  previewState.value = { visible: true, current: idx }
}
</script>

<template>
  <div style="display: flex; gap: 8px; margin-bottom: 12px">
    <c-button @click="openAt(0)">从第 1 张开始</c-button>
    <c-button @click="openAt(1)">从第 2 张开始</c-button>
  </div>
  <c-image-preview v-model:preview="previewState" :items="photos" />
</template>
```

:::

## 失败兜底链

`fallback` 与 `#error` slot 可同时存在：fallback 是「先重试一次」，再失败才走 error slot。常用于 CDN 多重备份场景。

:::demo

```vue
<template>
  <c-image
    src="https://invalid.example.com/y.png"
    :width="200"
    :height="120"
    fallback="https://also-invalid.example.com/x.png"
  >
    <template #error>
      <div
        style="
          display: flex;
          flex-direction: column;
          align-items: center;
          justify-content: center;
          height: 100%;
          background: var(--ccui-area);
          color: #cf1322;
          font-size: 12px;
          gap: 4px;
        "
      >
        <c-icon name="mdi:alert" />
        <span>主图与备份图均失败</span>
      </div>
    </template>
  </c-image>
</template>
```

:::

## API

### Props

| 参数       | 类型               | 默认值   | 说明                           |
| ---------- | ------------------ | -------- | ------------------------------ |
| src        | string             | —        | 必填，图片地址                 |
| alt        | string             | `''`     | 替代文本                       |
| fit        | `ImageFit`         | `'fill'` | 与 CSS `object-fit` 同义       |
| width      | `number \| string` | `''`     | 宽度（数字按 px）              |
| height     | `number \| string` | `''`     | 高度                           |
| preview    | boolean            | `false`  | 启用大图预览，点击弹层         |
| fallback   | string             | `''`     | 加载失败时使用的兜底图片地址   |
| lazy       | boolean            | `false`  | 懒加载（IntersectionObserver） |
| rootMargin | string             | `'0px'`  | 配合 lazy 的预加载距离         |

### Events

| 事件名 | 回调签名          | 触发时机     |
| ------ | ----------------- | ------------ |
| load   | `(e: Event)`      | 图片加载完成 |
| error  | `(e: Event)`      | 加载失败     |
| click  | `(e: MouseEvent)` | 点击图片     |

### Slots

| 名称        | 说明               |
| ----------- | ------------------ |
| placeholder | 自定义加载中占位   |
| error       | 自定义加载失败展示 |


---

# ImagePreview 图片预览

> 文档链接：https://vaebe.github.io/ccui/components/image-preview/index.html

多图预览组件，作为独立顶层组件存在（不挂在 Image 命名空间下）。

## 何时使用

- 多张图片需要统一预览，支持上一张 / 下一张切换。
- 缩略图列表 + 大图预览的画廊场景。
- 需要受控预览状态（外部按钮触发打开第 N 张）。

## items 模式

最简用法：把图片数组传给 `items`，组件自动渲染缩略图列表，点击打开预览。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const items = [
      { src: 'https://picsum.photos/seed/a/600/400', alt: '风景 A' },
      { src: 'https://picsum.photos/seed/b/600/400', alt: '风景 B' },
      { src: 'https://picsum.photos/seed/c/600/400', alt: '风景 C' },
    ]
    return { items }
  },
})
</script>

<template>
  <c-image-preview :items="items" />
</template>
```

:::

`items` 也接 `string[]` 简写：

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      items: ['https://picsum.photos/seed/x/600/400', 'https://picsum.photos/seed/y/600/400'],
    }
  },
})
</script>

<template>
  <c-image-preview :items="items" />
</template>
```

:::

## 受控预览

传 `preview` 对象进入受控模式。外部按钮控制打开 / 关闭 / 当前下标。

:::demo

```vue
<script>
import { defineComponent, reactive } from 'vue'

export default defineComponent({
  setup() {
    const preview = reactive({ visible: false, current: 0 })
    const items = [
      { src: 'https://picsum.photos/seed/m/600/400', alt: 'M' },
      { src: 'https://picsum.photos/seed/n/600/400', alt: 'N' },
      { src: 'https://picsum.photos/seed/o/600/400', alt: 'O' },
    ]
    const onUpdate = (next) => {
      Object.assign(preview, next)
    }
    return {
      preview,
      items,
      onUpdate,
      open: (i) => {
        preview.current = i
        preview.visible = true
      },
    }
  },
})
</script>

<template>
  <c-button @click="open(0)">看第 1 张</c-button>
  <c-button @click="open(1)" style="margin-left: 8px">看第 2 张</c-button>
  <c-button @click="open(2)" style="margin-left: 8px">看第 3 张</c-button>
  <c-image-preview :items="items" :preview="preview" @update:preview="onUpdate" />
</template>
```

:::

## 缩放 + 键盘导航

打开预览后：

- `+` / `−` / `⟳` 按钮缩放（默认上限 6×，下限 0.25×）。
- `ArrowLeft` / `ArrowRight` 切换上 / 下一张（循环）。
- `Escape` 关闭预览。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      items: [
        'https://picsum.photos/seed/p/600/400',
        'https://picsum.photos/seed/q/600/400',
        'https://picsum.photos/seed/r/600/400',
      ],
    }
  },
})
</script>

<template>
  <c-image-preview :items="items" :max-zoom="8" :min-zoom="0.5" />
</template>
```

:::

## 默认 slot 模式

不传 `items` 时，缩略图完全由父组件渲染；预览状态走受控，由父组件决定当前显示哪张。

:::demo

```vue
<script>
import { defineComponent, reactive } from 'vue'

export default defineComponent({
  setup() {
    const preview = reactive({ visible: false, current: 0 })
    const items = [
      { src: 'https://picsum.photos/seed/u/600/400', alt: 'U' },
      { src: 'https://picsum.photos/seed/v/600/400', alt: 'V' },
    ]
    const onUpdate = (next) => Object.assign(preview, next)
    const open = (i) => {
      preview.current = i
      preview.visible = true
    }
    return { preview, items, onUpdate, open }
  },
})
</script>

<template>
  <c-image-preview :items="items" :preview="preview" @update:preview="onUpdate">
    <div style="display: flex; gap: 12px">
      <img
        v-for="(it, i) in items"
        :key="i"
        :src="it.src"
        style="width: 100px; height: 100px; object-fit: cover; cursor: zoom-in"
        @click="open(i)"
      />
    </div>
  </c-image-preview>
</template>
```

:::

## ImagePreview 参数

| 参数    | 类型                                        | 默认 | 说明                                               |
| ------- | ------------------------------------------- | ---- | -------------------------------------------------- |
| items   | string[] \| { src: string; alt?: string }[] | --   | 图片数组；传则自动渲染缩略图，不传走默认 slot 模式 |
| preview | { visible?: boolean; current?: number }     | --   | 受控预览状态；传则受控，未传则内部维护             |
| maxZoom | number                                      | 6    | 缩放上限                                           |
| minZoom | number                                      | 0.25 | 缩放下限                                           |

## ImagePreview 事件

| 事件名         | 参数                                  | 说明                 |
| -------------- | ------------------------------------- | -------------------- |
| update:preview | { visible: boolean; current: number } | 受控模式回写         |
| change         | current: number                       | 当前显示图片下标变化 |
| visible-change | visible: boolean                      | 打开 / 关闭预览      |

## ImagePreview 插槽

| 插槽名  | 说明                                                  |
| ------- | ----------------------------------------------------- |
| default | 仅未传 `items` 时生效；缩略图等内容由父组件自定义渲染 |

## 行为说明

- **循环切换**：`prev` 在首张回到末尾；`next` 在末尾回到首张。
- **键盘监听**：仅在 `visible=true` 时绑定 `window.keydown`，关闭后解绑；组件卸载强制解绑防泄漏。
- **缩放重置**：每次切换图片自动 `scale=1`。
- **z-index 1100**：高于 Modal / Drawer，避免被覆盖。


---

# Input 输入框

> 文档链接：https://vaebe.github.io/ccui/components/input/index.html

通过鼠标或键盘输入字符，可以设置输入框的类型、大小和状态。

## 何时使用

- 需要用户输入文本内容时。
- 需要收集用户的简短信息时。
- 需要搜索、过滤或表单输入时。

## 基本使用

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value" placeholder="请输入内容" />
  </div>
</template>

<style></style>
```

:::

## 不同尺寸

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value1 = ref('')
    const value2 = ref('')
    const value3 = ref('')
    return {
      value1,
      value2,
      value3,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value1" size="large" placeholder="大号输入框" class="mb-10" />
    <c-input v-model="value2" placeholder="默认输入框" class="mb-10" />
    <c-input v-model="value3" size="small" placeholder="小号输入框" />
  </div>
</template>

<style></style>
```

:::

## 禁用状态

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div>
    <c-input placeholder="禁用状态" disabled />
  </div>
</template>

<style></style>
```

:::

## 只读状态

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('只读内容')
    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value" readonly placeholder="只读状态" />
  </div>
</template>

<style></style>
```

:::

## 清空功能

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('可以清空的内容')
    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value" clearable placeholder="可清空的输入框" />
  </div>
</template>

<style></style>
```

:::

## 密码输入

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value" type="password" placeholder="密码输入框" class="mb-10" />
    <c-input v-model="value" type="password" show-password placeholder="可切换密码可见性" />
  </div>
</template>

<style></style>
```

:::

## 前置/后置内容

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-input v-model="value" prepend="http://" placeholder="请输入网址" class="mb-10" />
    <c-input v-model="value" append=".com" placeholder="请输入域名" class="mb-10" />
    <c-input v-model="value" prepend="https://" append=".org" placeholder="请输入网址" />
  </div>
</template>

<style></style>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled`（无边框 + 填充背景）/ `borderless`（无边框无背景）/ `underlined`（仅底部边框）。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-input v-model="value" :variant="variant" placeholder="切换 variant 观察样式" style="width: 260px" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
</script>
```

:::

## 校验状态 status

`status='error' | 'warning'` 控制边框 / focus 阴影色。**Form 联动会自动透传**：放进 `<c-form-item>` 里且校验失败时，Input 自动加 `--status-error` 类，无需手写。显式 `status` 优先于 Form 注入。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-input v-model="v1" status="error" placeholder="error" style="width: 220px" />
    <c-input v-model="v2" status="warning" placeholder="warning" style="width: 220px" />
    <c-input v-model="v3" placeholder="normal" style="width: 220px" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const v1 = ref('')
const v2 = ref('')
const v3 = ref('')
</script>
```

:::

## Input参数

| 参数          | 类型                                        | 默认    | 说明                                                                                        |
| ------------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| type          | [InputType](#inputtype)                     | text    | 输入框类型                                                                                  |
| size          | [InputSize](#inputsize)                     | default | 输入框尺寸                                                                                  |
| placeholder   | string                                      | --      | 占位符                                                                                      |
| disabled      | boolean                                     | false   | 是否为禁用状态                                                                              |
| readonly      | boolean                                     | false   | 是否为只读状态                                                                              |
| modelValue    | string                                      | --      | 绑定值（v-model）                                                                           |
| defaultValue  | string                                      | --      | 非受控初值，仅首次挂载使用                                                                  |
| clearable     | boolean                                     | false   | 是否显示清除按钮                                                                            |
| show-password | boolean                                     | false   | 密码输入时是否可切换可见性                                                                  |
| prepend       | string                                      | ''      | 前置 addon 文本（也可用同名 `prepend` slot）                                                |
| append        | string                                      | ''      | 后置 addon 文本（也可用同名 `append` slot）                                                 |
| maxLength     | number                                      | --      | 最大长度（透传原生 `maxlength`）                                                            |
| showCount     | boolean \| { formatter?: (info) => string } | false   | 显示字符计数，配合 `maxLength` 显示 `N / max`；formatter 接 `({ value, count, maxLength })` |
| status        | '' \| 'error' \| 'warning'                  | ''      | 校验状态，Form 联动会自动透传                                                               |

## Input类型定义

### InputType

```ts
export type InputType = 'text' | 'password'
```

### InputSize

```ts
export type InputSize = 'large' | 'default' | 'small'
```

## Input事件

| 事件名            | 参数          | 说明                             |
| ----------------- | ------------- | -------------------------------- |
| update:modelValue | value         | 绑定值改变时触发（v-model 事件） |
| input             | value         | 输入框值改变时触发               |
| change            | value         | 输入框值改变并失去焦点时触发     |
| focus             | event         | 输入框获得焦点时触发             |
| blur              | event         | 输入框失去焦点时触发             |
| clear             | --            | 点击清除图标时触发               |
| press-enter       | KeyboardEvent | Enter 键按下时触发               |

## Input插槽

| 插槽名  | 说明              |
| ------- | ----------------- |
| prepend | 前置 addon 内容   |
| append  | 后置 addon 内容   |
| prefix  | 输入框内左侧前缀  |
| suffix  | 输入框内右侧后缀  |


---

# InputNumber 数字输入框

> 文档链接：https://vaebe.github.io/ccui/components/input-number/index.html

数字输入框组件，用于输入数字类型的数据。

## 何时使用

当需要获取标准数值时。

## 基本使用

基础的数字输入框用法。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(0)
</script>

<template>
  <c-input-number v-model="value" placeholder="请输入数字" />
  <p>当前值：{{ value }}</p>
</template>
```

:::

## 禁用状态

通过 `disabled` 属性指定是否禁用 input 组件。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(10)
</script>

<template>
  <c-input-number v-model="value" disabled />
</template>
```

:::

## 只读状态

`readonly` 让数值不可编辑但仍可读出 / focus，常用于「计算结果展示但允许 copy」的场景。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(99.5)
</script>

<template>
  <c-input-number v-model="value" readonly />
  <p style="color: var(--ccui-color-text-secondary)">值由后端计算得出，仅供展示</p>
</template>
```

:::

## 数值范围

使用 `min` 和 `max` 属性限制数值范围。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(1)
</script>

<template>
  <c-input-number v-model="value" :min="1" :max="10" />
  <p>范围：1 - 10</p>
</template>
```

:::

## 步数

使用 `step` 属性设置步长。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(0)
</script>

<template>
  <c-input-number v-model="value" :step="2" />
  <p>步长：2</p>
</template>
```

:::

## 精度

使用 `precision` 属性设置数值精度。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(1.0)
</script>

<template>
  <c-input-number v-model="value" :precision="2" :step="0.1" />
  <p>精度：2 位小数</p>
</template>
```

:::

## 尺寸

支持 `large` / `default` / `small` 三档，与库内其他录入组件（Input / Select 等）统一。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(0)
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <c-input-number v-model="value" size="large" placeholder="large（大）" />
    <c-input-number v-model="value" placeholder="default（默认）" />
    <c-input-number v-model="value" size="small" placeholder="small（小）" />
  </div>
</template>
```

:::

## 控制按钮位置

使用 `controls-position` 属性设置控制按钮位置。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(0)
</script>

<template>
  <div>
    <p style="margin-top: 0">两侧控制</p>
    <c-input-number v-model="value" controls-position="both" placeholder="两侧控制" />

    <p>右侧控制</p>
    <div style="display: flex; gap: 12px">
      <c-input-number v-model="value" size="large" controls-position="right" placeholder="右侧控制" />
      <c-input-number v-model="value" controls-position="right" placeholder="右侧控制" />
      <c-input-number v-model="value" size="small" controls-position="right" placeholder="右侧控制" />
    </div>

    <p>无控制按钮</p>
    <c-input-number v-model="value" :controls="false" placeholder="无控制按钮" />
  </div>
</template>
```

:::

## 允许空值

使用 `allow-empty` 属性允许输入框为空。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(undefined)
</script>

<template>
  <c-input-number v-model="value" allow-empty placeholder="允许空值" />
  <p>当前值：{{ value === undefined ? '（空）' : value }}</p>
</template>
```

:::

## 监听 change 事件

`change` 返回当前值与变更前的旧值两个参数，方便埋点 / 撤销栈等场景。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(0)
const logs = ref([])

function onChange(curr, prev) {
  logs.value.unshift({ curr, prev, at: new Date().toLocaleTimeString() })
  if (logs.value.length > 5) logs.value.length = 5
}
</script>

<template>
  <c-input-number v-model="value" @change="onChange" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近 5 次变更：</p>
  <ul style="margin: 4px 0; padding-left: 20px; color: var(--ccui-color-text-secondary)">
    <li v-for="(log, i) in logs" :key="i">[{{ log.at }}] {{ log.prev }} → {{ log.curr }}</li>
  </ul>
</template>
```

:::

## 实例方法（ref）

通过 ref 拿到组件实例后可调用 `focus` / `blur` / `increase` / `decrease` / `getValue` / `setValue` 6 个方法，常用于配合外部按钮操控。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref(5)
const inputRef = ref(null)

function inc() {
  inputRef.value?.increase()
}
function dec() {
  inputRef.value?.decrease()
}
function focus() {
  inputRef.value?.focus()
}
function reset() {
  inputRef.value?.setValue(0)
}
</script>

<template>
  <c-input-number ref="inputRef" v-model="value" :step="1" :min="0" :max="10" />
  <div style="display: flex; gap: 8px; margin-top: 8px">
    <c-button @click="inc">+1</c-button>
    <c-button @click="dec">-1</c-button>
    <c-button @click="focus">聚焦</c-button>
    <c-button type="primary" @click="reset">重置</c-button>
  </div>
</template>
```

:::

## 货币输入场景

`precision=2` + `step=0.01` + `min=0` + `placeholder="¥ 0.00"` 是常见的金额输入组合。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const price = ref(0)
</script>

<template>
  <c-input-number v-model="price" :precision="2" :step="0.01" :min="0" placeholder="¥ 0.00" controls-position="right" />
  <p style="margin-top: 8px">应付金额：¥ {{ price.toFixed(2) }}</p>
</template>
```

:::

## 正则限制 reg

`reg` 接受 RegExp 或字符串，输入时不匹配的字符会被过滤；常用于「只允许正整数」「只允许非负数」之类的约束。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const intOnly = ref(0)
const positiveOnly = ref(0)
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 280px">
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">仅正整数（reg = /^\d+$/）</p>
      <c-input-number v-model="intOnly" :reg="/^\d+$/" :min="0" placeholder="只能输入整数" />
    </div>
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">非负小数（reg = /^\d+(\.\d{0,2})?$/）</p>
      <c-input-number v-model="positiveOnly" :reg="/^\d+(\.\d{0,2})?$/" :min="0" :precision="2" placeholder="0.00" />
    </div>
  </div>
</template>
```

:::

## 关闭悬浮发光

`show-glow-style="false"` 关闭 hover / focus 时的发光描边，融入更克制的视觉风格。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref(10)
const b = ref(10)
</script>

<template>
  <div style="display: flex; gap: 16px">
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">默认（发光）</p>
      <c-input-number v-model="a" />
    </div>
    <div>
      <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">关闭发光</p>
      <c-input-number v-model="b" :show-glow-style="false" />
    </div>
  </div>
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-input-number v-model="value" :variant="variant" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref(10)
</script>
```

:::

## 校验状态 status

`status='error' | 'warning'` 控制边框 / focus 阴影色。Form 联动会自动透传 —— 放进 `<c-form-item>` 内校验失败时自动加 `--status-error` 类。change / blur 都会触发 FormItem 校验。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-input-number v-model="v1" status="error" />
    <c-input-number v-model="v2" status="warning" />
    <c-input-number v-model="v3" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const v1 = ref(0)
const v2 = ref(0)
const v3 = ref(0)
</script>
```

:::

## InputNumber参数

| 参数              | 类型                                                             | 默认值       | 说明                                                                                         |
| ----------------- | ---------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| v-model           | `number \| undefined`                                            | `undefined`  | 绑定值                                                                                       |
| step              | `number`                                                         | `1`          | 计数器步长                                                                                   |
| placeholder       | `string`                                                         | `''`         | 输入框占位文本                                                                               |
| max               | `number`                                                         | `Infinity`   | 设置计数器允许的最大值                                                                       |
| min               | `number`                                                         | `-Infinity`  | 设置计数器允许的最小值                                                                       |
| disabled          | `boolean`                                                        | `false`      | 是否禁用计数器                                                                               |
| readonly          | `boolean`                                                        | `false`      | 是否只读                                                                                     |
| precision         | `number`                                                         | `undefined`  | 数值精度                                                                                     |
| size              | `'large' \| 'default' \| 'small'`                                | `'default'`  | 输入框尺寸                                                                                   |
| controls          | `boolean`                                                        | `true`       | 是否显示控制按钮                                                                             |
| controls-position | `'both' \| 'right'`                                              | `'both'`     | 控制按钮位置                                                                                 |
| allow-empty       | `boolean`                                                        | `false`      | 是否允许空值                                                                                 |
| show-glow-style   | `boolean`                                                        | `true`       | 是否显示悬浮发光效果                                                                         |
| reg               | `RegExp \| string`                                               | `undefined`  | 输入限制的正则表达式，不匹配的字符会被过滤                                                   |
| variant           | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'`         | `'outlined'` | 录入组件统一形态                                                                             |
| status            | `'' \| 'error' \| 'warning'`                                     | `''`         | 校验状态，Form 联动会自动透传                                                                |

## InputNumber事件

| 事件名 | 回调参数                                                         | 说明                    |
| ------ | ---------------------------------------------------------------- | ----------------------- |
| change | `(currentVal: number \| undefined, oldVal: number \| undefined)` | 绑定值被改变时触发      |
| blur   | `(event: FocusEvent)`                                            | 在 Input 失去焦点时触发 |
| focus  | `(event: FocusEvent)`                                            | 在 Input 获得焦点时触发 |
| input  | `(currentValue: number \| undefined)`                            | 在 Input 值改变时触发   |

## InputNumber方法

通过 ref 调用：

| 方法名   | 说明                          | 参数                  | 返回值                |
| -------- | ----------------------------- | --------------------- | --------------------- |
| focus    | 使 input 获取焦点             | —                     | `void`                |
| blur     | 使 input 失去焦点             | —                     | `void`                |
| increase | 按 `step` 增加一次            | —                     | `void`                |
| decrease | 按 `step` 减少一次            | —                     | `void`                |
| getValue | 获取当前值                    | —                     | `number \| undefined` |
| setValue | 设置值（受 min/max/精度约束） | `number \| undefined` | `void`                |


---

# InputOtp 一次性密码

> 文档链接：https://vaebe.github.io/ccui/components/input-otp/index.html

分格的一次性密码 / 验证码输入框，作为独立顶层组件存在（不挂在 Input 命名空间下）。

## 何时使用

- 短信验证码 / 邮箱验证码输入。
- 一次性 PIN 码 / 安全码输入。
- 需要自动焦点流转 + 粘贴填充体验。

## 基本使用

默认 6 个 cell，每个 cell 输入一个字符后焦点自动跳到下一格。Backspace 退格、ArrowLeft / ArrowRight 跨格、粘贴会逐格填入。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    const onChange = (val, info) => {
      console.log('change:', val, 'trigger index:', info.index)
    }
    return { value, onChange }
  },
})
</script>

<template>
  <c-input-otp v-model="value" @change="onChange" />
</template>
```

:::

## 自定义长度

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      v1: ref(''),
      v2: ref(''),
    }
  },
})
</script>

<template>
  <c-input-otp v-model="v1" :length="4" />
  <c-input-otp v-model="v2" :length="8" style="margin-top: 12px" />
</template>
```

:::

## 字符遮罩

`mask=true` 用 `•` 显示，`mask="#"` 用自定义字符。emit 的 modelValue 始终是真实字符。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('1234')
    return { value }
  },
})
</script>

<template>
  <c-input-otp v-model="value" :length="4" :mask="true" />
  <c-input-otp v-model="value" :length="4" mask="#" style="margin-top: 12px" />
</template>
```

:::

## 格式化输入

`formatter` 在每个字符写入前调用，常用于强制大写 / 限制只能数字。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const v1 = ref('')
    const v2 = ref('')
    const upper = (v) => v.toUpperCase()
    const digit = (v) => (/^[0-9]$/.test(v) ? v : '')
    return { v1, v2, upper, digit }
  },
})
</script>

<template>
  <c-input-otp v-model="v1" :length="6" :formatter="upper" />
  <c-input-otp v-model="v2" :length="6" :formatter="digit" style="margin-top: 12px" />
</template>
```

:::

## 校验状态

:::demo

```vue
<template>
  <c-input-otp status="error" :length="6" />
  <c-input-otp status="warning" :length="6" style="margin-top: 12px" />
</template>
```

:::

## 不同尺寸

:::demo

```vue
<template>
  <c-input-otp size="large" :length="4" />
  <c-input-otp :length="4" style="margin-top: 12px" />
  <c-input-otp size="small" :length="4" style="margin-top: 12px" />
</template>
```

:::

## InputOtp 参数

| 参数         | 类型                            | 默认    | 说明                                         |
| ------------ | ------------------------------- | ------- | -------------------------------------------- |
| modelValue   | string                          | ''      | 完整字符串（长度 ≤ length），v-model         |
| defaultValue | string                          | --      | 非受控初值                                   |
| length       | number                          | 6       | 单元格数量                                   |
| mask         | boolean \| string               | false   | true 用 `•`；string 用任意单字符；仅影响显示 |
| formatter    | (v: string) => string           | --      | 单字符变换器，写入 cell 前调用               |
| autoFocus    | boolean                         | false   | 挂载时聚焦首格                               |
| disabled     | boolean                         | false   | 整体禁用                                     |
| size         | 'large' \| 'default' \| 'small' | default | 尺寸                                         |
| status       | '' \| 'error' \| 'warning'      | ''      | 校验状态                                     |

## InputOtp 事件

| 事件名            | 参数               | 说明                                     |
| ----------------- | ------------------ | ---------------------------------------- |
| update:modelValue | value              | v-model                                  |
| change            | (value, { index }) | 任意格内容变化时触发，index 是触发格序号 |
| focus             | event              | 任一 cell 获得焦点                       |
| blur              | event              | 任一 cell 失去焦点                       |

## 行为说明

- **自动焦点流转**：在一格输入字符后焦点自动跳到下一格；一次输入多字符（IME / 安卓 / 粘贴）会逐格填入。
- **Backspace**：当前格有值 → 清掉；当前格为空且不在首格 → 回到上一格并清掉。
- **ArrowLeft / ArrowRight**：显式跨格焦点。
- **`autocomplete="one-time-code"`**：首格设置该属性，配合 iOS / Android 系统自动填充短信验证码。
- **`inputmode="numeric"`**：移动端默认弹出数字键盘。


---

# InputSearch 搜索框

> 文档链接：https://vaebe.github.io/ccui/components/input-search/index.html

带搜索按钮的输入框，作为独立顶层组件存在（不挂在 Input 命名空间下）。

## 何时使用

- 需要带搜索按钮的输入场景，配合 `@search` 事件触发查询。
- 需要在按钮内显示加载状态（`loading`）。
- 需要自定义按钮文字或完全自定义按钮内容（`enter-button` slot）。

## 基本使用

`enterButton=false`（默认）时右侧仅显示放大镜图标，点击放大镜或按 Enter 触发 `@search`。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    const onSearch = (val) => {
      console.log('search:', val)
    }
    return { value, onSearch }
  },
})
</script>

<template>
  <c-input-search v-model="value" placeholder="输入关键字后按 Enter" @search="onSearch" />
</template>
```

:::

## 带搜索按钮

`enterButton=true` 显示放大镜按钮；`enterButton="搜索"` 显示文字按钮。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      v1: ref(''),
      v2: ref(''),
    }
  },
})
</script>

<template>
  <c-input-search v-model="v1" :enter-button="true" placeholder="enterButton=true" />
  <c-input-search v-model="v2" enter-button="搜索" placeholder="enterButton='搜索'" style="margin-top: 12px" />
</template>
```

:::

## 加载状态

`loading=true` 时按钮内的放大镜替换为旋转 loading 图标，按钮 disabled 且不触发 `@search`。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      value: ref(''),
    }
  },
})
</script>

<template>
  <c-input-search :loading="true" :enter-button="true" placeholder="loading" />
  <c-input-search :loading="true" placeholder="loading 无按钮态" style="margin-top: 12px" />
</template>
```

:::

## 自定义按钮内容

`enter-button` slot 完全自定义按钮内容（优先级高于 prop）。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return { value: ref('') }
  },
})
</script>

<template>
  <c-input-search v-model="value" placeholder="自定义按钮内容">
    <template #enter-button>
      <span>🔍 立即搜</span>
    </template>
  </c-input-search>
</template>
```

:::

## 清除按钮 + 搜索

`clearable` 开启后，清除会同时 emit `@search('')`。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('内容')
    return { value }
  },
})
</script>

<template>
  <c-input-search v-model="value" clearable enter-button="搜索" />
</template>
```

:::

## InputSearch 参数

| 参数         | 类型                                       | 默认    | 说明                                                                               |
| ------------ | ------------------------------------------ | ------- | ---------------------------------------------------------------------------------- |
| modelValue   | string                                     | --      | 绑定值（v-model）                                                                  |
| defaultValue | string                                     | --      | 非受控初值                                                                         |
| placeholder  | string                                     | --      | 占位符                                                                             |
| enterButton  | boolean \| string \| VNode                 | false   | 搜索按钮：false 仅 suffix 放大镜；true 默认图标按钮；string 文字按钮；VNode 自定义 |
| loading      | boolean                                    | false   | 搜索中状态，按钮变 disabled                                                        |
| size         | 'large' \| 'default' \| 'small'            | default | 尺寸                                                                               |
| disabled     | boolean                                    | false   | 整体禁用                                                                           |
| readonly     | boolean                                    | false   | 只读                                                                               |
| clearable    | boolean                                    | false   | 清除按钮，清除时同步 emit @search('')                                              |
| maxLength    | number                                     | --      | 最大长度                                                                           |
| status       | '' \| 'error' \| 'warning'                 | ''      | 校验状态                                                                           |

## InputSearch 事件

| 事件名            | 参数            | 说明                                                                                    |
| ----------------- | --------------- | --------------------------------------------------------------------------------------- |
| search            | (value, event?) | 点击 enterButton / 点击 suffix 放大镜 / Enter / clear 都触发；disabled/loading 时不触发 |
| press-enter       | event           | Enter 时触发（与 search 共存）                                                          |
| update:modelValue | value           | v-model                                                                                 |
| input             | value           | 输入时触发                                                                              |
| change            | value           | 失焦时触发                                                                              |
| focus             | event           | 获得焦点                                                                                |
| blur              | event           | 失去焦点                                                                                |
| clear             | --              | 点击清除按钮                                                                            |

## InputSearch 插槽

| 插槽名       | 说明                                       |
| ------------ | ------------------------------------------ |
| enter-button | 完全自定义按钮内容，优先级高于 enterButton |
| prefix       | 输入框左侧前缀                             |
| suffix       | 输入框右侧后缀（与放大镜共存）             |


---

# Layout 布局

> 文档链接：https://vaebe.github.io/ccui/components/layout/index.html

帮助构建中后台页面的整体框架，提供 `<c-layout>`、`<c-layout-header>`、`<c-layout-sider>`、`<c-layout-content>`、`<c-layout-footer>` 五个组件。

## 何时使用

- 中后台典型布局：顶部导航 / 侧边导航 / 主体内容 / 底部信息。
- 在 `<c-layout>` 嵌套 `<c-layout>` 实现复杂分栏。

## 基本使用

最简的"上中下"结构。

:::demo

```vue
<template>
  <c-layout style="min-height: 240px">
    <c-layout-header style="background: var(--ccui-color-primary); color: var(--ccui-color-text-light-solid)">Header</c-layout-header>
    <c-layout-content style="padding: 24px; background: var(--ccui-area)">Content</c-layout-content>
    <c-layout-footer style="text-align: center">Footer</c-layout-footer>
  </c-layout>
</template>
```

:::

## 含侧边栏

`<c-layout-sider>` 直接放在 `<c-layout>` 第一位作为左栏。

:::demo

```vue
<template>
  <c-layout style="min-height: 240px">
    <c-layout-sider style="background: #001529; color: rgba(255, 255, 255, 0.65); padding: 12px">
      Sider
    </c-layout-sider>
    <c-layout>
      <c-layout-header style="background: var(--ccui-color-primary); color: var(--ccui-color-text-light-solid)">Header</c-layout-header>
      <c-layout-content style="padding: 24px">Main</c-layout-content>
      <c-layout-footer style="text-align: center">Footer</c-layout-footer>
    </c-layout>
  </c-layout>
</template>
```

:::

## 可折叠侧边栏

`collapsible` 在底部加上一个折叠按钮；用 `v-model:collapsed` 双向同步状态。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const collapsed = ref(false)
</script>

<template>
  <c-layout style="min-height: 280px">
    <c-layout-sider
      v-model:collapsed="collapsed"
      collapsible
      style="background: #001529; color: rgba(255, 255, 255, 0.65); padding: 12px"
    >
      Sider menu
    </c-layout-sider>
    <c-layout>
      <c-layout-header style="background: var(--ccui-color-primary)" />
      <c-layout-content style="padding: 24px"> 当前 collapsed = {{ collapsed }} </c-layout-content>
    </c-layout>
  </c-layout>
</template>
```

:::

## 自定义宽度

`width` 设置展开宽度，`collapsedWidth` 设置折叠后的宽度。

:::demo

```vue
<template>
  <c-layout style="min-height: 240px">
    <c-layout-sider
      :width="240"
      :collapsed-width="60"
      collapsible
      :default-collapsed="true"
      style="background: #001529; color: rgba(255, 255, 255, 0.65); padding: 12px"
    >
      <p>展开 240，折叠 60</p>
    </c-layout-sider>
    <c-layout-content style="padding: 24px">主体</c-layout-content>
  </c-layout>
</template>
```

:::

## 浅色侧边栏

`theme="light"` 用浅色背景的 sider，更适合品牌色顶栏 + 白色侧栏的搭配。

:::demo

```vue
<template>
  <c-layout style="min-height: 240px">
    <c-layout-sider theme="light" style="border-inline-end: 1px solid var(--ccui-color-border-secondary); padding: 12px">
      浅色 Sider
    </c-layout-sider>
    <c-layout>
      <c-layout-header style="background: var(--ccui-color-bg-container); border-bottom: 1px solid var(--ccui-color-border-secondary); color: var(--ccui-color-text)">
        Header
      </c-layout-header>
      <c-layout-content style="padding: 24px; background: var(--ccui-area)">主体</c-layout-content>
    </c-layout>
  </c-layout>
</template>
```

:::

## 监听折叠

`collapse` 事件回调 `(collapsed, type)`，`type` 标识触发来源（`'clickTrigger'`）。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const collapsed = ref(false)
const log = ref('（无）')

function onCollapse(val, type) {
  log.value = `collapsed=${val} type=${type}`
}
</script>

<template>
  <c-layout style="min-height: 240px">
    <c-layout-sider v-model:collapsed="collapsed" collapsible @collapse="onCollapse"> Sider </c-layout-sider>
    <c-layout-content style="padding: 24px">最近一次折叠：{{ log }}</c-layout-content>
  </c-layout>
</template>
```

:::

## API

### Layout / Header / Content / Footer

直接渲染对应语义化标签，无额外 props。`style` 可自由覆盖背景 / 内边距等。

### LayoutSider Props

| 参数                  | 类型                                            | 默认值   | 说明                                                                                                  |
| --------------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| width                 | `number \| string`                              | `200`    | 展开宽度                                                                                              |
| collapsedWidth        | `number \| string`                              | `80`     | 折叠后宽度。设为 `0` 时 Sider 完全消失，触发器由 `zeroWidthTriggerStyle` 定位为浮动按钮               |
| collapsed             | `boolean`                                       | —        | 当前折叠状态，支持 `v-model:collapsed`                                                                |
| defaultCollapsed      | `boolean`                                       | `false`  | 初始折叠状态                                                                                          |
| collapsible           | `boolean`                                       | `false`  | 显示底部折叠按钮                                                                                      |
| reverseArrow          | `boolean`                                       | `false`  | 折叠按钮的箭头反向                                                                                    |
| theme                 | `'light' \| 'dark'`                             | `'dark'` | 主题色                                                                                                |
| breakpoint            | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | —        | 响应式断点。视口宽度小于对应断点时自动折叠；解除时自动展开。受控 `collapsed` 时仅 emit 事件不覆盖父值 |
| zeroWidthTriggerStyle | `CSSProperties`                                 | —        | `collapsedWidth=0` 且当前折叠时，触发器的 inline style（用于做浮动定位）                              |

### LayoutSider Events

| 事件             | 回调签名                         | 说明                                                                         |
| ---------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| update:collapsed | `(value: boolean)`               | 折叠状态变化                                                                 |
| collapse         | `(value: boolean, type: string)` | 折叠被触发，`type` 为 `'clickTrigger'` / `'responsive'`                      |
| breakpoint       | `(broken: boolean)`              | 断点状态变化。`broken=true` 表示视口已小于断点（自动折叠），`false` 表示恢复 |


---

# Masonry 瀑布流

> 文档链接：https://vaebe.github.io/ccui/components/masonry/index.html

按列分布、高度自适应的多列布局。卡片墙、画廊、动态列表的常见排版方式。

## 基本使用

设置 `columns`（列数）和 `gutter`（间距），把任意子节点放进默认插槽。

:::demo

```vue
<script setup>
const heights = [80, 120, 60, 100, 140, 90, 70, 110, 130]
</script>

<template>
  <c-masonry :columns="3" :gutter="16">
    <div v-for="(h, i) in heights" :key="i" class="mas-item" :style="{ height: `${h}px` }">Item {{ i + 1 }}</div>
  </c-masonry>
</template>

<style>
.mas-item {
  background: var(--ccui-color-bg-container);
  border: 1px solid var(--ccui-color-border-secondary);
  color: var(--ccui-color-text);
  padding: 12px;
  border-radius: 4px;
}
</style>
```

:::

## 响应式列数

`columns` 也可以传断点对象，Masonry 会按当前视口宽度选择对应列数。

:::demo

```vue
<template>
  <c-masonry :columns="{ xs: 1, sm: 2, md: 3, lg: 4 }" :gutter="12">
    <div v-for="i in 8" :key="i" class="mas-item" :style="{ height: `${60 + i * 12}px` }">Item {{ i }}</div>
  </c-masonry>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">缩窄浏览器观察列数变化</p>
</template>

<style>
.mas-item {
  background: var(--ccui-color-bg-container);
  border: 1px solid var(--ccui-color-border-secondary);
  color: var(--ccui-color-text);
  padding: 12px;
  border-radius: 4px;
}
</style>
```

:::

## 控制水平 / 垂直间距

`gutter` 可传单值（同时控制 H/V）或 `[h, v]` 数组分别指定。

:::demo

```vue
<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 8px">水平 24, 垂直 8</p>
  <c-masonry :columns="3" :gutter="[24, 8]">
    <div v-for="i in 6" :key="i" class="mas-item" :style="{ height: `${60 + i * 8}px` }">Item {{ i }}</div>
  </c-masonry>
</template>

<style>
.mas-item {
  background: var(--ccui-color-bg-container);
  border: 1px solid var(--ccui-color-border-secondary);
  color: var(--ccui-color-text);
  padding: 12px;
  border-radius: 4px;
}
</style>
```

:::

## 卡片墙

把 `<c-card>` 放进 Masonry，立刻得到卡片瀑布流。

:::demo

```vue
<script setup>
const cards = [
  { title: '日报', body: '第 14 周 项目进展……' },
  { title: '需求池', body: '本周提交 12 项需求，已排期 5 项。' },
  { title: '待办', body: '今日 4 项必做：评审、上线、巡检、夜会。' },
  { title: '复盘', body: '上线问题 3 例，根因总结附后。' },
  { title: '人员', body: '在岗 12 人，请假 1 人。' },
  { title: '风险', body: '依赖外部 API，关注 9 月窗口期。' },
]
</script>

<template>
  <c-masonry :columns="{ xs: 1, sm: 2, md: 3 }" :gutter="16">
    <c-card v-for="(c, i) in cards" :key="i" :title="c.title">
      <p>{{ c.body }}</p>
    </c-card>
  </c-masonry>
</template>
```

:::

## 内容动态变化

Masonry 在子节点变化时会重新分列，方便做"加载更多"。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const list = ref(Array.from({ length: 6 }, (_, i) => i + 1))

function loadMore() {
  const start = list.value.length + 1
  list.value = [...list.value, ...Array.from({ length: 4 }, (_, i) => start + i)]
}
function reset() {
  list.value = Array.from({ length: 6 }, (_, i) => i + 1)
}
</script>

<template>
  <c-masonry :columns="3" :gutter="12">
    <div v-for="n in list" :key="n" class="mas-item" :style="{ height: `${60 + (n % 4) * 20}px` }">Item {{ n }}</div>
  </c-masonry>
  <div style="margin-top: 8px">
    <c-button type="primary" @click="loadMore">加载更多</c-button>
    <c-button style="margin-inline-start: 8px" @click="reset">重置</c-button>
  </div>
</template>

<style>
.mas-item {
  background: var(--ccui-color-bg-container);
  border: 1px solid var(--ccui-color-border-secondary);
  color: var(--ccui-color-text);
  padding: 12px;
  border-radius: 4px;
}
</style>
```

:::

## API

### Props

| 参数       | 类型                                                  | 默认值  | 说明                                       |
| ---------- | ----------------------------------------------------- | ------- | ------------------------------------------ |
| columns    | `number \| { xs?, sm?, md?, lg?, xl?, xxl?: number }` | `3`     | 列数；对象形式按断点响应                   |
| gutter     | `number \| [number, number]`                          | `16`    | 间距：单值 = H/V 同；数组 = `[水平, 垂直]` |
| sequential | boolean                                               | `false` | 顺序填充（保持原序，不做高度平衡）         |

### 断点对照（与 c-grid 一致）

| 断点 | 触发宽度（px） |
| ---- | -------------- |
| xs   | 0              |
| sm   | 576            |
| md   | 768            |
| lg   | 992            |
| xl   | 1200           |
| xxl  | 1600           |


---

# Mentions 提及

> 文档链接：https://vaebe.github.io/ccui/components/mentions/index.html

带「@提及」语法的多行输入框。在 textarea 中输入特定 prefix（默认 `@`）后弹出候选浮层，选中后插入 `@username ` 到光标位置。常见于评论、IM、协作工具的 @ 队友、`#` 话题、`/` 命令场景。

## 基本使用

`v-model` 绑定输入值，`options` 提供候选项。输入 `@` 后浮层打开。

:::demo

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

const value = ref('')
const users = ['anna', 'alice', 'bob', 'charlie', 'dora']
</script>

<template>
  <c-mentions v-model="value" :options="users" placeholder="输入 @ 提及别人" :rows="4" />
</template>
```

:::

## 自定义选项格式

提供 `{ value, label, disabled }` 形态可独立控制 value 与显示文本。`label` 用于浮层显示，`value` 是真正插入到 textarea 的字符串。

:::demo

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

const value = ref('')
const team = [
  { value: 'alice', label: 'Alice (PM)' },
  { value: 'bob', label: 'Bob (Frontend)' },
  { value: 'charlie', label: 'Charlie (Backend)' },
  { value: 'guest', label: 'Guest', disabled: true },
]
</script>

<template>
  <c-mentions v-model="value" :options="team" :rows="3" />
</template>
```

:::

## 多触发字符

`prefix` 传数组支持同时识别多个触发字符。

:::demo

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

const value = ref('')
const allOpts = ['anna', 'todo', 'bug', 'feature']
</script>

<template>
  <c-mentions v-model="value" :options="allOpts" :prefix="['@', '#']" placeholder="@ 提及人 / # 关联标签" :rows="3" />
</template>
```

:::

## 自定义分隔符

`split` 控制选中后追加的字符（默认空格）。

:::demo

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

const value = ref('')
</script>

<template>
  <c-mentions v-model="value" :options="['anna', 'bob']" split=", " :rows="2" />
</template>
```

:::

## 自定义过滤

`filter-option` 控制候选项过滤：`true`（默认 includes）/ `false`（不过滤）/ 函数 `(input, option) => boolean`。

:::demo

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

const value = ref('')
const opts = ['Apple', 'apple', 'banana']

function startsWith(input: string, opt: { value: string }) {
  return opt.value.startsWith(input)
}
</script>

<template>
  <c-mentions v-model="value" :options="opts" :filter-option="startsWith" :rows="2" />
</template>
```

:::

## 区分大小写

默认 `caseSensitive=false`（输入 `An` 也能匹配 `anna`）；开启后，必须严格匹配大小写。

:::demo

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

const v1 = ref('')
const v2 = ref('')
const opts = ['Anna', 'ALICE', 'bob']
</script>

<template>
  <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">caseSensitive=false（默认，An 也能匹配 Anna）</p>
  <c-mentions v-model="v1" :options="opts" :rows="2" />
  <p style="margin: 12px 0 4px; color: var(--ccui-color-text-secondary)">caseSensitive=true（必须严格大小写）</p>
  <c-mentions v-model="v2" :options="opts" case-sensitive :rows="2" />
</template>
```

:::

## 自适应高度 autoSize

`autoSize` 让 textarea 跟随内容自动伸缩。可以传 `true`（无限制）或 `{ minRows, maxRows }`（限制范围）。

:::demo

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

const v1 = ref('')
const v2 = ref('')
</script>

<template>
  <p style="margin: 0 0 4px; color: var(--ccui-color-text-secondary)">autoSize=true（无限制）</p>
  <c-mentions v-model="v1" :options="['anna', 'bob']" auto-size placeholder="多输几行回车试试" />
  <p style="margin: 12px 0 4px; color: var(--ccui-color-text-secondary)">autoSize=&#123; minRows: 2, maxRows: 6 &#125;</p>
  <c-mentions
    v-model="v2"
    :options="['anna', 'bob']"
    :auto-size="{ minRows: 2, maxRows: 6 }"
    placeholder="最少 2 行，最多 6 行"
  />
</template>
```

:::

## 浮层位置 placement

`placement="top"` 把候选浮层放到 textarea 上方，适合输入区位于页面底部（如评论框）。

:::demo

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

const value = ref('')
</script>

<template>
  <div style="height: 80px"></div>
  <c-mentions
    v-model="value"
    :options="['anna', 'bob', 'charlie']"
    placement="top"
    :rows="3"
    placeholder="评论框：浮层向上弹出"
  />
</template>
```

:::

## 空数据占位 notFoundContent

候选过滤后无匹配项时显示 `notFoundContent`；不传则取 ConfigProvider locale（默认中文「暂无数据」）。

:::demo

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

const value = ref('')
</script>

<template>
  <c-mentions
    v-model="value"
    :options="['anna', 'bob']"
    not-found-content="🙈 找不到相关成员，去通讯录搜搜？"
    :rows="2"
    placeholder="输入 @ 后乱打几个字符触发空态"
  />
</template>
```

:::

## 自定义选项渲染（option slot）

`#option` slot 接收 `{ option, index }` scope，常用于做「头像 + 姓名 + 角色」的双行选项。

:::demo

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

const value = ref('')
const team = [
  { value: 'alice', label: 'Alice', role: 'PM', color: '#1677ff' },
  { value: 'bob', label: 'Bob', role: 'Frontend', color: '#52c41a' },
  { value: 'charlie', label: 'Charlie', role: 'Backend', color: '#fa8c16' },
  { value: 'dora', label: 'Dora', role: 'Design', color: '#eb2f96' },
]
</script>

<template>
  <c-mentions v-model="value" :options="team" :rows="3" placeholder="输入 @ 看自定义选项">
    <template #option="{ option }">
      <div style="display: flex; align-items: center; gap: 8px; padding: 2px 0">
        <span
          :style="{
            width: '24px',
            height: '24px',
            borderRadius: '50%',
            background: option.color,
            color: 'var(--ccui-color-text-light-solid)',
            fontSize: '12px',
            display: 'inline-flex',
            alignItems: 'center',
            justifyContent: 'center',
          }"
        >
          {{ option.label.charAt(0) }}
        </span>
        <span>
          <strong>{{ option.label }}</strong>
          <span style="margin-left: 6px; color: var(--ccui-color-text-tertiary); font-size: 12px">{{ option.role }}</span>
        </span>
      </div>
    </template>
  </c-mentions>
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-mentions v-model="value" :variant="variant" :options="opts" placeholder="@ 触发提示" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
const opts = ['alice', 'bob', 'charlie']
</script>
```

:::

## 校验状态 status

`status='error' | 'warning'` 控制边框 / focus 阴影色（视觉边框层在 `__textarea`，与 variant 一致）。Form 联动会自动透传 —— 放进 `<c-form-item>` 内校验失败时自动加 `--status-error` 类。

:::demo

```vue
<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <c-mentions v-model="v1" status="error" :options="opts" placeholder="error" />
    <c-mentions v-model="v2" status="warning" :options="opts" placeholder="warning" />
    <c-mentions v-model="v3" :options="opts" placeholder="normal" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const v1 = ref('')
const v2 = ref('')
const v3 = ref('')
const opts = ['alice', 'bob', 'charlie']
</script>
```

:::

## API

### Props

| 参数            | 类型                                                     | 默认值       | 说明                                              |
| --------------- | -------------------------------------------------------- | ------------ | ------------------------------------------------- |
| modelValue      | string \| null                                           | --           | 当前输入值，支持 `v-model`                        |
| defaultValue    | string                                                   | `''`         | 非受控初始值                                      |
| options         | `(string \| { value, label?, disabled? })[]`             | `[]`         | 候选项                                            |
| prefix          | `string \| string[]`                                     | `'@'`        | 触发字符；数组形态可同时识别多个                  |
| split           | string                                                   | `' '`        | 选中后追加的分隔符                                |
| placeholder     | string                                                   | --           | 占位文案                                          |
| disabled        | boolean                                                  | `false`      | 是否禁用                                          |
| rows            | number                                                   | `3`          | textarea 行数                                     |
| filterOption    | `boolean \| (input, option) => boolean`                  | `true`       | 过滤逻辑                                          |
| caseSensitive   | boolean                                                  | `false`      | 默认过滤是否区分大小写                            |
| notFoundContent | string                                                   | `暂无数据`   | 空数据占位                                        |
| placement       | `'top' \| 'bottom'`                                      | `'bottom'`   | 浮层方位（基于 textarea）                         |
| popupMaxHeight  | number                                                   | `256`        | 浮层最大高度（px）                                |
| autoSize        | `boolean \| { minRows?: number, maxRows?: number }`      | `false`      | 自适应 textarea 高度；`true` 无限制，对象指定范围 |
| searchDebounce  | number                                                   | `0`          | 搜索防抖延迟（毫秒），`0` 不防抖                  |
| variant         | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'` | 录入组件统一形态                                  |
| status          | `'' \| 'error' \| 'warning'`                             | `''`         | 校验状态，Form 联动会自动透传                     |

### Events

| 事件名            | 回调签名                                  | 触发时机                |
| ----------------- | ----------------------------------------- | ----------------------- |
| update:modelValue | `(value: string)`                         | 输入或选中时            |
| change            | `(value: string)`                         | 同 update:modelValue    |
| select            | `(option: MentionOption, prefix: string)` | 选中候选项时            |
| search            | `(text: string, prefix: string)`          | 浮层打开 / 搜索词变化时 |
| focus             | `(e: FocusEvent)`                         | textarea 聚焦           |
| blur              | `(e: FocusEvent)`                         | textarea 失焦           |

### Slots

| 名称   | 参数                                       | 说明           |
| ------ | ------------------------------------------ | -------------- |
| option | `{ option: MentionOption, index: number }` | 自定义单项渲染 |

## 已知限制（未交付）

- **光标精确定位**：浮层固定在 textarea 下方左侧，不会跟随光标位置精确浮动（需要 mirror div 测量字符宽度，工程量较大）。
- **彩色 token 渲染**：textarea 不支持富文本，`@user` 在编辑态保持纯文本。要彩色高亮需要切到 contenteditable，留到独立体验型组件 RichMentions。
- **trigger slot**：textarea 不支持替换为 input 或自定义触发器。


---

# Menu 导航菜单

> 文档链接：https://vaebe.github.io/ccui/components/menu/index.html

为页面、侧边栏和应用顶部提供导航，使用 Vue 组件的声明式 props、`v-model` 和事件风格。

## 配置式 API

::: tip 为什么不暴露子组件命名空间
ccui 的 `<c-menu>` 走**配置式 API**：所有菜单项、子菜单、分组、分割线都通过 `items: MenuItem[]` prop 用 `type` 字段表达，**不暴露 `Menu.SubMenu` / `Menu.ItemGroup` / `Menu.Divider` 子组件命名空间**（与 ccui「平铺独立顶层组件，不挂静态属性」原则一致）。

Menu 数据结构高度规整（树形 + 类型枚举），配置式 API 在动态菜单（如基于后端权限）场景比模板式更简洁；模板式如 `<c-sub-menu>` 等子组件如有强需求，留作后续演进项。
:::

各菜单项类型通过 `items.type` 区分：

| `type`      | 形状                                                                 | 说明                     |
| ----------- | -------------------------------------------------------------------- | ------------------------ |
| `'item'`    | `{ key, label, icon? }`                                              | 普通菜单项（默认）       |
| `'submenu'` | `{ key, label, type: 'submenu' \| undefined, children: MenuItem[] }` | 含 `children` 即为子菜单 |
| `'group'`   | `{ key, label, type: 'group', children: MenuItem[] }`                | 分组容器（不可点）       |
| `'divider'` | `{ key, type: 'divider' }`                                           | 分割线                   |

`type` 字段缺省时自动推断：有 `children` 视为 `'submenu'`，无 `children` 视为 `'item'`。

## 基本使用

:::demo

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

const selectedKeys = ref(['mail'])

const items = [
  { key: 'mail', label: '邮件', icon: 'i-mail' },
  { key: 'app', label: '应用', icon: 'i-appstore' },
  { key: 'disabled', label: '禁用项', disabled: true },
]
</script>

<template>
  <c-menu v-model:selected-keys="selectedKeys" mode="horizontal" :items="items" />
</template>
```

:::

## 内联子菜单

:::demo

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

const selectedKeys = ref(['1'])
const openKeys = ref(['sub1'])

const items = [
  {
    key: 'sub1',
    label: '导航一',
    type: 'submenu',
    children: [
      { key: '1', label: '选项一' },
      { key: '2', label: '选项二' },
    ],
  },
  {
    key: 'sub2',
    label: '导航二',
    type: 'submenu',
    children: [
      { key: '3', label: '选项三' },
      { key: '4', label: '危险操作', danger: true },
    ],
  },
]
</script>

<template>
  <c-menu
    v-model:selected-keys="selectedKeys"
    v-model:open-keys="openKeys"
    mode="inline"
    style="width: 256px"
    :items="items"
  />
</template>
```

:::

## 默认展开与默认选中

适合只需要初始化状态的场景，后续由组件内部状态维护。需要由业务状态接管时，使用 `v-model:selected-keys` 和 `v-model:open-keys`。

:::demo

```vue
<template>
  <c-menu
    mode="inline"
    style="width: 256px"
    :default-selected-keys="['dashboard']"
    :default-open-keys="['workbench']"
    :items="[
      {
        key: 'workbench',
        label: '工作台',
        children: [
          { key: 'dashboard', label: '仪表盘' },
          { key: 'analysis', label: '分析页' },
        ],
      },
    ]"
  />
</template>
```

:::

## 多选菜单

:::demo

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

const selectedKeys = ref(['read'])

const items = [
  { key: 'read', label: '只读权限' },
  { key: 'write', label: '写入权限' },
  { key: 'admin', label: '管理员权限', danger: true },
]
</script>

<template>
  <c-menu v-model:selected-keys="selectedKeys" multiple :items="items" />
</template>
```

:::

## 分组、分割线和额外内容

:::demo

```vue
<template>
  <c-menu
    style="width: 256px"
    :items="[
      {
        key: 'group-basic',
        type: 'group',
        label: '常用',
        children: [
          { key: 'profile', label: '个人资料', extra: 'Ctrl+P' },
          { key: 'settings', label: '设置' },
        ],
      },
      { key: 'divider-1', type: 'divider' },
      { key: 'logout', label: '退出登录', danger: true },
    ]"
  />
</template>
```

:::

## 暗色主题和收起

:::demo

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

const collapsed = ref(false)

const items = [
  { key: 'home', label: '首页', icon: 'i-home' },
  {
    key: 'system',
    label: '系统',
    icon: 'i-setting',
    children: [
      { key: 'users', label: '用户' },
      { key: 'roles', label: '角色' },
    ],
  },
]
</script>

<template>
  <button type="button" @click="collapsed = !collapsed">切换</button>
  <c-menu theme="dark" mode="inline" :inline-collapsed="collapsed" :default-open-keys="['system']" :items="items" />
</template>
```

:::

## Menu Props

| 参数                 | 类型                                 | 默认值      | 说明                                           |
| -------------------- | ------------------------------------ | ----------- | ---------------------------------------------- |
| mode                 | `vertical` / `horizontal` / `inline` | `vertical`  | 菜单类型                                       |
| theme                | `light` / `dark`                     | `light`     | 主题                                           |
| items                | `MenuItem[]`                         | `[]`        | 菜单数据                                       |
| selectedKeys         | `(string \| number)[]`               | `[]`        | 当前选中的菜单项，支持 `v-model:selected-keys` |
| defaultSelectedKeys  | `(string \| number)[]`               | `[]`        | 默认选中的菜单项                               |
| openKeys             | `(string \| number)[]`               | `[]`        | 当前展开的子菜单，支持 `v-model:open-keys`     |
| defaultOpenKeys      | `(string \| number)[]`               | `[]`        | 默认展开的子菜单                               |
| inlineIndent         | `number`                             | `24`        | inline 模式下每级缩进                          |
| collapsed            | `boolean`                            | `false`     | 收起菜单，保留兼容属性                         |
| inlineCollapsed      | `boolean`                            | `undefined` | inline 模式收起状态，优先级高于 `collapsed`    |
| multiple             | `boolean`                            | `false`     | 是否允许多选                                   |
| selectable           | `boolean`                            | `true`      | 是否允许选中菜单项                             |
| disabled             | `boolean`                            | `false`     | 是否禁用整个菜单                               |
| accordion            | `boolean`                            | `false`     | 是否只展开一个顶层子菜单                       |
| forceSubMenuRender   | `boolean`                            | `false`     | 是否强制渲染未展开的子菜单 DOM                 |
| triggerSubMenuAction | `click` / `hover`                    | `click`     | 子菜单展开触发方式                             |

## MenuItem

```ts
interface MenuItem {
  key: string | number
  label?: VNodeChild
  title?: string
  icon?: string
  disabled?: boolean
  danger?: boolean
  extra?: VNodeChild
  type?: 'item' | 'submenu' | 'group' | 'divider'
  children?: MenuItem[]
}
```

## Events

| 事件                | 说明                                                  |
| ------------------- | ----------------------------------------------------- |
| update:selectedKeys | 选中项变化，用于 `v-model:selected-keys`              |
| update:openKeys     | 展开项变化，用于 `v-model:open-keys`                  |
| click               | 点击菜单项，参数为 `MenuInfo`                         |
| select              | 选中菜单项，参数为 `MenuInfo`                         |
| deselect            | 多选模式下取消选中，参数为 `MenuInfo`                 |
| open-change         | 子菜单展开状态变化，参数为 `(openKeys, MenuOpenInfo)` |
| openChange          | `open-change` 的 camelCase 事件别名                   |

## 键盘交互

- `ArrowUp` / `ArrowDown`：在可见菜单项中移动焦点。
- `ArrowLeft` / `ArrowRight`：在水平菜单中移动焦点，在子菜单上收起或展开。
- `Enter` / `Space`：选中当前菜单项或切换当前子菜单。


---

# Message 全局提示

> 文档链接：https://vaebe.github.io/ccui/components/message/index.html

轻量的全局反馈提示，从顶部弹入，几秒后自动消失。适合用于操作成功 / 失败的简短确认，不打断用户操作。

## 基本使用

调用 `message.info` / `success` / `warning` / `error` / `loading` 即可弹出对应类型的提示。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function showInfo() {
  message.info('这是一条信息')
}
function showSuccess() {
  message.success('操作成功')
}
function showWarning() {
  message.warning('注意：磁盘空间不足')
}
function showError() {
  message.error('保存失败，请稍后重试')
}
</script>

<template>
  <c-button @click="showInfo">Info</c-button>
  <c-button type="primary" @click="showSuccess">Success</c-button>
  <c-button @click="showWarning">Warning</c-button>
  <c-button type="danger" @click="showError">Error</c-button>
</template>
```

:::

## 加载中

`message.loading` 用于异步操作前的占位提示，自动播放旋转图标。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function showLoading() {
  message.loading('加载中…')
}
</script>

<template>
  <c-button @click="showLoading">Loading</c-button>
</template>
```

:::

## 自定义停留时长

第二个参数推荐传**秒**；传 `0` 时不会自动关闭，需要手动调用返回的 `close()`。

::: tip 单位规则

- `duration ≤ 100` 视为「秒」（如 `3` → 3 秒、`1.5` → 1.5 秒）
- `duration > 100` 视为「毫秒」（如 `3000`、`8000`）
- `duration === 0` 永远表示不自动关闭

:::

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function shortToast() {
  message.success('1 秒后消失', 1) // 秒
}
function longToast() {
  message.info('停留 8 秒', 8)
}
function msUnit() {
  message.info('毫秒写法', 5000) // > 100 按 ms 处理
}
</script>

<template>
  <c-button @click="shortToast">短 (1s)</c-button>
  <c-button @click="longToast">长 (8s)</c-button>
  <c-button @click="msUnit">毫秒 (5000)</c-button>
</template>
```

:::

## 多 placement

支持 6 个位置：`top` / `topLeft` / `topRight` / `bottom` / `bottomLeft` / `bottomRight`。默认 `top`。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'
function pop(p) {
  message.open({ content: `placement: ${p}`, placement: p, duration: 2 })
}
</script>

<template>
  <c-button @click="pop('top')">top</c-button>
  <c-button @click="pop('topLeft')">topLeft</c-button>
  <c-button @click="pop('topRight')">topRight</c-button>
  <c-button @click="pop('bottom')">bottom</c-button>
  <c-button @click="pop('bottomLeft')">bottomLeft</c-button>
  <c-button @click="pop('bottomRight')">bottomRight</c-button>
</template>
```

:::

## 全局配置 message.config

`message.config(...)` 可一次性设定 `maxCount` / `stack` / `pauseOnHover` / `role` / `duration` / `top` / `bottom` / `getContainer` 等全局默认值。再次调用以覆盖前一次配置。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function setupStack() {
  message.config({ maxCount: 3, stack: true })
  for (let i = 1; i <= 5; i += 1) message.info(`第 ${i} 条`, 0)
}

function setupOffset() {
  message.config({ top: 100 }) // 顶部偏移 100px
  message.success('从顶 100px 处弹出', 2)
}

function reset() {
  message.destroy()
  message.config({ maxCount: Infinity, stack: false, top: undefined })
}
</script>

<template>
  <c-button @click="setupStack">maxCount=3 + stack</c-button>
  <c-button @click="setupOffset">top=100px</c-button>
  <c-button @click="reset">还原</c-button>
</template>
```

:::

## 主动关闭

当 `duration` 设为 `0`，或希望提前关闭时，使用调用返回的 `MessageHandle`。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'
import { ref } from 'vue'

const handle = ref(null)

function openSticky() {
  handle.value = message.open({
    content: '这条不会自动消失',
    type: 'warning',
    duration: 0,
  })
}

function closeSticky() {
  handle.value?.close()
  handle.value = null
}
</script>

<template>
  <c-button @click="openSticky">弹出常驻提示</c-button>
  <c-button @click="closeSticky" :disabled="!handle">手动关闭</c-button>
</template>
```

:::

## 显示关闭按钮 + 回调

`showClose` 显示关闭图标；`onClose` 在关闭（自动 / 主动）时触发，用于清理或埋点。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'
import { ref } from 'vue'

const closedCount = ref(0)

function withClose() {
  message.open({
    content: '5 秒后自动关，可点 × 提前关闭',
    type: 'info',
    duration: 5000,
    showClose: true,
    onClose() {
      closedCount.value += 1
    },
  })
}
</script>

<template>
  <c-button @click="withClose">弹出可关闭提示</c-button>
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">已关闭：{{ closedCount }} 次</span>
</template>
```

:::

## 全局清空

`message.destroy()` 关闭所有当前显示的提示并卸载容器；下次再调用 `message.*` 会重新挂载。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function spawnFive() {
  for (let i = 1; i <= 5; i += 1) {
    message.info(`第 ${i} 条`)
  }
}
function destroyAll() {
  message.destroy()
}
</script>

<template>
  <c-button @click="spawnFive">连发 5 条</c-button>
  <c-button type="danger" @click="destroyAll">全部清空</c-button>
</template>
```

:::

## useMessage composable

`useMessage()` 返回 `{ message, holder }` **对象**（**不是** React 的 `[modal, contextHolder]` 元组）。容器渲染在当前 Vue 子树里，自动继承父组件 provide 的 ConfigProvider / 主题等上下文——**与模块级 `message` 的最大差异**。

::: tip 何时用模块级 vs Hook 版？

- **模块级 `import { message } from '@vaebe/ccui'`**：脚手架 / utils / 命令式弹一条，简单直接，但容器走独立 `createApp`，**拿不到调用方 app 的 inject**（如自定义 ConfigProvider、主题、locale）。
- **Hook `useMessage()`**：当弹层需要继承组件树上下文（深色主题、自定义 locale、自定义 ConfigProvider）时用。**必须**在模板中挂 `<component :is="holder" />`。

:::

:::demo

```vue
<script setup>
import { useMessage } from '@vaebe/ccui'

const { message, holder } = useMessage()

function show() {
  message.success('我能拿到 ConfigProvider 的 locale', 2)
}
</script>

<template>
  <component :is="holder" />
  <c-button type="primary" @click="show">弹出（继承上下文）</c-button>
</template>
```

:::

### UseMessageReturn

| 字段    | 类型         | 说明                                                                              |
| ------- | ------------ | --------------------------------------------------------------------------------- |
| message | `MessageApi` | 与全局 `message` 同 API：`info/success/warning/error/loading/open/config/destroy` |
| holder  | `Component`  | 必须挂到模板：`<component :is="holder" />`                                        |

## API

### message 命名空间

| 方法                                  | 说明                                                    |
| ------------------------------------- | ------------------------------------------------------- |
| `message.open(options)`               | 通用入口，传完整 `MessageOptions`，返回 `MessageHandle` |
| `message.info(content, duration?)`    | 信息（默认 3 秒），返回 `MessageHandle`                 |
| `message.success(content, duration?)` | 成功                                                    |
| `message.warning(content, duration?)` | 警告                                                    |
| `message.error(content, duration?)`   | 错误                                                    |
| `message.loading(content, duration?)` | 加载（带旋转图标）                                      |
| `message.config(cfg)`                 | 全局默认值配置                                          |
| `message.destroy()`                   | 关闭全部当前提示并卸载容器                              |

### MessageOptions

| 字段         | 类型                  | 默认      | 说明                                                                                 |
| ------------ | --------------------- | --------- | ------------------------------------------------------------------------------------ |
| content      | `string \| VNode`     | —         | 提示内容（必填）                                                                     |
| type         | `MessageType`         | `'info'`  | 类型：`info` / `success` / `warning` / `error` / `loading`                           |
| duration     | number                | `3`       | 停留时长。≤100 按秒，>100 按毫秒；`0` 不自动关闭                                     |
| showClose    | boolean               | `false`   | 是否显示关闭按钮                                                                     |
| icon         | string                | `''`      | 自定义 icon 名（覆盖默认类型图标）                                                   |
| customClass  | string                | `''`      | 自定义类名，便于做样式覆盖                                                           |
| onClose      | `() => void`          | —         | 关闭时回调（自动 / 主动 / destroy 都会触发）                                         |
| key          | `string \| number`    | —         | 标识，便于以同一 key 替换已存在的提示                                                |
| placement    | `MessagePlacement`    | `'top'`   | 6 位置之一：`top` / `topLeft` / `topRight` / `bottom` / `bottomLeft` / `bottomRight` |
| role         | `'alert' \| 'status'` | `'alert'` | DOM `role` + `aria-live`（`alert` → `assertive`；`status` → `polite`）               |
| pauseOnHover | boolean               | `true`    | 鼠标悬停暂停自动关闭计时器                                                           |

### MessageGlobalConfig

通过 `message.config({...})` 设置；优先级低于单次 `open()` 选项。

| 字段         | 类型                  | 默认       | 说明                                      |
| ------------ | --------------------- | ---------- | ----------------------------------------- |
| duration     | number                | `3`        | 默认停留时长（秒）                        |
| maxCount     | number                | `Infinity` | 单 placement 最多并发条数，超出顶掉最旧   |
| stack        | boolean               | `false`    | 视觉堆叠模式（容器加 `--stack` modifier） |
| pauseOnHover | boolean               | `true`     | 全局默认 `pauseOnHover`                   |
| role         | `'alert' \| 'status'` | `'alert'`  | 全局默认 `role`                           |
| top          | `number \| string`    | —          | 顶部偏移（仅作用于 `top*` placement）     |
| bottom       | `number \| string`    | —          | 底部偏移（仅作用于 `bottom*` placement）  |
| getContainer | `() => HTMLElement`   | `body`     | 自定义挂载父节点                          |

### MessageHandle

| 字段  | 类型         | 说明           |
| ----- | ------------ | -------------- |
| close | `() => void` | 主动关闭该提示 |


---

# Modal 对话框

> 文档链接：https://vaebe.github.io/ccui/components/modal/index.html

模态对话框。需要确认操作或集中处理一段交互时使用。

## 基本使用

`v-model:visible` 控制开合。

:::demo

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

<template>
  <c-button type="primary" @click="open = true">打开 Modal</c-button>
  <c-modal v-model:visible="open" title="基本对话框">
    <p>这是一个对话框的内容。</p>
    <p>支持任意 vue 内容。</p>
  </c-modal>
</template>
```

:::

## 自定义按钮文字 / 类型

`ok-text` / `cancel-text` 替换文案，`ok-type="danger"` 把确认按钮渲染为危险色。

:::demo

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

<template>
  <c-button @click="open = true">删除...</c-button>
  <c-modal v-model:visible="open" title="确认删除" ok-text="删除" cancel-text="再想想" ok-type="danger">
    删除后无法恢复，确认要删除吗？
  </c-modal>
</template>
```

:::

## 异步关闭（确认按钮 loading）

通过 `confirm-loading` 控制确认按钮的加载状态，常用于点击确认后请求服务端，请求完成再关闭。

:::demo

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

const open = ref(false)
const loading = ref(false)

function handleOk() {
  loading.value = true
  setTimeout(() => {
    loading.value = false
    open.value = false
  }, 1500)
}
</script>

<template>
  <c-button type="primary" @click="open = true">打开</c-button>
  <c-modal v-model:visible="open" title="异步提交" :confirm-loading="loading" @ok="handleOk">
    点击「确定」后会模拟 1.5s 的请求再关闭弹窗。
  </c-modal>
</template>
```

:::

## 居中显示

`centered` 让 Modal 在视口垂直居中（默认距顶部 100px）。

:::demo

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

<template>
  <c-button @click="open = true">居中打开</c-button>
  <c-modal v-model:visible="open" centered title="垂直居中"> 我在视口中央。 </c-modal>
</template>
```

:::

## 自定义宽度

`width` 接受数字（px）或字符串（如 `'80%'`）。

:::demo

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

<template>
  <c-button @click="v1 = true">小弹窗</c-button>
  &nbsp;
  <c-button @click="v2 = true">大弹窗</c-button>
  <c-modal v-model:visible="v1" :width="360" title="360px"> 紧凑型。 </c-modal>
  <c-modal v-model:visible="v2" width="80%" title="80% 宽"> 适合表格、表单类内容。 </c-modal>
</template>
```

:::

## 不带按钮 / 自定义页脚

`:footer="null"` 隐藏整个页脚；或用 `footer` 插槽完全自定义按钮区。slot 参数 `{ ok, cancel }` 是默认的关闭函数。

:::demo

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

<template>
  <c-button @click="open = true">自定义 footer</c-button>
  <c-modal v-model:visible="open" title="提示">
    <p>此 Modal 自定义了 footer 区域，提供三个动作。</p>
    <template #footer="{ cancel }">
      <c-button @click="cancel">关闭</c-button>
      <c-button type="primary" @click="cancel" style="margin-inline-start: 8px">保存草稿</c-button>
      <c-button type="primary" @click="cancel" style="margin-inline-start: 8px">提交</c-button>
    </template>
  </c-modal>
</template>
```

:::

## 命令式 Modal.confirm

`Modal.confirm({...})` / `.info` / `.success` / `.error` / `.warning` 命令式弹窗，**纯函数调用**，不需要在模板中预写组件。返回 `{ destroy, update }` 句柄。

::: tip 命名空间约定

ccui Vue 风格：**不挂静态属性子组件**（如 `Modal.Header` / `Modal.Footer` 这类我们一律拆为顶层平铺组件）。但 `Modal.confirm` / `.info` 等是**命令式函数调用**，是命名空间下挂函数（而非组件），符合 JS 模块惯例，保留。

:::

:::demo

```vue
<script setup>
import { Modal } from '@vaebe/ccui'

function ask() {
  Modal.confirm({
    title: '确认删除',
    content: '此操作不可恢复，确认继续？',
    okText: '删除',
    okType: 'danger',
    onOk: () => fetch('/api/delete'),
    onCancel: () => console.log('canceled'),
  })
}

function showInfo() {
  Modal.info({ title: '系统提示', content: '已生成新报表，请到列表查看。' })
}

function showSuccess() {
  Modal.success({ title: '部署成功', content: '版本 v2.0.0 已上线。' })
}

function showError() {
  Modal.error({ title: '请求失败', content: '网络异常，请稍后重试。' })
}

function showWarning() {
  Modal.warning({ title: '警告', content: '磁盘空间不足 10%。' })
}
</script>

<template>
  <c-button type="danger" @click="ask">弹 confirm</c-button>
  <c-button @click="showInfo">info</c-button>
  <c-button type="primary" @click="showSuccess">success</c-button>
  <c-button @click="showError">error</c-button>
  <c-button @click="showWarning">warning</c-button>
</template>
```

:::

### onOk 返回 Promise（loading 串行）

`onOk` 返回 Promise 时，OK 按钮自动进入 loading 状态直到 resolve；reject 时**不关闭** modal（错误传给调用方）。

:::demo

```vue
<script setup>
import { Modal } from '@vaebe/ccui'

function asyncConfirm() {
  Modal.confirm({
    title: '提交订单',
    content: '请稍候 1.5 秒...',
    onOk: () => new Promise((resolve) => setTimeout(resolve, 1500)),
  })
}
</script>

<template>
  <c-button type="primary" @click="asyncConfirm">异步 confirm</c-button>
</template>
```

:::

### update / destroy 句柄

返回的 handle 可动态更新 title / content，或强制销毁。

:::demo

```vue
<script setup>
import { Modal } from '@vaebe/ccui'

function progressDemo() {
  let i = 1
  const handle = Modal.info({ title: '进度', content: `当前 ${i} / 3` })
  const timer = setInterval(() => {
    i += 1
    if (i > 3) {
      clearInterval(timer)
      handle.destroy()
      return
    }
    handle.update({ content: `当前 ${i} / 3` })
  }, 1000)
}
</script>

<template>
  <c-button @click="progressDemo">进度条 demo</c-button>
</template>
```

:::

### Modal.destroyAll

```ts
Modal.destroyAll() // 关闭所有当前活跃命令式 modal（不影响 <c-modal> 模板实例）
```

## useModal composable

`useModal()` 返回 `{ modal, holder }` **对象**（**不是** React `[modal, contextHolder]` 元组）。命令式调用会继承调用组件的 provide / ConfigProvider / 主题 / locale 链——**与全局 `Modal.confirm` 的最大差异**：全局版走独立 `createApp`，拿不到调用方 app 的 inject。

::: tip 何时用模块级 vs Hook 版？

- **`Modal.confirm({...})`**：脚手架 / utils / 命令式弹一条，简单直接，但**拿不到调用方 app 的 inject**。
- **`useModal()`**：当 confirm 弹窗需要继承父链 inject（自定义 ConfigProvider、主题、locale、formContext）时用。**必须**在模板中挂 `<component :is="holder" />` 保持 API 一致；hook 在 setup 阶段捕获 instance 并在 `modal.confirm()` 调用时**懒读** `inst.provides` 拿到最终 provides 链。

:::

:::demo

```vue
<script setup>
import { useModal } from '@vaebe/ccui'

const { modal, holder } = useModal()

function ask() {
  modal.confirm({
    title: '继承上下文',
    content: '我能读到父组件 provide 的 theme / locale / ConfigProvider',
    onOk: () => Promise.resolve(),
  })
}
</script>

<template>
  <component :is="holder" />
  <c-button type="primary" @click="ask">弹出（继承上下文）</c-button>
</template>
```

:::

### UseModalReturn

| 字段   | 类型        | 说明                                                             |
| ------ | ----------- | ---------------------------------------------------------------- |
| modal  | `ModalApi`  | 命令式 API：`confirm` / `info` / `success` / `error` / `warning` |
| holder | `Component` | 必须挂到模板：`<component :is="holder" />`                       |

### ModalFuncOptions

| 字段          | 类型                                 | 默认         | 说明                                                             |
| ------------- | ------------------------------------ | ------------ | ---------------------------------------------------------------- |
| title         | `string \| VNode`                    | —            | 标题                                                             |
| content       | `string \| VNode`                    | —            | 正文                                                             |
| type          | `ModalFuncType`                      | `'confirm'`  | `confirm` / `info` / `success` / `error` / `warning`             |
| icon          | `string \| VNode`                    | —            | 自定义图标（不传则按 type 渲染默认图标；传空字符串隐藏图标）     |
| width         | `number \| string`                   | `416`        | 弹窗宽度（命令式默认 416 比常规 Modal 的 520 更窄）              |
| centered      | boolean                              | `false`      | 垂直居中                                                         |
| mask          | boolean                              | `true`       | 遮罩                                                             |
| maskClosable  | boolean                              | `false`      | 点击遮罩关闭（confirm 系列默认 false）                           |
| closeOnEsc    | boolean                              | `true`       | Esc 关闭                                                         |
| closable      | boolean                              | `false`      | 显示右上角关闭按钮                                               |
| okText        | string                               | `'确 定'`    | OK 按钮文字                                                      |
| cancelText    | string                               | `'取 消'`    | Cancel 按钮文字（仅 type='confirm' 渲染）                        |
| okType        | `'primary' \| 'danger' \| 'default'` | 按 type 推导 | OK 按钮类型                                                      |
| onOk          | `() => void \| Promise<unknown>`     | —            | OK 回调；返回 Promise 时按钮 loading 直到 resolve；reject 不关闭 |
| onCancel      | `() => void \| Promise<unknown>`     | —            | Cancel 回调                                                      |
| afterClose    | `() => void`                         | —            | 弹窗完全关闭并卸载 DOM 后触发（含离场动画完成）                  |
| zIndex        | number                               | —            | 透传 Modal `zIndex`                                              |
| wrapClassName | string                               | —            | 透传 Modal `wrapClassName`                                       |

### ModalFuncReturn

| 字段    | 类型                                                                       | 说明                         |
| ------- | -------------------------------------------------------------------------- | ---------------------------- |
| destroy | `() => void`                                                               | 强制关闭并卸载               |
| update  | `(updater: Partial<ModalFuncOptions> \| ((prev) => Partial<...>)) => void` | 更新部分选项（合并，不替换） |

## API

### Props

| 参数                   | 类型                                                                                 | 默认值      | 说明                                                   |
| ---------------------- | ------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------ |
| visible                | boolean                                                                              | `false`     | 是否可见（支持 `v-model:visible`）                     |
| title                  | string                                                                               | `''`        | 标题（也可用 `title` slot 自定义）                     |
| width                  | `number \| string`                                                                   | `520`       | 宽度，数字为 px                                        |
| closable               | `boolean \| { closeIcon?: VNode \| string; disabled?: boolean; ariaLabel?: string }` | `true`      | 关闭按钮配置；对象形支持自定义图标 / 禁用 / aria-label |
| maskClosable           | boolean                                                                              | `true`      | 点击蒙层是否关闭                                       |
| closeOnEsc             | boolean                                                                              | `true`      | 按 Esc 是否关闭                                        |
| centered               | boolean                                                                              | `false`     | 是否垂直居中显示                                       |
| mask                   | boolean                                                                              | `true`      | 是否显示蒙层                                           |
| okText                 | string                                                                               | `'确 定'`   | 确认按钮文案                                           |
| cancelText             | string                                                                               | `'取 消'`   | 取消按钮文案                                           |
| okType                 | `'primary' \| 'danger' \| 'default'`                                                 | `'primary'` | 确认按钮类型                                           |
| confirmLoading         | boolean                                                                              | `false`     | 确认按钮加载态                                         |
| footer                 | `string \| VNode \| null \| undefined`                                               | --          | 底部按钮区：`null` 隐藏；`string` / VNode 直接渲染     |
| destroyOnClose         | boolean                                                                              | `false`     | 关闭时销毁内部内容（与 `keepAlive` 互斥）              |
| keepAlive              | boolean                                                                              | `false`     | 即使未打开也保留 DOM（与 `destroyOnClose` 互斥）       |
| wrapClassName          | string                                                                               | --          | 自定义根节点 class                                     |
| transitionName         | string                                                                               | --          | 自定义 Transition 名（空走内置 `-zoom`）               |
| maskTransitionName     | string                                                                               | --          | mask 自定义 Transition 名（空走内置 `-mask-fade`）     |
| focusTriggerAfterClose | boolean                                                                              | `true`      | 关闭后聚焦回打开前的触发元素                           |
| appendToBody           | boolean                                                                              | `true`      | 是否把浮层 Teleport 到 `document.body`                 |
| zIndex                 | number                                                                               | `1000`      | z-index                                                |

### Events

| 事件名            | 回调签名             | 触发时机                                                 |
| ----------------- | -------------------- | -------------------------------------------------------- |
| update:visible    | `(visible: boolean)` | 显示状态变化（v-model:visible）                          |
| after-open-change | `(open: boolean)`    | 打开 / 关闭动画完成后触发（immediate watch，首次 false） |
| ok                | `()`                 | 点击确认按钮                                             |
| cancel            | `()`                 | 点击取消 / 关闭 / Esc                                    |
| close             | `()`                 | 关闭过程中（先于 cancel）                                |
| open              | `()`                 | 开始展开                                                 |
| opened            | `()`                 | 展开动画完成                                             |
| closed            | `()`                 | 收起动画完成                                             |

### Slots

| 名称       | slot 参数        | 说明                                              |
| ---------- | ---------------- | ------------------------------------------------- |
| default    | -                | 弹窗内容                                          |
| title      | -                | 自定义标题区                                      |
| footer     | `{ ok, cancel }` | 自定义底部按钮（优先级高于 `footer` prop）        |
| close-icon | -                | 自定义关闭图标（优先级高于 `closable.closeIcon`） |


---

# Notification 通知

> 文档链接：https://vaebe.github.io/ccui/components/notification/index.html

四角弹出的通知提醒，比 Message 更适合带标题 + 描述的多行内容。默认 4.5 秒自动关闭，右上角弹出。

## 基本使用

`notification.success` / `info` / `warning` / `error` 都接受 `{ title, description }` 形式的对象。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

function open() {
  notification.success({
    title: '操作成功',
    description: '您的操作已完成，可以继续下一步。',
  })
}
</script>

<template>
  <c-button type="primary" @click="open">显示通知</c-button>
</template>
```

:::

## 不同类型

不同 `type` 对应不同前置图标和强调色。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

const items = [
  { type: 'info', title: '提示', desc: '有一份新报表生成了。' },
  { type: 'success', title: '成功', desc: '部署已完成。' },
  { type: 'warning', title: '警告', desc: '磁盘空间不足 10%。' },
  { type: 'error', title: '失败', desc: '请求超时，请重试。' },
]

function open(item) {
  notification[item.type]({ title: item.title, description: item.desc })
}
</script>

<template>
  <c-button v-for="it in items" :key="it.type" @click="open(it)">
    {{ it.title }}
  </c-button>
</template>
```

:::

## 弹出位置

支持 6 个位置：`topRight` / `topLeft` / `top`（顶部居中）/ `bottomRight` / `bottomLeft` / `bottom`（底部居中）。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

const placements = ['top', 'topLeft', 'topRight', 'bottom', 'bottomLeft', 'bottomRight']

function open(placement) {
  notification.info({
    title: placement,
    description: `从 ${placement} 弹入`,
    placement,
  })
}
</script>

<template>
  <c-button v-for="p in placements" :key="p" @click="open(p)">{{ p }}</c-button>
</template>
```

:::

## 自定义停留时长

`duration` 推荐传**秒**；传 `0` 则不自动关闭，需要用户手动点 ×。

::: tip 单位规则

- `duration ≤ 100` 视为「秒」（如 `4.5` → 4.5 秒）
- `duration > 100` 视为「毫秒」（如 `4500`）
- `duration === 0` 永远表示不自动关闭

:::

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

function shortToast() {
  notification.success({
    title: '快闪',
    description: '1.5 秒后自动消失',
    duration: 1.5, // 秒
  })
}
function sticky() {
  notification.warning({
    title: '常驻提醒',
    description: '不会自动消失，需要点 × 关闭',
    duration: 0,
  })
}
function msUnit() {
  notification.info({
    title: '毫秒写法',
    description: '4500ms = 4.5s',
    duration: 4500,
  })
}
</script>

<template>
  <c-button @click="shortToast">短 (1.5s)</c-button>
  <c-button @click="sticky">常驻 (duration=0)</c-button>
  <c-button @click="msUnit">毫秒 (4500)</c-button>
</template>
```

:::

## 全局配置 notification.config

`notification.config(...)` 设置 `maxCount` / `stack` / `pauseOnHover` / `role` / `duration` / `top` / `bottom` / `placement` / `getContainer` 等全局默认值。再次调用以覆盖前一次配置。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

function setupStack() {
  notification.config({ maxCount: 3, stack: true })
  for (let i = 1; i <= 5; i += 1) {
    notification.info({ title: `第 ${i} 条`, duration: 0 })
  }
}
function setupOffset() {
  notification.config({ top: 100 })
  notification.success({ title: '顶部偏移 100px', duration: 3 })
}
function reset() {
  notification.destroy()
  notification.config({ maxCount: Infinity, stack: false, top: undefined })
}
</script>

<template>
  <c-button @click="setupStack">maxCount=3 + stack</c-button>
  <c-button @click="setupOffset">top=100px</c-button>
  <c-button @click="reset">还原</c-button>
</template>
```

:::

## 主动关闭 + 关闭回调

`open` / 各类型方法都返回 `NotificationHandle`，调用 `handle.close()` 可主动收掉；`onClose` 在关闭时（自动 / 主动 / destroy）触发。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'
import { ref } from 'vue'

const handle = ref(null)
const closedTimes = ref(0)

function openControlled() {
  handle.value = notification.info({
    title: '受控通知',
    description: '可手动关，也会触发回调',
    duration: 0,
    onClose() {
      closedTimes.value += 1
    },
  })
}

function closeManually() {
  handle.value?.close()
  handle.value = null
}
</script>

<template>
  <c-button @click="openControlled">弹出受控通知</c-button>
  <c-button :disabled="!handle" @click="closeManually">手动关闭</c-button>
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">已关闭：{{ closedTimes }} 次</span>
</template>
```

:::

## 全局清空

`notification.destroy()` 会关闭四个角的全部通知，并卸载容器；下次再调用会重新挂载。

:::demo

```vue
<script setup>
import { notification } from '@vaebe/ccui'

function spam() {
  notification.info({ title: '左上', description: '内容', placement: 'topLeft' })
  notification.success({ title: '右上', description: '内容', placement: 'topRight' })
  notification.warning({ title: '左下', description: '内容', placement: 'bottomLeft' })
  notification.error({ title: '右下', description: '内容', placement: 'bottomRight' })
}
function clear() {
  notification.destroy()
}
</script>

<template>
  <c-button @click="spam">四角各发一条</c-button>
  <c-button type="danger" @click="clear">全部清空</c-button>
</template>
```

:::

## useNotification composable

`useNotification()` 返回 `{ notification, holder }` **对象**（**不是** React 风格元组）。容器渲染在当前 Vue 子树里，自动继承父组件 provide 的 ConfigProvider / 主题等上下文——**与模块级 `notification` 的最大差异**。

::: tip 何时用模块级 vs Hook 版？

- **模块级 `import { notification } from '@vaebe/ccui'`**：脚手架 / utils / 命令式弹一条，简单直接，但容器走独立 `createApp`，**拿不到调用方 app 的 inject**（自定义 ConfigProvider、主题、locale）。
- **Hook `useNotification()`**：当通知需要继承组件树上下文时用。**必须**在模板中挂 `<component :is="holder" />`。

:::

:::demo

```vue
<script setup>
import { useNotification } from '@vaebe/ccui'

const { notification, holder } = useNotification()

function show() {
  notification.success({ title: '继承上下文', description: 'locale / theme 都来自父组件', duration: 3 })
}
</script>

<template>
  <component :is="holder" />
  <c-button type="primary" @click="show">弹出（继承上下文）</c-button>
</template>
```

:::

### UseNotificationReturn

| 字段         | 类型              | 说明                                                                           |
| ------------ | ----------------- | ------------------------------------------------------------------------------ |
| notification | `NotificationApi` | 与全局 `notification` 同 API：`info/success/warning/error/open/config/destroy` |
| holder       | `Component`       | 必须挂到模板：`<component :is="holder" />`                                     |

## API

### notification 命名空间

| 方法                         | 说明                                                          |
| ---------------------------- | ------------------------------------------------------------- |
| `notification.open(options)` | 通用入口，传 `NotificationOptions`，返回 `NotificationHandle` |
| `notification.info(options)` | info 类型                                                     |
| `notification.success(...)`  | success 类型                                                  |
| `notification.warning(...)`  | warning 类型                                                  |
| `notification.error(...)`    | error 类型                                                    |
| `notification.config(cfg)`   | 全局默认值配置                                                |
| `notification.destroy()`     | 关闭并卸载所有通知容器                                        |

### NotificationOptions

| 字段         | 类型                    | 默认         | 说明                                                                             |
| ------------ | ----------------------- | ------------ | -------------------------------------------------------------------------------- |
| title        | string                  | —            | 通知标题（建议必填）                                                             |
| description  | `string \| VNode`       | —            | 通知正文                                                                         |
| type         | `NotificationType`      | `'info'`     | 类型：`info` / `success` / `warning` / `error`                                   |
| placement    | `NotificationPlacement` | `'topRight'` | 6 位置：`top` / `topRight` / `topLeft` / `bottom` / `bottomRight` / `bottomLeft` |
| duration     | number                  | `4.5`        | 停留时长。≤100 按秒，>100 按毫秒；`0` 不自动关闭                                 |
| showClose    | boolean                 | `true`       | 是否显示关闭按钮                                                                 |
| icon         | string                  | `''`         | 自定义 icon 名（覆盖默认类型图标）                                               |
| customClass  | string                  | `''`         | 自定义类名                                                                       |
| onClose      | `() => void`            | —            | 关闭时回调                                                                       |
| role         | `'alert' \| 'status'`   | `'alert'`    | DOM `role` + `aria-live`（`alert` → `assertive`；`status` → `polite`）           |
| pauseOnHover | boolean                 | `true`       | 鼠标悬停暂停自动关闭计时器                                                       |

### NotificationGlobalConfig

通过 `notification.config({...})` 设置；优先级低于单次 `open()` 选项。

| 字段         | 类型                    | 默认         | 说明                                      |
| ------------ | ----------------------- | ------------ | ----------------------------------------- |
| duration     | number                  | `4.5`        | 默认停留时长（秒）                        |
| maxCount     | number                  | `Infinity`   | 单 placement 最多并发条数，超出顶掉最旧   |
| stack        | boolean                 | `false`      | 视觉堆叠模式（容器加 `--stack` modifier） |
| pauseOnHover | boolean                 | `true`       | 全局默认 `pauseOnHover`                   |
| role         | `'alert' \| 'status'`   | `'alert'`    | 全局默认 `role`                           |
| placement    | `NotificationPlacement` | `'topRight'` | 全局默认弹出位置                          |
| top          | `number \| string`      | —            | 顶部偏移（仅作用于 `top*` placement）     |
| bottom       | `number \| string`      | —            | 底部偏移（仅作用于 `bottom*` placement）  |
| getContainer | `() => HTMLElement`     | `body`       | 自定义挂载父节点                          |

### NotificationHandle

| 字段  | 类型         | 说明           |
| ----- | ------------ | -------------- |
| close | `() => void` | 主动关闭该通知 |


---

# Pagination 分页

> 文档链接：https://vaebe.github.io/ccui/components/pagination/index.html

切分大列表为多页展示。

## 基本使用

`v-model:current` 双向绑定当前页码；`total` 提供总条数，分页器自动按 `pageSize`（默认 10）算页数。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const current = ref(1)
</script>

<template>
  <c-pagination v-model:current="current" :total="100" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前第 {{ current }} 页</p>
</template>
```

:::

## 显示总数

`show-total` 设为 `true` 显示"共 N 条"，传函数则可自定义文案。

:::demo

```vue
<template>
  <c-pagination :total="500" :current="1" :page-size="20" show-total />
  <c-pagination
    style="margin-top: 12px"
    :total="500"
    :current="2"
    :page-size="20"
    :show-total="(total, range) => `第 ${range[0]}-${range[1]} 项 / 共 ${total} 项`"
  />
</template>
```

:::

## 切换每页条数

`show-size-changer` 显示一个下拉用于改 `pageSize`，可用 `page-size-options` 指定可选数。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const current = ref(1)
const size = ref(20)
</script>

<template>
  <c-pagination
    v-model:current="current"
    v-model:page-size="size"
    :total="500"
    :page-size-options="[10, 20, 50, 100]"
    show-size-changer
    show-total
  />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">page={{ current }} pageSize={{ size }}</p>
</template>
```

:::

## 快速跳页

`show-quick-jumper` 在右侧显示一个数字输入框，输入后回车跳转。

:::demo

```vue
<template>
  <c-pagination :total="800" :current="3" :page-size="20" show-quick-jumper show-total />
</template>
```

:::

## 简洁模式

`simple` 仅显示"当前/总页数 + 上一页 / 下一页"，常用于移动端或紧凑场景。

:::demo

```vue
<template>
  <c-pagination :total="200" :current="1" simple />
</template>
```

:::

## 小尺寸

`size="small"` 缩小整体高度与字号，适合放在表格 toolbar 里。

:::demo

```vue
<template>
  <c-pagination :total="100" :current="1" size="small" show-total />
</template>
```

:::

## 禁用 / 单页隐藏

`disabled` 整体禁用；`hide-on-single-page` 在只有一页时隐藏自身。

:::demo

```vue
<template>
  <c-pagination :total="100" :current="1" disabled />
  <c-pagination :total="5" :page-size="10" hide-on-single-page />
  <p style="color: var(--ccui-color-text-secondary)">↑ 上方 disabled，下方因只有 1 页被隐藏</p>
</template>
```

:::

## API

### Props

| 参数             | 类型                                  | 默认值              | 说明                              |
| ---------------- | ------------------------------------- | ------------------- | --------------------------------- |
| current          | number                                | `1`                 | 当前页，支持 `v-model:current`    |
| total            | number                                | `0`                 | 总条数                            |
| pageSize         | number                                | `10`                | 每页条数，支持 `v-model:pageSize` |
| pageSizeOptions  | `number[]`                            | `[10, 20, 50, 100]` | 切换 pageSize 的下拉选项          |
| showSizeChanger  | boolean                               | `false`             | 显示每页条数切换器                |
| showQuickJumper  | boolean                               | `false`             | 显示快速跳页输入                  |
| showTotal        | `boolean \| (total, range) => string` | `false`             | 显示总数；传函数自定义文案        |
| simple           | boolean                               | `false`             | 简洁模式                          |
| disabled         | boolean                               | `false`             | 整体禁用                          |
| hideOnSinglePage | boolean                               | `false`             | 只有 1 页时隐藏自身               |
| size             | `'default' \| 'small'`                | `'default'`         | 尺寸                              |

### Events

| 事件名          | 回调签名                           | 说明           |
| --------------- | ---------------------------------- | -------------- |
| update:current  | `(page: number)`                   | 页码变化       |
| update:pageSize | `(size: number)`                   | 每页条数变化   |
| change          | `(page: number, pageSize: number)` | 页码或条数变化 |


---

# Popconfirm 气泡确认

> 文档链接：https://vaebe.github.io/ccui/components/popconfirm/index.html

在被点击的元素附近弹出二次确认气泡。比 Modal 轻量，适合"删除 / 重置 / 注销"等需要明确反悔机会的危险操作。

## 基本使用

`title` 是主问句；用 `description` 补充后果说明。点确定 / 取消都会自动收起。

:::demo

```vue
<script setup>
import { message } from '@vaebe/ccui'

function onConfirm() {
  message.success('已删除')
}
function onCancel() {
  message.info('已取消')
}
</script>

<template>
  <c-popconfirm title="确认删除？" description="此操作不可恢复" @confirm="onConfirm" @cancel="onCancel">
    <c-button type="danger">删除</c-button>
  </c-popconfirm>
</template>
```

:::

## 自定义按钮文案

`confirm-text` / `cancel-text` 调整按钮文字，业务话术更顺。

:::demo

```vue
<template>
  <c-popconfirm title="保存修改？" confirm-text="保存" cancel-text="放弃">
    <c-button type="primary">保存</c-button>
  </c-popconfirm>
</template>
```

:::

## 不同确定按钮风格

`confirm-type` 切换确定按钮风格：`primary`（默认蓝）/ `danger`（红）/ `default`（次按钮）。

:::demo

```vue
<template>
  <c-popconfirm title="确定执行？" confirm-type="primary">
    <c-button type="primary">primary</c-button>
  </c-popconfirm>
  &nbsp;
  <c-popconfirm title="确定删除？" confirm-type="danger">
    <c-button type="danger">danger</c-button>
  </c-popconfirm>
  &nbsp;
  <c-popconfirm title="保留旧数据？" confirm-type="default">
    <c-button>default</c-button>
  </c-popconfirm>
</template>
```

:::

## 改变弹出方位

`placement` 与 Popover 一致，支持 12 个方位。

:::demo

```vue
<template>
  <c-popconfirm title="弹向上方？" placement="top">
    <c-button>top</c-button>
  </c-popconfirm>
  &nbsp;
  <c-popconfirm title="弹向右侧？" placement="right">
    <c-button>right</c-button>
  </c-popconfirm>
  &nbsp;
  <c-popconfirm title="弹向左下？" placement="bottom-end">
    <c-button>bottom-end</c-button>
  </c-popconfirm>
</template>
```

:::

## 隐藏图标 + 自定义图标颜色

`hide-icon` 完全去掉前置感叹号；保留时可用 `icon-color` 调整颜色（默认是警告黄）。

:::demo

```vue
<template>
  <c-popconfirm title="主色感叹号" icon-color="#1677ff">
    <c-button>蓝色图标</c-button>
  </c-popconfirm>
  &nbsp;
  <c-popconfirm title="无图标" hide-icon>
    <c-button>无图标</c-button>
  </c-popconfirm>
</template>
```

:::

## 受控显示

通过 `v-model:visible` 自己掌控开合，常用于"先做异步校验再决定要不要弹"。

:::demo

```vue
<script setup>
import { ref } from 'vue'
import { message } from '@vaebe/ccui'

const visible = ref(false)

async function tryDelete() {
  // 异步校验：模拟 500ms
  await new Promise((r) => setTimeout(r, 300))
  visible.value = true
}

function confirm() {
  message.success('已删除')
  visible.value = false
}
</script>

<template>
  <c-popconfirm v-model:visible="visible" title="后端校验通过，确认删除？" trigger="manual" @confirm="confirm">
    <c-button type="danger" @click="tryDelete">校验后再删</c-button>
  </c-popconfirm>
</template>
```

:::

## API

### Props

| 参数                      | 类型                                        | 默认值      | 说明                                           |
| ------------------------- | ------------------------------------------- | ----------- | ---------------------------------------------- |
| title                     | string                                      | `''`        | 主问句                                         |
| description               | string                                      | `''`        | 补充说明（可选）                               |
| placement                 | `PopoverPlacement`                          | `'top'`     | 12 方位之一                                    |
| confirmText               | string                                      | `'确 定'`   | 确定按钮文案（未传时走 ConfigProvider locale） |
| cancelText                | string                                      | `'取 消'`   | 取消按钮文案                                   |
| confirmType               | `'primary' \| 'danger' \| 'default'`        | `'primary'` | 确定按钮类型                                   |
| icon                      | string                                      | `''`        | 自定义 icon 类名（覆盖默认感叹号）             |
| iconColor                 | string                                      | `'#faad14'` | 图标颜色                                       |
| hideIcon                  | boolean                                     | `false`     | 隐藏前置图标                                   |
| width                     | `number \| string`                          | `''`        | 弹出层宽度                                     |
| disabled                  | boolean                                     | `false`     | 禁用整个弹出（点击不响应）                     |
| visible / v-model:visible | boolean                                     | `undefined` | 受控显示状态                                   |
| trigger                   | `'click' \| 'hover' \| 'focus' \| 'manual'` | `'click'`   | 触发方式                                       |

### Events

| 事件名         | 回调签名             | 触发时机             |
| -------------- | -------------------- | -------------------- |
| confirm        | `(e: MouseEvent)`    | 点击"确定"按钮       |
| cancel         | `(e: MouseEvent)`    | 点击"取消"按钮       |
| update:visible | `(visible: boolean)` | v-model:visible 同步 |

### Slots

| 名称        | 说明                                                      |
| ----------- | --------------------------------------------------------- |
| default     | 触发气泡的元素                                            |
| title       | 自定义标题                                                |
| description | 自定义描述                                                |
| actions     | 自定义底部按钮（参数 `{ confirm, cancel }` 用于主动收起） |


---

# Popover 弹出框

> 文档链接：https://vaebe.github.io/ccui/components/popover/index.html

用于在不打断用户流程的情况下展示补充信息和操作内容。支持标题 / 富文本内容 / 不同触发方式与位置控制。

## 何时使用

- 需要在不打断用户流程的情况下展示补充信息和操作内容
- 支持标题、富文本内容、不同触发方式与位置控制
- 需要展示比 Tooltip 更复杂的内容和操作

## 基本使用

最简单的用法，默认点击触发显示弹出框。

:::demo

```vue
<template>
  <c-popover title="标题" content="这是一段 Popover 内容">
    <c-button type="primary" plain>点击触发</c-button>
  </c-popover>
</template>
```

:::

## 悬停触发

`trigger="hover"` 鼠标悬停时显示弹出框。

:::demo

```vue
<template>
  <c-popover trigger="hover" content="鼠标悬停显示">
    <c-button type="primary" plain>Hover</c-button>
  </c-popover>
</template>
```

:::

## 自定义内容与标题插槽

`#title` / `#content` slot 可插入任意 VNode，常用于带操作按钮的富文本浮层。

:::demo

```vue
<template>
  <c-popover>
    <template #title>
      <span>自定义标题</span>
    </template>
    <template #content>
      <div style="max-width: 240px">
        <p style="margin: 0 0 8px">支持任意插槽内容</p>
        <c-button type="primary" plain size="small">操作</c-button>
      </div>
    </template>
    <c-button type="primary" plain>自定义内容</c-button>
  </c-popover>
</template>
```

:::

## 12 个出现位置

通过 `placement` 控制方位。

:::demo

```vue
<script setup>
const tops = ['top-start', 'top', 'top-end']
const lefts = ['left-start', 'left', 'left-end']
const rights = ['right-start', 'right', 'right-end']
const bottoms = ['bottom-start', 'bottom', 'bottom-end']
</script>

<template>
  <div class="demo-popover-placement">
    <div class="row">
      <c-popover v-for="p in tops" :key="p" :placement="p" :content="`title ${p}`" trigger="hover">
        <c-button type="primary" plain>{{ p }}</c-button>
      </c-popover>
    </div>
    <div class="center">
      <div class="col">
        <c-popover v-for="p in lefts" :key="p" :placement="p" :content="`title ${p}`" trigger="hover">
          <c-button type="primary" plain>{{ p }}</c-button>
        </c-popover>
      </div>
      <div class="col">
        <c-popover v-for="p in rights" :key="p" :placement="p" :content="`title ${p}`" trigger="hover">
          <c-button type="primary" plain>{{ p }}</c-button>
        </c-popover>
      </div>
    </div>
    <div class="row">
      <c-popover v-for="p in bottoms" :key="p" :placement="p" :content="`title ${p}`" trigger="hover">
        <c-button type="primary" plain>{{ p }}</c-button>
      </c-popover>
    </div>
  </div>
</template>

<style scoped>
.demo-popover-placement {
  width: 460px;
  margin: 0 auto;
}
.demo-popover-placement .row {
  display: flex;
  justify-content: center;
  gap: 8px;
}
.demo-popover-placement .center {
  display: flex;
  justify-content: space-between;
  margin: 10px 0;
}
.demo-popover-placement .col {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.demo-popover-placement .ccui-button {
  width: 110px;
  font-size: 12px;
}
</style>
```

:::

## 自定义背景色 color

`color` 优先于 `effect`，接受任意 CSS color 字符串，常用于品牌色 / 警告色 / 渐变。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-popover content="品牌蓝" color="#1677ff" trigger="hover">
      <c-button type="primary" plain>蓝</c-button>
    </c-popover>
    <c-popover content="成功绿" color="#52c41a" trigger="hover">
      <c-button type="primary" plain>绿</c-button>
    </c-popover>
    <c-popover content="警告红" color="#f5222d" trigger="hover">
      <c-button type="primary" plain>红</c-button>
    </c-popover>
  </div>
</template>
```

:::

## 显隐箭头 show-arrow

通过 `show-arrow` 控制箭头显示/隐藏。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-popover content="默认带箭头" placement="top" trigger="hover">
      <c-button type="primary" plain>带箭头</c-button>
    </c-popover>
    <c-popover content="无箭头" placement="top" trigger="hover" :show-arrow="false">
      <c-button type="primary" plain>无箭头</c-button>
    </c-popover>
  </div>
</template>
```

:::

## 弹层宽度 width

`width` 控制弹层固定宽度，常用于复杂内容场景避免内容塌缩。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-popover title="说明" content="这段文字较短，无需固定宽度" trigger="hover">
      <c-button type="primary" plain>默认</c-button>
    </c-popover>
    <c-popover
      title="说明（固定 280px）"
      content="即便内容很短，弹层依然保持 280px 宽度；适合需要对齐的卡片样式场景"
      :width="280"
      trigger="hover"
    >
      <c-button type="primary" plain>width = 280</c-button>
    </c-popover>
  </div>
</template>
```

:::

## 触发方式

`hover` / `click` / `focus` / `manual` / `contextmenu` 五种。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-popover trigger="hover" content="鼠标悬停">
      <c-button type="primary" plain>Hover</c-button>
    </c-popover>
    <c-popover trigger="click" content="点击触发">
      <c-button type="primary" plain>Click</c-button>
    </c-popover>
    <c-popover trigger="focus" content="聚焦触发">
      <c-button type="primary" plain>Focus</c-button>
    </c-popover>
    <c-popover trigger="contextmenu" title="右键菜单" content="右键点击触发">
      <c-button type="primary" plain>右键点击</c-button>
    </c-popover>
  </div>
</template>
```

:::

## 延迟显示 / 隐藏

通过 `show-after` / `hide-after` 控制显隐延迟（ms）。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-popover content="延迟 800ms 显示" :show-after="800" trigger="hover">
      <c-button type="primary" plain>延迟显示</c-button>
    </c-popover>
    <c-popover content="延迟 800ms 隐藏" :hide-after="800" trigger="hover">
      <c-button type="primary" plain>延迟隐藏</c-button>
    </c-popover>
  </div>
</template>
```

:::

## 受控显示 v-model:visible

`visible` 配合 `v-model:visible` 双向同步。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const visible = ref(false)
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center">
    <c-popover
      v-model:visible="visible"
      title="v-model:visible"
      content="通过 v-model:visible 接管显隐状态"
      trigger="manual"
    >
      <c-button type="primary" plain>受控触发器</c-button>
    </c-popover>
    <c-button type="primary" plain @click="visible = !visible">{{ visible ? '隐藏' : '显示' }}</c-button>
    <span style="color: var(--ccui-color-text-secondary)">visible = {{ visible }}</span>
  </div>
</template>
```

:::

## ref 调用 hide 方法

通过 ref 拿到组件实例后调用 `hide()` 可以在事件回调内主动关闭浮层，常用于「点确认后关闭」流程。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const popRef = ref(null)
function confirm() {
  console.log('确认操作')
  popRef.value?.hide()
}
function cancel() {
  popRef.value?.hide()
}
</script>

<template>
  <c-popover ref="popRef" trigger="click" :width="280">
    <template #title>
      <span style="color: #f5222d"><c-icon name="mdi:alert" /> 确认删除</span>
    </template>
    <template #content>
      <p style="margin: 0 0 12px; color: var(--ccui-color-text-secondary)">此操作将永久删除该文件，是否继续？</p>
      <div style="display: flex; justify-content: flex-end; gap: 8px">
        <c-button size="small" @click="cancel">取消</c-button>
        <c-button type="primary" size="small" danger @click="confirm">确定</c-button>
      </div>
    </template>
    <c-button type="primary" plain danger>删除文件</c-button>
  </c-popover>
</template>
```

:::

## 自动关闭

`auto-close` 设置毫秒数，弹层在指定时间后自动隐藏；常用于 toast-like 提示场景。

:::demo

```vue
<template>
  <c-popover trigger="click" :auto-close="3000" title="自动关闭" content="3 秒后自动关闭">
    <c-button type="primary" plain>点击我（3 秒后自动关闭）</c-button>
  </c-popover>
</template>
```

:::

## 虚拟触发

`virtual-triggering` 配合 `virtual-ref`，让浮层挂在外部任意元素上，常用于「触发节点和声明位置分离」的场景。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const triggerRef = ref()
const visible = ref(false)
</script>

<template>
  <div class="demo-popover-virtual">
    <div class="virtual-trigger-area">
      <div ref="triggerRef" class="virtual-trigger" @mouseenter="visible = true" @mouseleave="visible = false">
        虚拟触发区域（hover 我）
      </div>
    </div>
    <c-popover
      v-model:visible="visible"
      :virtual-triggering="true"
      :virtual-ref="triggerRef"
      trigger="manual"
      content="这是通过虚拟触发显示的内容"
    />
  </div>
</template>

<style scoped>
.virtual-trigger-area {
  border: 2px dashed var(--ccui-color-border);
  padding: 18px;
  text-align: center;
  border-radius: 4px;
}
.virtual-trigger {
  background: var(--ccui-area);
  padding: 10px;
  border-radius: 4px;
  cursor: pointer;
  transition: background 0.3s;
}
.virtual-trigger:hover {
  background: var(--ccui-color-primary-bg);
}
</style>
```

:::

## 业务场景：用户卡片 hover

用户列表上 hover 头像 / 名字时展示完整用户卡，是 IM / 协作工具最常见的悬浮卡片范式。

:::demo

```vue
<script setup>
const users = [
  { value: 'alice', name: 'Alice', role: 'PM', desc: '负责需求评审与排期协调', color: '#1677ff' },
  { value: 'bob', name: 'Bob', role: 'Frontend', desc: '专注组件库与可视化', color: '#52c41a' },
  { value: 'carol', name: 'Carol', role: 'Backend', desc: '微服务与数据接口', color: '#fa8c16' },
]
</script>

<template>
  <div style="display: flex; gap: 16px">
    <c-popover v-for="u in users" :key="u.value" trigger="hover" :width="240" placement="bottom-start">
      <template #content>
        <div style="display: flex; gap: 12px; align-items: flex-start">
          <div
            :style="{
              width: '48px',
              height: '48px',
              borderRadius: '50%',
              background: u.color,
              color: 'var(--ccui-color-text-light-solid)',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              fontSize: '20px',
              flexShrink: 0,
            }"
          >
            {{ u.name.charAt(0) }}
          </div>
          <div>
            <strong>{{ u.name }}</strong>
            <p style="margin: 4px 0; color: var(--ccui-color-text-tertiary); font-size: 12px">{{ u.role }}</p>
            <p style="margin: 0; color: var(--ccui-color-text-secondary); font-size: 12px">{{ u.desc }}</p>
          </div>
        </div>
      </template>
      <a href="#" style="color: var(--ccui-color-primary)">{{ u.name }}</a>
    </c-popover>
  </div>
</template>
```

:::

## API

### Popover Props

| 参数                      | 说明                                        | 类型                                                         | 默认值             |
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------ | ------------------ |
| title                     | 标题文本，也可以通过 `slot#title` 传入      | string                                                       | —                  |
| content                   | 显示的内容，也可以通过 `slot#content` 传入  | string                                                       | —                  |
| placement                 | Popover 的出现位置                          | 12 种方位字符串                                              | bottom             |
| effect                    | 默认提供的主题                              | `'dark' \| 'light'`                                          | light              |
| visible / v-model:visible | 受控显示状态                                | boolean                                                      | false              |
| disabled                  | Popover 是否可用                            | boolean                                                      | false              |
| color                     | 自定义背景色（覆盖 `effect`）               | string                                                       | —                  |
| show-arrow                | 是否显示箭头                                | boolean                                                      | true               |
| trigger                   | 触发方式                                    | `'hover' \| 'focus' \| 'click' \| 'manual' \| 'contextmenu'` | click              |
| show-after                | 鼠标进入显示延迟（ms）                      | number                                                       | 0                  |
| hide-after                | 鼠标离开隐藏延迟（ms）                      | number                                                       | 200                |
| popper-class              | 浮层根节点 class                            | string                                                       | —                  |
| fresh                     | 关闭后是否销毁内部内容                      | boolean                                                      | false              |
| destroyTooltipOnHide      | 隐藏时销毁弹层节点                          | boolean                                                      | false              |
| autoAdjustOverflow        | 自动调整方向避免溢出                        | boolean                                                      | true               |
| align                     | floating-ui 微调对象                        | object                                                       | —                  |
| offset                    | 出现位置的偏移量                            | number                                                       | 4                  |
| raw-content               | 是否将 content 作为 HTML 字符串处理         | boolean                                                      | false              |
| enterable                 | 鼠标是否可进入到 popover 中                 | boolean                                                      | true               |
| hide-on-click-outside     | 是否在点击外部时隐藏                        | boolean                                                      | true               |
| close-on-esc              | 是否支持 ESC 键关闭                         | boolean                                                      | true               |
| aria-label                | 屏幕阅读器标签                              | string                                                       | —                  |
| width                     | 弹层宽度                                    | `number \| string`                                           | —                  |
| transition                | 定义渐变动画                                | string                                                       | ccui-popover-fade  |
| auto-close                | 自动关闭时间，单位毫秒                      | number                                                       | 0                  |
| tabindex                  | Popover 组件的 tabindex                     | `number \| string`                                           | 0                  |
| teleported                | 是否 Teleport 到 body                       | boolean                                                      | true               |
| persistent                | 是否持久化                                  | boolean                                                      | true               |
| virtual-triggering        | 是否启用虚拟触发器                          | boolean                                                      | false              |
| virtual-ref               | 虚拟触发器的参照元素                        | HTMLElement                                                  | —                  |
| trigger-keys              | 键盘触发按键                                | string[]                                                     | ['Enter', 'Space'] |

### Popover Events

| 事件名         | 说明                 | 回调参数 |
| -------------- | -------------------- | -------- |
| before-show    | 显示前触发           | —        |
| show           | 显示时触发           | —        |
| before-hide    | 隐藏前触发           | —        |
| hide           | 隐藏时触发           | —        |
| update:visible | v-model:visible 同步 | visible  |
| before-enter   | 显示动画播放前触发   | —        |
| after-enter    | 显示动画播放后触发   | —        |
| before-leave   | 隐藏动画播放前触发   | —        |
| after-leave    | 隐藏动画播放后触发   | —        |

### Popover Slots

| 插槽名  | 说明                      |
| ------- | ------------------------- |
| default | Popover 触发 & 引用的元素 |
| title   | 自定义标题                |
| content | 自定义内容                |

### Popover Exposes

| 方法名 | 说明       | 类型       |
| ------ | ---------- | ---------- |
| hide   | 隐藏弹出框 | () => void |


---

# Progress 进度条

> 文档链接：https://vaebe.github.io/ccui/components/progress/index.html

可视化操作的完成度。

## 何时使用

- 操作耗时 ≥ 2 秒，需向用户反馈进度。
- 文件上传 / 下载 / 后台任务的实时进度。
- 数据填充率、目标完成率等"百分比"指标。

## 基本使用

线形进度条，`percent` 取值 0–100。

:::demo

```vue
<template>
  <c-progress :percent="30" />
  <c-progress :percent="50" />
  <c-progress :percent="100" />
</template>
```

:::

## 不同状态

`status` 决定进度条颜色与图标：`normal` / `active`（带流光动画）/ `success` / `exception`。

:::demo

```vue
<template>
  <c-progress :percent="30" status="normal" />
  <c-progress :percent="50" status="active" />
  <c-progress :percent="70" status="exception" />
  <c-progress :percent="100" status="success" />
</template>
```

:::

## 自定义颜色

`stroke-color` 改进度条主色，`trail-color` 改未完成部分的灰底色。

:::demo

```vue
<template>
  <c-progress :percent="60" stroke-color="#52c41a" />
  <c-progress :percent="60" stroke-color="#fa541c" />
  <c-progress :percent="60" stroke-color="#722ed1" trail-color="#f0e6ff" />
</template>
```

:::

## 自定义文案

`format` 接收百分比，返回任意字符串，常用于"已完成 / 总数"展示。

:::demo

```vue
<template>
  <c-progress :percent="50" :format="(p) => `${p} / 100`" />
  <c-progress :percent="80" :format="(p) => `进度 ${p}%`" />
  <c-progress :percent="100">
    <template #format>已完成 <c-icon name="mdi:check" /></template>
  </c-progress>
</template>
```

:::

## 圆形

`type="circle"` 渲染为圆环；`width` 控制画布大小。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px; flex-wrap: wrap">
    <c-progress type="circle" :percent="75" />
    <c-progress type="circle" :percent="70" status="exception" />
    <c-progress type="circle" :percent="100" />
    <c-progress type="circle" :percent="50" :width="80" />
  </div>
</template>
```

:::

## 仪表盘

`type="dashboard"` 是底部留缺口的圆形，常见于"剩余配额 / 容量占用"。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px">
    <c-progress type="dashboard" :percent="60" />
    <c-progress type="dashboard" :percent="80" status="active" />
    <c-progress type="dashboard" :percent="92" status="exception" :format="(p) => `${p}%\n紧张`" />
  </div>
</template>
```

:::

## 动态进度

配合 `setInterval` 模拟一个上传进度。

:::demo

```vue
<script setup>
import { ref, onBeforeUnmount } from 'vue'

const percent = ref(0)
let timer = null

function start() {
  stop()
  percent.value = 0
  timer = setInterval(() => {
    percent.value = Math.min(100, percent.value + Math.round(Math.random() * 12))
    if (percent.value >= 100) {
      stop()
    }
  }, 400)
}

function stop() {
  if (timer) {
    clearInterval(timer)
    timer = null
  }
}

onBeforeUnmount(stop)
</script>

<template>
  <c-progress :percent="percent" status="active" />
  <div style="margin-top: 12px">
    <c-button type="primary" @click="start">开始</c-button>
    <c-button style="margin-inline-start: 8px" @click="stop">暂停</c-button>
  </div>
</template>
```

:::

## 不同尺寸

`size` 支持 `'small' | 'default' | number | [number, number]` 四种形式。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-progress :percent="60" size="small" />
    <span style="color: var(--ccui-color-text-tertiary); font-size: 12px">size="small"</span>
  </div>
  <div style="margin-bottom: 12px">
    <c-progress :percent="60" />
    <span style="color: var(--ccui-color-text-tertiary); font-size: 12px">size="default"</span>
  </div>
  <div style="margin-bottom: 12px">
    <c-progress :percent="60" :size="16" />
    <span style="color: var(--ccui-color-text-tertiary); font-size: 12px">:size="16"（线宽 16px）</span>
  </div>
  <div>
    <c-progress :percent="60" :size="[240, 12]" />
    <span style="color: var(--ccui-color-text-tertiary); font-size: 12px">:size="[240, 12]"（宽 240 高 12）</span>
  </div>
</template>
```

:::

## 隐藏百分比数字

`show-info="false"` 关闭右侧 / 中心的数字，常用于「占位条」或紧凑列表。

:::demo

```vue
<template>
  <c-progress :percent="40" :show-info="false" />
  <c-progress :percent="80" :show-info="false" stroke-color="#52c41a" />
  <div style="display: flex; gap: 16px; margin-top: 16px">
    <c-progress type="circle" :percent="70" :show-info="false" :width="60" />
    <c-progress type="dashboard" :percent="50" :show-info="false" :width="60" />
  </div>
</template>
```

:::

## 自定义线宽

`stroke-width` 改进度条线宽（line：高度 px；circle / dashboard：描边粗细）。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-progress :percent="50" :stroke-width="4" />
  </div>
  <div style="margin-bottom: 12px">
    <c-progress :percent="50" :stroke-width="8" />
  </div>
  <div style="margin-bottom: 12px">
    <c-progress :percent="50" :stroke-width="16" />
  </div>
  <div style="display: flex; gap: 16px">
    <c-progress type="circle" :percent="75" :stroke-width="4" />
    <c-progress type="circle" :percent="75" :stroke-width="10" />
    <c-progress type="circle" :percent="75" :stroke-width="16" />
  </div>
</template>
```

:::

## 圆形不同尺寸

`width` 改圆形 / 仪表盘的画布尺寸（px），适合卡片中不同大小的指标圈。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px; align-items: center; flex-wrap: wrap">
    <c-progress type="circle" :percent="60" :width="48" />
    <c-progress type="circle" :percent="60" :width="80" />
    <c-progress type="circle" :percent="60" :width="120" />
    <c-progress type="circle" :percent="60" :width="180" />
  </div>
</template>
```

:::

## 渐变色（line-gradient）

`stroke-color` 接受 CSS `linear-gradient` 字符串，实现渐变填充。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-progress :percent="70" stroke-color="linear-gradient(90deg, #108ee9, #87d068)" />
  </div>
  <div style="margin-bottom: 12px">
    <c-progress :percent="85" stroke-color="linear-gradient(90deg, #faad14, #fa541c)" />
  </div>
  <div>
    <c-progress :percent="100" stroke-color="linear-gradient(90deg, #722ed1, #eb2f96, #fa541c)" />
  </div>
</template>
```

:::

## 步骤式进度（多段）

通过多个 `<c-progress>` 实现「步骤完成度」展示，每段代表一个步骤。

:::demo

```vue
<script setup>
import { ref, computed } from 'vue'
const step = ref(2)
const steps = ['创建', '审核', '部署', '验收']
const segPercents = computed(() => steps.map((_, i) => (i < step.value ? 100 : i === step.value ? 50 : 0)))
</script>

<template>
  <div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; margin-bottom: 12px">
    <div v-for="(p, i) in segPercents" :key="i">
      <div style="font-size: 12px; color: var(--ccui-color-text-secondary); margin-bottom: 4px">{{ steps[i] }}</div>
      <c-progress :percent="p" :show-info="false" size="small" :stroke-color="i < step ? '#52c41a' : '#1677ff'" />
    </div>
  </div>
  <c-button @click="step = Math.max(0, step - 1)">上一步</c-button>
  <c-button style="margin-inline-start: 8px" type="primary" @click="step = Math.min(4, step + 1)">下一步</c-button>
</template>
```

:::

## 失败 + 重试

`status="exception"` 显示失败态，业务侧改 percent 与 status 切回 `active` 即可重试。

:::demo

```vue
<script setup>
import { ref, onBeforeUnmount } from 'vue'
const percent = ref(45)
const status = ref('exception')
let timer = null

function retry() {
  if (timer) clearInterval(timer)
  status.value = 'active'
  timer = setInterval(() => {
    percent.value = Math.min(100, percent.value + 5)
    if (percent.value >= 100) {
      status.value = 'success'
      clearInterval(timer)
      timer = null
    }
  }, 300)
}

function fail() {
  if (timer) clearInterval(timer)
  status.value = 'exception'
}

onBeforeUnmount(() => timer && clearInterval(timer))
</script>

<template>
  <c-progress :percent="percent" :status="status" />
  <div style="margin-top: 12px">
    <c-button type="primary" @click="retry">重试</c-button>
    <c-button style="margin-inline-start: 8px" type="danger" @click="fail">模拟失败</c-button>
  </div>
</template>
```

:::

## 剩余时间提示（format 计算）

`format` 是普通函数，可结合外部状态计算 ETA。

:::demo

```vue
<script setup>
import { ref, onBeforeUnmount } from 'vue'
const percent = ref(0)
const startedAt = ref(0)
let timer = null

function start() {
  if (timer) clearInterval(timer)
  percent.value = 0
  startedAt.value = Date.now()
  timer = setInterval(() => {
    percent.value = Math.min(100, percent.value + 4)
    if (percent.value >= 100) {
      clearInterval(timer)
      timer = null
    }
  }, 500)
}

function fmt(p) {
  if (p === 0) return '准备中'
  if (p >= 100) return '完成'
  const elapsed = (Date.now() - startedAt.value) / 1000
  const remaining = (elapsed / p) * (100 - p)
  return `${p}% · 约剩 ${remaining.toFixed(0)}s`
}

onBeforeUnmount(() => timer && clearInterval(timer))
</script>

<template>
  <c-progress :percent="percent" :format="fmt" status="active" />
  <c-button style="margin-top: 12px" type="primary" @click="start">开始</c-button>
</template>
```

:::

## API

### Props

| 参数        | 类型                                                 | 默认值      | 说明                               |
| ----------- | ---------------------------------------------------- | ----------- | ---------------------------------- |
| percent     | number                                               | `0`         | 百分比 0–100                       |
| type        | `'line' \| 'circle' \| 'dashboard'`                  | `'line'`    | 形态                               |
| status      | `'normal' \| 'active' \| 'success' \| 'exception'`   | `'normal'`  | 状态                               |
| showInfo    | boolean                                              | `true`      | 显示百分比数字                     |
| strokeColor | string                                               | —           | 进度条颜色（不传走主色 token）     |
| trailColor  | string                                               | —           | 未完成段颜色                       |
| strokeWidth | number                                               | —           | 线宽（line: px；circle: 描边粗细） |
| width       | number                                               | `120`       | 圆形 / 仪表盘的画布尺寸（px）      |
| size        | `'default' \| 'small' \| number \| [number, number]` | `'default'` | 尺寸                               |
| format      | `(percent: number) => string`                        | —           | 自定义中心 / 后置文案              |


---

# Radio 单选框

> 文档链接：https://vaebe.github.io/ccui/components/radio/index.html

在多个备选项中选中一个。

## 何时使用

- 在一组备选项中选中单一选项。
- 与 `<c-radio-group>` 搭配，在多个 Radio 之间形成互斥关系。

## 基本使用

直接 `v-model` 到字符串，与每个 `<c-radio>` 的 `label` 比对决定选中状态。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref('apple')
</script>

<template>
  <c-radio v-model="value" label="apple">苹果</c-radio>
  <c-radio v-model="value" label="banana">香蕉</c-radio>
  <c-radio v-model="value" label="orange">橙子</c-radio>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前：{{ value }}</p>
</template>
```

:::

## 禁用

`disabled` 让单项不可选；常用于"权限不足 / 暂不开放"。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const value = ref('a')
</script>

<template>
  <c-radio v-model="value" label="a">可选 A</c-radio>
  <c-radio v-model="value" label="b" disabled>禁用 B</c-radio>
  <c-radio v-model="value" label="c">可选 C</c-radio>
</template>
```

:::

## 单选框组

`<c-radio-group>` 把一组 Radio 收纳到统一的 `v-model` 下，免去给每个 Radio 单独绑值。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const city = ref('shanghai')
</script>

<template>
  <c-radio-group v-model="city">
    <c-radio label="beijing">北京</c-radio>
    <c-radio label="shanghai">上海</c-radio>
    <c-radio label="guangzhou">广州</c-radio>
    <c-radio label="shenzhen">深圳</c-radio>
  </c-radio-group>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">已选：{{ city }}</p>
</template>
```

:::

## 排列方向

`direction` 切换纵向（默认）/ 横向。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const a = ref('1')
const b = ref('1')
</script>

<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 4px">column（默认）</p>
  <c-radio-group v-model="a" direction="column">
    <c-radio label="1">选项 1</c-radio>
    <c-radio label="2">选项 2</c-radio>
    <c-radio label="3">选项 3</c-radio>
  </c-radio-group>

  <p style="color: var(--ccui-color-text-secondary); margin: 16px 0 4px">row</p>
  <c-radio-group v-model="b" direction="row">
    <c-radio label="1">选项 1</c-radio>
    <c-radio label="2">选项 2</c-radio>
    <c-radio label="3">选项 3</c-radio>
  </c-radio-group>
</template>
```

:::

## 整组禁用

在 `<c-radio-group>` 上加 `disabled` 一次性禁用整组。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('1')
</script>

<template>
  <c-radio-group v-model="v" disabled direction="row">
    <c-radio label="1">已选不可改</c-radio>
    <c-radio label="2">禁用</c-radio>
    <c-radio label="3">禁用</c-radio>
  </c-radio-group>
</template>
```

:::

## 切换前钩子

`before-change` 返回 `false` / `Promise<false>` 时阻止本次切换，常用于"二次确认"或"先做异步校验"。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('safe')
const log = ref('（无）')

function beforeChange(val) {
  log.value = `尝试切换到 "${val}"`
  if (val === 'danger') {
    log.value += ' → 已被钩子阻止'
    return false
  }
  return true
}
</script>

<template>
  <c-radio-group v-model="v" :before-change="beforeChange" direction="row">
    <c-radio label="safe">安全</c-radio>
    <c-radio label="warn">注意</c-radio>
    <c-radio label="danger">危险（被禁）</c-radio>
  </c-radio-group>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">日志：{{ log }}</p>
</template>
```

:::

## 监听 change

`change` 事件返回新值，用于联动其他状态。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('s')
const lastChange = ref('（无）')

function onChange(val) {
  lastChange.value = val
}
</script>

<template>
  <c-radio-group v-model="v" direction="row" @change="onChange">
    <c-radio label="s">小</c-radio>
    <c-radio label="m">中</c-radio>
    <c-radio label="l">大</c-radio>
  </c-radio-group>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近 change：{{ lastChange }}</p>
</template>
```

:::

## API

### Radio Props

| 参数         | 类型               | 默认值  | 说明                                                        |
| ------------ | ------------------ | ------- | ----------------------------------------------------------- |
| modelValue   | `string \| number` | —       | 必选，绑定值（与 `label` 比较决定是否选中），支持 `v-model` |
| label        | `string \| number` | `''`    | 必选，本项的值                                              |
| name         | string             | `''`    | 原生 `name` 属性                                            |
| disabled     | boolean            | `false` | 是否禁用                                                    |
| beforeChange | `BeforeChangeType` | —       | 切换前的钩子，返回 `false` 阻止切换                         |

### Radio Events

| 事件   | 回调签名          | 说明         |
| ------ | ----------------- | ------------ |
| change | `(value: string)` | 值改变时触发 |

### RadioGroup Props

| 参数         | 类型               | 默认值     | 说明                             |
| ------------ | ------------------ | ---------- | -------------------------------- |
| modelValue   | `string \| number` | —          | 必选，被选中的值，支持 `v-model` |
| disabled     | boolean            | `false`    | 整组禁用                         |
| direction    | `DirectionType`    | `'column'` | 排列方向（`row` / `column`）     |
| beforeChange | `BeforeChangeType` | —          | 切换前的钩子，返回 `false` 阻止  |

### RadioGroup Events

| 事件   | 回调签名          | 说明         |
| ------ | ----------------- | ------------ |
| change | `(value: string)` | 值改变时触发 |

### Slots

| 名称    | 说明           |
| ------- | -------------- |
| default | 单选框右侧文本 |

### 类型定义

```ts
type BeforeChangeType = (value: string) => boolean | Promise<boolean>
type DirectionType = 'row' | 'column'
```


---

# RangePicker 日期范围

> 文档链接：https://vaebe.github.io/ccui/components/range-picker/index.html

选择一段连续的日期区间。双面板显示当前月与下一月，起 / 止两次点击完成选择，hover 期间高亮预览区间。复用 DatePicker 同款 dayjs 工具层与 `valueFormat` 三档。

## 基本使用

`v-model` 是 `[start, end]` 数组，类型与 `valueFormat` 对应。两次点击日期完成选择。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" />
</template>
```

:::

## 显示已选区间

`modelValue` 同时支持 `[string, string]`、`[Date, Date]`、`[number, number]`，按 `format` 自动解析。

:::demo

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

const value = ref<[string, string] | null>(['2026-05-01', '2026-05-15'])
</script>

<template>
  <c-range-picker v-model="value" />
</template>
```

:::

## 自定义格式

`format` 控制输入框显示，`valueFormat` 决定 `v-model` 输出形态。

:::demo

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

const a = ref<[string, string] | null>(null)
const b = ref<[Date, Date] | null>(null)
const c = ref<[number, number] | null>(null)
</script>

<template>
  <c-range-picker v-model="a" format="YYYY/MM/DD" />
  <c-range-picker v-model="b" value-format="date" />
  <c-range-picker v-model="c" value-format="number" />
</template>
```

:::

## 自动调换

如果点击 end < start，组件会自动把两端调换，输出始终满足 `start <= end`。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" />
</template>
```

:::

## 禁用日期

`disabled-date(current: Dayjs) => boolean` 与 DatePicker 一致，对 start / end 都生效。

:::demo

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

const value = ref<[string, string] | null>(null)

function disabledDate(current: Dayjs) {
  return current.isBefore(dayjs().startOf('day'))
}
</script>

<template>
  <c-range-picker v-model="value" :disabled-date="disabledDate" />
</template>
```

:::

## 独立禁用起止侧

`disabledStartDate` / `disabledEndDate` 仅作用于对应侧（phase=start / phase=end），优先级高于通用 `disabledDate`；单侧未配置时回落到 `disabledDate`。先点起始切到 end 阶段后，结束侧的禁用样式才会出现。

:::demo

```vue
<script setup lang="ts">
import dayjs, { type Dayjs } from 'dayjs'
import { computed, ref } from 'vue'

const value = ref<[string, string] | null>(null)
const start = computed(() => value.value?.[0])

function disabledStartDate(current: Dayjs) {
  return current.isBefore(dayjs().startOf('day'))
}
function disabledEndDate(current: Dayjs) {
  if (!start.value) return false
  return current.isAfter(dayjs(start.value).add(14, 'day'))
}
</script>

<template>
  <c-range-picker v-model="value" :disabled-start-date="disabledStartDate" :disabled-end-date="disabledEndDate" />
</template>
```

:::

## 两端独立禁用 disabled

`disabled` 支持元组 `[boolean, boolean]`，分别锁两端 input。例如「开始日期可选 / 结束日期锁定」常见于编辑订单中的「下单时间不可改、退款时间待选」场景。锁定端：input 禁用、点击不打开面板。当两端都锁定时清除按钮自动隐藏。

:::demo

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

const value = ref<[string, string] | null>(['2026-05-09', '2026-05-15'])
</script>

<template>
  <c-range-picker v-model="value" :disabled="[true, false]" />
</template>
```

:::

## 两端独立允许为空 allowEmpty

`allowEmpty` 接 `[boolean, boolean]`，分别配置「开始日期可空 / 结束日期可空」。两端默认 `false`，需要全部选择后才能提交。设为 `[true, false]` 即可实现「开始日期可空 / 结束日期必填」之类的不对称需求。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" :allow-empty="[true, false]" />
</template>
```

:::

## 自定义分隔符与占位

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" :placeholder="['Check-in', 'Check-out']" separator="→" />
</template>
```

:::

## 三种尺寸

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" size="small" />
  <c-range-picker v-model="value" />
  <c-range-picker v-model="value" size="large" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive<{ vacation: [string, string] | null }>({ vacation: null })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { vacation: [{ required: true, message: '请选择假期' }] }
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="vacation" label="假期" prop="vacation">
      <c-range-picker v-model="form.vacation" />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()"> 校验 </c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" popup-append-to-body />
</template>
```

:::

## showTime 时间选择

`show-time` 为 `true` 或对象时启用时间选择，两侧面板各挂时分秒三列；点日期不立即提交，footer 出现「确定」按钮，起止齐全后可点。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-range-picker v-model="value" show-time />
  <p>当前值：{{ value }}</p>
</template>
```

:::

传对象可配置默认时刻与步进，未传 `defaultStartTime` / `defaultEndTime` 时默认 `00:00:00` / `23:59:59`。

:::demo

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

const value = ref<[string, string] | null>(null)
const showTime = {
  defaultStartTime: '2026-01-01 09:00:00',
  defaultEndTime: '2026-01-01 17:30:00',
  minuteStep: 15,
}
</script>

<template>
  <c-range-picker v-model="value" :show-time="showTime" />
</template>
```

:::

## presets 预设快捷项

`presets` 传入快捷项数组后，面板左侧出现 rail；空数组不渲染。每项 `value` 可为元组或返回元组的函数，非严格解析，`end < start` 时自动调换。

:::demo

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

const value = ref<[string, string] | null>(null)
const presets = [
  { label: '今天', value: () => [dayjs().format('YYYY-MM-DD'), dayjs().format('YYYY-MM-DD')] },
  { label: '最近 7 天', value: () => [dayjs().subtract(6, 'day').format('YYYY-MM-DD'), dayjs().format('YYYY-MM-DD')] },
  {
    label: '本周',
    value: () => [dayjs().startOf('week').format('YYYY-MM-DD'), dayjs().endOf('week').format('YYYY-MM-DD')],
  },
  {
    label: '本月',
    value: () => [dayjs().startOf('month').format('YYYY-MM-DD'), dayjs().endOf('month').format('YYYY-MM-DD')],
  },
]
</script>

<template>
  <c-range-picker v-model="value" :presets="presets" />
</template>
```

:::

与 `show-time` 共存时，点击预设仅写入 pending，可继续微调时间，最后通过「确定」提交。

:::demo

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

const value = ref<[string, string] | null>(null)
const presets = [{ label: '上次会议', value: ['2026-05-08 14:00:00', '2026-05-08 15:30:00'] }]
</script>

<template>
  <c-range-picker v-model="value" show-time :presets="presets" />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-range-picker v-model="value" :variant="variant" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref([])
</script>
```

:::

## API

### Props

| 参数              | 类型                                                       | 默认值                    | 说明                                                                                                                                                                                                 |
| ----------------- | ---------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| modelValue        | `[DateValue, DateValue] \| null`                           | --                        | 起止区间，支持 `v-model`                                                                                                                                                                             |
| format            | string                                                     | `YYYY-MM-DD`              | 输入框显示与字符串解析格式                                                                                                                                                                           |
| valueFormat       | `'string' \| 'date' \| 'number'`                           | `'string'`                | `v-model` 输出形态：按 format 字符串 / Date 实例 / 毫秒时间戳                                                                                                                                        |
| placeholder       | `[string, string]`                                         | `['开始日期','结束日期']` | 起止两端占位文案                                                                                                                                                                                     |
| separator         | string                                                     | `~`                       | 起止之间的分隔符                                                                                                                                                                                     |
| disabled          | `boolean \| [boolean, boolean]`                            | `false`                   | 是否禁用；元组形态分别锁两端 input。两端都锁定时 clear 自动隐藏                                                                                                                                      |
| allowEmpty        | `boolean \| [boolean, boolean]`                            | `false`                   | 是否允许该端为空；元组分别配置两端。两端都不允许时必须选完整范围才能 ok 提交                                                                                                                         |
| clearable         | boolean                                                    | `true`                    | 是否显示清除按钮                                                                                                                                                                                     |
| size              | `'small' \| 'default' \| 'large'`                          | `'default'`               | 输入框尺寸                                                                                                                                                                                           |
| status            | `'' \| 'error' \| 'warning' \| ...`                        | `''`                      | 校验状态；置于 `FormItem` 时自动继承                                                                                                                                                                 |
| disabledDate      | `(current: Dayjs) => boolean`                              | --                        | 不可选日期回调，对 start / end 都生效                                                                                                                                                                |
| disabledStartDate | `(current: Dayjs) => boolean`                              | --                        | 仅作用于起始侧（phase=start），优先级高于 `disabledDate`                                                                                                                                             |
| disabledEndDate   | `(current: Dayjs) => boolean`                              | --                        | 仅作用于结束侧（phase=end），优先级高于 `disabledDate`                                                                                                                                               |
| placement         | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`            | 浮层方位                                                                                                                                                                                             |
| popupClassName    | string                                                     | --                        | 浮层根元素自定义 class                                                                                                                                                                               |
| popupAppendToBody | boolean                                                    | `false`                   | 是否把浮层 Teleport 到 `document.body`                                                                                                                                                               |
| getPopupContainer | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                        | 自定义浮层挂载点                                                                                                                                                                                     |
| autoFocus         | boolean                                                    | `false`                   | 挂载后自动 focus 起始输入框                                                                                                                                                                          |
| inputReadOnly     | boolean                                                    | `true`                    | 输入框只读                                                                                                                                                                                           |
| transitionName    | string                                                     | `ccui-range-picker-fade`  | 浮层过渡名                                                                                                                                                                                           |
| weekStart         | `0 \| 1`                                                   | `0`                       | 周起始：`0` 周日开头，`1` 周一开头                                                                                                                                                                   |
| presets           | `RangePresetItem[]`                                        | `[]`                      | 左侧快捷项；每项 `{ label, value }`，`value` 可为元组或返回元组的函数；空数组不渲染 rail                                                                                                             |
| showTime          | `boolean \| RangeTimeShowConfig`                           | `false`                   | 启用时间选择；对象支持 `format` / `defaultStartTime` / `defaultEndTime` / `hourStep` / `minuteStep` / `secondStep` / `disabledHours` / `disabledMinutes` / `disabledSeconds` / `hideDisabledOptions` |

### Events

| 事件名            | 回调签名                                  | 触发时机                           |
| ----------------- | ----------------------------------------- | ---------------------------------- |
| update:modelValue | `(value: [DateValue, DateValue] \| null)` | 区间提交或清除时                   |
| change            | `(value, dateStrings: [string, string])`  | 区间提交或清除时（带格式化字符串） |
| open-change       | `(open: boolean)`                         | 浮层打开 / 关闭时                  |
| focus             | --                                        | 输入框聚焦                         |
| blur              | --                                        | 输入框失焦                         |

## 已知限制（未交付）

- **键盘导航**：方向键 / Enter 切换尚未实现。
- **响应式单面板**：移动端 PC 双面板会溢出，自动切单面板留给后续。


---

# Rate 评分

> 文档链接：https://vaebe.github.io/ccui/components/rate/index.html

等级评估。

## 何时使用

- 收集用户对某个对象的「满意度 / 喜爱度」反馈。
- 展示外部聚合评分（只读模式）。

## 基本使用

`v-model` 双向绑定数值（0 ~ `count`）；默认 5 颗星。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const value = ref(3)
</script>

<template>
  <c-rate v-model="value" />
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">当前：{{ value }} 星</span>
</template>
```

:::

## 只读模式

`read-only` 用于「展示」场景，无法交互。常见于商品列表、评论汇总。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const value = ref(3.5)
</script>

<template>
  <c-rate v-model="value" :read-only="true" :allow-half="true" />
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">{{ value }} 分</span>
</template>
```

:::

## 半选

`allow-half` 允许半颗星选中（0.5 步长），常用于精确评分。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const value = ref(2.5)
</script>

<template>
  <c-rate v-model="value" :allow-half="true" />
  <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">{{ value }}</span>
</template>
```

:::

## 自定义星数

`count` 改变总等级数，常见于「10 分制」打分。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const v5 = ref(3)
const v7 = ref(5)
const v10 = ref(8)
</script>

<template>
  <div style="margin-bottom: 12px">
    <c-rate v-model="v5" :count="5" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">5 分制：{{ v5 }}</span>
  </div>
  <div style="margin-bottom: 12px">
    <c-rate v-model="v7" :count="7" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">7 分制：{{ v7 }}</span>
  </div>
  <div>
    <c-rate v-model="v10" :count="10" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">10 分制：{{ v10 }}</span>
  </div>
</template>
```

:::

## 自定义颜色

`color` 字符串接 CSS 颜色值；可用主题预设关键字（blue / red / orange）或自定义十六进制。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const v1 = ref(4)
const v2 = ref(3)
const v3 = ref(5)
const v4 = ref(2)
</script>

<template>
  <div style="margin-bottom: 12px">
    <c-rate v-model="v1" color="#fadb14" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">金色（默认风）</span>
  </div>
  <div style="margin-bottom: 12px">
    <c-rate v-model="v2" color="#fa541c" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">橙红</span>
  </div>
  <div style="margin-bottom: 12px">
    <c-rate v-model="v3" color="#52c41a" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">绿（好评向）</span>
  </div>
  <div>
    <c-rate v-model="v4" color="#722ed1" />
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">紫（品牌向）</span>
  </div>
</template>
```

:::

## 自定义图标

`default` slot 接一个字符或 SVG 元素替换星星。常见用于「心形」「点赞」「字母评分」。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const heart = ref(3)
const letter = ref(2)
</script>

<template>
  <div style="margin-bottom: 12px">
    <c-rate v-model="heart" color="#eb2f96">❤</c-rate>
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">心形评分</span>
  </div>
  <div>
    <c-rate v-model="letter" color="#1677ff" :count="5">A</c-rate>
    <span style="margin-inline-start: 12px; color: var(--ccui-color-text-secondary)">字母分级</span>
  </div>
</template>
```

:::

## 评分描述（info slot）

`info` slot 接收作用域 `info`（当前选中值），可显示「差 / 一般 / 好 / 很好 / 极好」文案。

:::demo

```vue
<script setup>
import { ref, computed } from 'vue'
const value = ref(3)
const desc = ['极差', '差', '一般', '好', '极好']
const text = computed(() => (value.value > 0 ? desc[value.value - 1] : '请评分'))
</script>

<template>
  <c-rate v-model="value">
    <template #info="info">
      <span style="margin-inline-start: 12px; color: var(--ccui-color-text-tertiary)">{{ info }} / 5</span>
    </template>
  </c-rate>
  <div style="margin-top: 8px; font-size: 13px; color: var(--ccui-color-text-secondary)">{{ text }}</div>
</template>
```

:::

## change 事件

`@change` 在评分改变时触发，回调参数为新值；用于联动日志、表单校验等。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const value = ref(0)
const log = ref([])

function onChange(v) {
  log.value.unshift(`${new Date().toLocaleTimeString()}  改为 ${v} 星`)
  if (log.value.length > 5) log.value.length = 5
}
</script>

<template>
  <c-rate v-model="value" @change="onChange" />
  <ul style="margin-top: 8px; color: var(--ccui-color-text-secondary); font-size: 12px">
    <li v-for="l in log" :key="l">{{ l }}</li>
  </ul>
</template>
```

:::

## 清零按钮

配合外部按钮把绑定值重置为 0；典型「重新评分」交互。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const value = ref(4)
</script>

<template>
  <c-rate v-model="value" :allow-half="true" />
  <c-button style="margin-inline-start: 12px" @click="value = 0">清零</c-button>
  <c-button style="margin-inline-start: 8px" type="primary" @click="value = 5">满分</c-button>
</template>
```

:::

## 在表单中使用

评分通常作为表单字段；与 `<c-form>` 协议无差异。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const form = ref({ score: 0, comment: '' })

function submit() {
  alert(`评分：${form.value.score}，评论：${form.value.comment}`)
}
</script>

<template>
  <c-form :model="form" label-width="80px" style="max-width: 480px">
    <c-form-item label="评分" name="score">
      <c-rate v-model="form.score" :allow-half="true" />
    </c-form-item>
    <c-form-item label="评论" name="comment">
      <c-input v-model="form.comment" placeholder="说点什么吧（可选）" />
    </c-form-item>
    <c-form-item>
      <c-button type="primary" :disabled="form.score === 0" @click="submit">提交</c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 只读 + 聚合分数（商品页常见）

多条评分汇总展示，配合主图标说明评分含义。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const overall = ref(4.5)
const desc = ref(4)
const speed = ref(5)
const service = ref(4.5)
</script>

<template>
  <div style="display: grid; gap: 8px; max-width: 360px">
    <div style="display: flex; align-items: center">
      <span style="width: 80px; color: var(--ccui-color-text-secondary)">综合：</span>
      <c-rate v-model="overall" :read-only="true" :allow-half="true" />
      <span style="margin-inline-start: 12px; color: #faad14; font-weight: 600">{{ overall }}</span>
    </div>
    <div style="display: flex; align-items: center">
      <span style="width: 80px; color: var(--ccui-color-text-secondary)">描述：</span>
      <c-rate v-model="desc" :read-only="true" />
      <span style="margin-inline-start: 12px; color: #faad14">{{ desc }}</span>
    </div>
    <div style="display: flex; align-items: center">
      <span style="width: 80px; color: var(--ccui-color-text-secondary)">物流：</span>
      <c-rate v-model="speed" :read-only="true" />
      <span style="margin-inline-start: 12px; color: #faad14">{{ speed }}</span>
    </div>
    <div style="display: flex; align-items: center">
      <span style="width: 80px; color: var(--ccui-color-text-secondary)">服务：</span>
      <c-rate v-model="service" :read-only="true" :allow-half="true" />
      <span style="margin-inline-start: 12px; color: #faad14">{{ service }}</span>
    </div>
  </div>
</template>
```

:::

## API

### Props

| 参数       | 类型      | 默认值  | 说明                       |
| ---------- | --------- | ------- | -------------------------- |
| v-model    | `number`  | `0`     | 评分绑定的值               |
| read-only  | `boolean` | `false` | 只读模式，无法交互         |
| count      | `number`  | `5`     | 总等级数                   |
| color      | `string`  | —       | 选中颜色（CSS 颜色字符串） |
| allow-half | `boolean` | `false` | 是否允许半选（0.5 步长）   |

### 事件

| 事件   | 回调参数          | 说明           |
| ------ | ----------------- | -------------- |
| change | `(value: number)` | 分值改变时触发 |

### 插槽

| 插槽    | 作用域  | 说明                                             |
| ------- | ------- | ------------------------------------------------ |
| default | —       | 替代默认星形 icon（接受字符串 / SVG / 单字符等） |
| info    | `value` | 评分右侧自定义描述区域，作用域为当前选中值       |


---

# Result 结果

> 文档链接：https://vaebe.github.io/ccui/components/result/index.html

为重要操作给出明确的最终反馈页（成功 / 失败 / 警告 / 找不到）。

## 何时使用

- 用户完成一个表单 / 交易 / 创建流程后展示总结。
- 路由命中"未授权 / 找不到 / 服务异常"时渲染语义化页面。

## 基本使用

最简形式：`status` + `title` + `sub-title`。`#extra` slot 放主操作按钮。

:::demo

```vue
<template>
  <c-result status="success" title="操作成功！" sub-title="订单 #2025-04-001 已提交，结果将于三天内反馈。">
    <template #extra>
      <c-button type="primary">查看订单</c-button>
      <c-button style="margin-inline-start: 8px">返回首页</c-button>
    </template>
  </c-result>
</template>
```

:::

## 不同状态

`status` 决定图标与色彩：`success` / `error` / `warning` / `info`。

:::demo

```vue
<template>
  <c-result status="error" title="提交失败" sub-title="请核对并修改下面的信息后重试。" />
  <c-result status="warning" title="磁盘容量已超 90%" sub-title="请在系统繁忙之前清理或扩容。" />
  <c-result status="info" title="操作已执行" sub-title="可能需要 1-2 分钟才能在控制台看到结果。" />
</template>
```

:::

## HTTP 错误页

`status="404"` / `'403'` / `'500'` 自带专门的 HTTP 错误插画。

:::demo

```vue
<template>
  <c-result status="404" title="404" sub-title="抱歉，您访问的页面不存在。">
    <template #extra>
      <c-button type="primary">返回首页</c-button>
    </template>
  </c-result>
</template>
```

:::

:::demo

```vue
<template>
  <c-result status="403" title="403" sub-title="抱歉，您无权访问该页面。" />
</template>
```

:::

:::demo

```vue
<template>
  <c-result status="500" title="500" sub-title="抱歉，服务器出错了。">
    <template #extra>
      <c-button type="primary">刷新页面</c-button>
    </template>
  </c-result>
</template>
```

:::

## 自定义图标

用 `#icon` slot 覆盖默认插画，常用于业务自定义视觉。

:::demo

```vue
<template>
  <c-result title="审核通过" sub-title="资质审核已完成，可以开始发布。">
    <template #icon>
      <div
        style="
          width: 80px;
          height: 80px;
          margin: 0 auto;
          border-radius: 50%;
          background: linear-gradient(135deg, #52c41a 0%, #95de64 100%);
          color: white;
          font-size: 40px;
          display: flex;
          align-items: center;
          justify-content: center;
        "
      >
        <c-icon name="mdi:check" />
      </div>
    </template>
    <template #extra>
      <c-button type="primary">前往发布</c-button>
    </template>
  </c-result>
</template>
```

:::

## 携带详细内容

默认插槽展示在副标题下方，常用于"成功后展示订单详情 / 失败后列出错误项"。

:::demo

```vue
<template>
  <c-result status="error" title="提交失败" sub-title="请处理以下问题后重新提交。">
    <ul style="margin: 0; padding-left: 20px; color: var(--ccui-color-text-secondary)">
      <li>用户名不能为空</li>
      <li>身份证号格式错误</li>
      <li>地址必须填写省 / 市 / 区</li>
    </ul>
    <template #extra>
      <c-button type="primary">返回修改</c-button>
    </template>
  </c-result>
</template>
```

:::

## 极简版（仅标题）

不传 `sub-title` / `#extra` 时，只展示状态图标 + 标题，适合卡片内嵌空状态。

:::demo

```vue
<template>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px">
    <div style="border: 1px solid var(--ccui-color-border-secondary); border-radius: 8px; padding: 16px">
      <c-result status="success" title="已激活" />
    </div>
    <div style="border: 1px solid var(--ccui-color-border-secondary); border-radius: 8px; padding: 16px">
      <c-result status="info" title="等待审核" />
    </div>
  </div>
</template>
```

:::

## 注册成功 + 倒计时跳转

业务常见：成功页 N 秒后自动跳转，期间用户可点击「立即跳转」。

:::demo

```vue
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'

const seconds = ref(5)
let timer = null

function reset() {
  if (timer) clearInterval(timer)
  seconds.value = 5
  timer = setInterval(() => {
    seconds.value -= 1
    if (seconds.value <= 0) {
      clearInterval(timer)
      timer = null
    }
  }, 1000)
}

function goNow() {
  if (timer) clearInterval(timer)
  alert('跳转到工作台')
}

onMounted(reset)
onBeforeUnmount(() => timer && clearInterval(timer))
</script>

<template>
  <c-result
    status="success"
    title="注册成功"
    :sub-title="seconds > 0 ? `将于 ${seconds} 秒后自动跳转到工作台...` : '已跳转'"
  >
    <template #extra>
      <c-button type="primary" @click="goNow">立即跳转</c-button>
      <c-button style="margin-inline-start: 8px" @click="reset">重置倒计时</c-button>
    </template>
  </c-result>
</template>
```

:::

## 网络错误（带重试计数）

异步加载失败页，配合重试按钮 + 计数追踪连续失败次数。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const tries = ref(0)

function retry() {
  tries.value += 1
}
</script>

<template>
  <c-result status="error" title="网络异常" :sub-title="`连接超时，请检查网络后重试（已尝试 ${tries} 次）`">
    <template #extra>
      <c-button type="primary" @click="retry">重试</c-button>
      <c-button style="margin-inline-start: 8px">检查网络</c-button>
    </template>
  </c-result>
</template>
```

:::

## 权限不足（申请权限）

403 状态 + 申请权限按钮，是后台常见交互。

:::demo

```vue
<template>
  <c-result status="403" title="403" sub-title="抱歉，您的账号没有访问该页面的权限。">
    <template #extra>
      <c-button type="primary">申请权限</c-button>
      <c-button style="margin-inline-start: 8px">返回首页</c-button>
    </template>
  </c-result>
</template>
```

:::

## 自定义 SVG 图标

`#icon` slot 支持任意 VNode 内容（SVG / Iconify / 图片皆可）。

:::demo

```vue
<template>
  <c-result title="云端同步完成" sub-title="所有文件已上传至云端，可在任意设备访问。">
    <template #icon>
      <svg width="80" height="80" viewBox="0 0 80 80" style="display: block; margin: 0 auto">
        <circle cx="40" cy="40" r="36" fill="#e6f4ff" stroke="#1677ff" stroke-width="2" />
        <path
          d="M 26 40 L 35 50 L 56 28"
          stroke="#1677ff"
          stroke-width="4"
          stroke-linecap="round"
          stroke-linejoin="round"
          fill="none"
        />
      </svg>
    </template>
    <template #extra>
      <c-button type="primary">打开文件夹</c-button>
    </template>
  </c-result>
</template>
```

:::

## 在 Modal 中使用

成功提示作为 Modal 内容，配合 `closable=false` 强制走主操作按钮。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const open = ref(false)
</script>

<template>
  <c-button type="primary" @click="open = true">完成订单</c-button>
  <c-modal v-model:visible="open" :footer="null" :width="520" :closable="false">
    <c-result status="success" title="支付成功" sub-title="您的订单已生成，预计 3 个工作日内发货。">
      <template #extra>
        <c-button type="primary" @click="open = false">查看订单</c-button>
        <c-button style="margin-inline-start: 8px" @click="open = false">关闭</c-button>
      </template>
    </c-result>
  </c-modal>
</template>
```

:::

## 多按钮组合

`#extra` 可以放多个按钮，按业务优先级排列。

:::demo

```vue
<template>
  <c-result status="success" title="部署完成" sub-title="新版本 v2.1.0 已成功上线生产环境。">
    <template #extra>
      <c-button type="primary">查看监控</c-button>
      <c-button style="margin-inline-start: 8px">查看日志</c-button>
      <c-button style="margin-inline-start: 8px">回滚版本</c-button>
      <c-button type="danger" style="margin-inline-start: 8px">紧急停止</c-button>
    </template>
  </c-result>
</template>
```

:::

## API

### Props

| 参数     | 类型                                                                     | 默认值   | 说明           |
| -------- | ------------------------------------------------------------------------ | -------- | -------------- |
| status   | `'success' \| 'error' \| 'info' \| 'warning' \| '404' \| '403' \| '500'` | `'info'` | 状态           |
| title    | string                                                                   | —        | 主标题         |
| subTitle | string                                                                   | —        | 副标题         |
| icon     | string                                                                   | —        | 自定义图标类名 |

### Slots

| 名称    | 说明               |
| ------- | ------------------ |
| icon    | 自定义图标         |
| extra   | 自定义底部按钮区域 |
| default | 副标题下方的内容   |


---

# Segmented 分段控制器

> 文档链接：https://vaebe.github.io/ccui/components/segmented/index.html

在两个或多个互斥选项之间切换，比 Radio 更紧凑。

## 何时使用

- 视图切换（日 / 周 / 月）。
- 在多种相同类型的视图 / 数据集间切换。

## 基本使用

`options` 是字符串 / 数字数组，`v-model` 绑定当前选中值。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('Daily')
</script>

<template>
  <c-segmented v-model="v" :options="['Daily', 'Weekly', 'Monthly', 'Quarterly', 'Yearly']" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前：{{ v }}</p>
</template>
```

:::

## 用对象选项

`options` 元素也可以是 `{ label, value, disabled, icon }`。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('list')
</script>

<template>
  <c-segmented
    v-model="v"
    :options="[
      { label: '列表', value: 'list' },
      { label: '看板', value: 'kanban' },
      { label: '日历', value: 'calendar', disabled: true },
    ]"
  />
</template>
```

:::

## 不同尺寸

`size`：`small` / `middle`（默认）/ `large`。

:::demo

```vue
<template>
  <c-segmented size="small" :options="['Daily', 'Weekly', 'Monthly']" model-value="Daily" />
  <br /><br />
  <c-segmented :options="['Daily', 'Weekly', 'Monthly']" model-value="Daily" />
  <br /><br />
  <c-segmented size="large" :options="['Daily', 'Weekly', 'Monthly']" model-value="Daily" />
</template>
```

:::

## 块级宽度

`block` 让组件横向占满父容器。

:::demo

```vue
<template>
  <c-segmented block :options="['Map', 'Transit', 'Satellite']" model-value="Map" />
</template>
```

:::

## 禁用整组

`disabled` 让所有选项不可点。

:::demo

```vue
<template>
  <c-segmented disabled :options="['Map', 'Transit', 'Satellite']" model-value="Map" />
</template>
```

:::

## 监听变化

`change` 事件返回新值，可联动其他组件。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const v = ref('all')
const log = ref('（无）')

function onChange(val) {
  log.value = val
}
</script>

<template>
  <c-segmented v-model="v" :options="['all', 'todo', 'done']" @change="onChange" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">最近 change：{{ log }}</p>
</template>
```

:::

## 数字 value

`options` 元素是数字时，`v-model` 也按数字类型回传，适合评分 / 年龄段 / 分页大小等枚举数值。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const pageSize = ref(20)
</script>

<template>
  <c-segmented v-model="pageSize" :options="[10, 20, 50, 100]" />
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">每页 {{ pageSize }} 条（typeof = {{ typeof pageSize }}）</p>
</template>
```

:::

## 带 icon 选项

`icon` 接 CSS class（与 Button 的 `icon` prop 同源），渲染在 label 文字前。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const view = ref('list')
</script>

<template>
  <c-segmented
    v-model="view"
    :options="[
      { label: '列表', value: 'list', icon: 'icon-menu' },
      { label: '看板', value: 'kanban', icon: 'icon-grid' },
      { label: '日历', value: 'calendar', icon: 'icon-calendar' },
    ]"
  />
</template>
```

:::

## 自定义渲染（default slot）

默认插槽接收 `{ option }` scope，可以完全接管单项的渲染——头像 + 文字 + 副标题等组合，适合用户切换 / 团队切换场景。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const member = ref('alice')

const members = [
  { value: 'alice', label: 'Alice', avatar: 'A', color: '#1677ff' },
  { value: 'bob', label: 'Bob', avatar: 'B', color: '#52c41a' },
  { value: 'carol', label: 'Carol', avatar: 'C', color: '#fa8c16' },
]
</script>

<template>
  <c-segmented v-model="member" :options="members">
    <template #default="{ option }">
      <div style="display: flex; align-items: center; gap: 6px; padding: 2px 4px">
        <span
          :style="{
            width: '20px',
            height: '20px',
            borderRadius: '50%',
            background: option.color,
            color: 'var(--ccui-color-text-light-solid)',
            fontSize: '12px',
            display: 'inline-flex',
            alignItems: 'center',
            justifyContent: 'center',
          }"
        >
          {{ option.avatar }}
        </span>
        <span>{{ option.label }}</span>
      </div>
    </template>
  </c-segmented>
</template>
```

:::

## 单项禁用

把禁用粒度下沉到 option：仅特定值不可点，其余可点。注意与整组 `disabled` 互不冲突。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const level = ref('basic')
</script>

<template>
  <c-segmented
    v-model="level"
    :options="[
      { label: '免费版', value: 'basic' },
      { label: '专业版', value: 'pro' },
      { label: '企业版（需联系销售）', value: 'enterprise', disabled: true },
    ]"
  />
</template>
```

:::

## 视图切换业务

最典型用法：切换视图模式联动主区域渲染逻辑。这里用文本占位代表实际的列表 / 看板 / 图表组件。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const view = ref('list')
</script>

<template>
  <c-segmented v-model="view" :options="['list', 'kanban', 'chart']" style="margin-bottom: 12px" />
  <div
    style="
      background: var(--ccui-area);
      border: 1px dashed var(--ccui-color-border);
      border-radius: 6px;
      padding: 24px;
      min-height: 80px;
      display: flex;
      align-items: center;
      justify-content: center;
      color: var(--ccui-color-text-secondary);
    "
  >
    <span v-if="view === 'list'">📋 列表视图占位</span>
    <span v-else-if="view === 'kanban'">🗂️ 看板视图占位</span>
    <span v-else>📊 图表视图占位</span>
  </div>
</template>
```

:::

## API

### Props

| 参数       | 类型                                      | 默认值     | 说明                   |
| ---------- | ----------------------------------------- | ---------- | ---------------------- |
| modelValue | `string \| number`                        | `''`       | 选中值，支持 `v-model` |
| options    | `(SegmentedOption \| string \| number)[]` | `[]`       | 选项列表               |
| block      | boolean                                   | `false`    | 撑满父容器             |
| disabled   | boolean                                   | `false`    | 整组禁用               |
| size       | `'small' \| 'middle' \| 'large'`          | `'middle'` | 尺寸                   |

### SegmentedOption

| 字段     | 类型               | 说明              |
| -------- | ------------------ | ----------------- |
| label    | string             | 显示文字          |
| value    | `string \| number` | 必填，选中值      |
| disabled | boolean            | 单项禁用          |
| icon     | string             | 自定义 icon class |

### Events

| 事件名 | 回调签名                    | 说明       |
| ------ | --------------------------- | ---------- |
| change | `(value: string \| number)` | 切换时触发 |


---

# Select 选择器

> 文档链接：https://vaebe.github.io/ccui/components/select/index.html

从一组选项中选择一个或多个值，支持分组（含嵌套）、字段名映射、自定义渲染、远程搜索、tags、popup 定位、Teleport 容器、虚拟列表、完整 ARIA、键盘导航、labelInValue、maxCount、命中高亮和 FormItem 校验联动。

## 基本使用

:::demo

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

const value = ref('lucy')
const options = [
  { label: 'Jack', value: 'jack' },
  { label: 'Lucy', value: 'lucy' },
  { label: 'Disabled', value: 'disabled', disabled: true },
]
</script>

<template>
  <c-select v-model="value" :options="options" placeholder="请选择成员" />
</template>
```

:::

## 多选

`mode="multiple"`（或保留兼容的 `multiple`）。

:::demo

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

const value = ref(['jack'])
const options = [
  { label: 'Jack', value: 'jack' },
  { label: 'Lucy', value: 'lucy' },
  { label: 'Tom', value: 'tom' },
]
</script>

<template>
  <c-select v-model="value" mode="multiple" clearable :options="options" placeholder="请选择成员" />
</template>
```

:::

## Tags 模式（自由输入）

`mode="tags"` 允许用户在搜索框中按 Enter 创建未在列表中的新 tag。空白和重复值会被忽略。

:::demo

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

const value = ref<string[]>(['vue'])
const options = [
  { label: 'vue', value: 'vue' },
  { label: 'react', value: 'react' },
  { label: 'svelte', value: 'svelte' },
]
</script>

<template>
  <c-select v-model="value" mode="tags" filterable clearable :options="options" placeholder="按 Enter 添加新 tag" />
</template>
```

:::

## 可搜索 / 远程搜索

`filterable` 默认开启**前端**模糊匹配。设置 `filterOption=false` 关掉前端过滤，监听 `search` 事件做远程数据加载，配合 `loading` 控制加载态。

:::demo

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

const value = ref()
const options = ref<Array<{ label: string; value: string }>>([])
const loading = ref(false)

let timer: ReturnType<typeof setTimeout> | null = null
function onSearch(keyword: string) {
  if (timer) clearTimeout(timer)
  if (!keyword) {
    options.value = []
    return
  }
  loading.value = true
  timer = setTimeout(() => {
    options.value = ['Beijing', 'Shanghai', 'Shenzhen']
      .filter((city) => city.toLowerCase().includes(keyword.toLowerCase()))
      .map((label) => ({ label, value: label }))
    loading.value = false
  }, 300)
}
</script>

<template>
  <c-select
    v-model="value"
    filterable
    clearable
    :options="options"
    :filter-option="false"
    :loading="loading"
    placeholder="输入城市..."
    @search="onSearch"
  />
</template>
```

:::

也可以传函数自定义匹配逻辑：

```vue
<c-select
  v-model="value"
  filterable
  :options="options"
  :filter-option="(input, option) => option.label.startsWith(input)"
/>
```

## 选项分组

在 `options` 里写 group 节点（含 `options` 数组）即可。同样支持搜索时按 group 折叠空组。

:::demo

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

const value = ref()
const options = [
  {
    label: '前端',
    options: [
      { label: 'Vue', value: 'vue' },
      { label: 'React', value: 'react' },
    ],
  },
  {
    label: '后端',
    options: [
      { label: 'Go', value: 'go' },
      { label: 'Rust', value: 'rust' },
    ],
  },
]
</script>

<template>
  <c-select v-model="value" :options="options" placeholder="选择技术栈" />
</template>
```

:::

## fieldNames 字段名映射

列表数据字段不叫 `label`/`value` 时用 `fieldNames` 映射：

:::demo

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

const value = ref()
const data = [
  {
    name: '水果',
    items: [
      { name: 'Apple', id: 1 },
      { name: 'Banana', id: 2 },
      { name: 'Cherry', id: 3, locked: true },
    ],
  },
]
</script>

<template>
  <c-select
    v-model="value"
    :options="data"
    :field-names="{ label: 'name', value: 'id', disabled: 'locked', options: 'items' }"
    placeholder="选择水果"
  />
</template>
```

:::

## 自定义渲染（option / tag / empty）

通过插槽自定义下拉项、已选 tag、空状态。

:::demo

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

const value = ref(['jack'])
const options = [
  { label: 'Jack', value: 'jack', avatar: '🦊' },
  { label: 'Lucy', value: 'lucy', avatar: '🐱' },
  { label: 'Tom', value: 'tom', avatar: '🐶' },
]
</script>

<template>
  <c-select v-model="value" mode="multiple" clearable :options="options">
    <template #option="{ option, selected }">
      <span>{{ option.raw.avatar }} {{ option.label }}</span>
      <c-icon v-if="selected" name="mdi:check" style="margin-left: 8px;" />
    </template>
    <template #tag="{ option, onClose }">
      <span style="display: inline-flex; gap: 4px; padding: 0 8px; background: #e6f4ff; border-radius: 12px;">
        {{ option.raw.avatar }} {{ option.label }}
        <c-icon style="cursor: pointer;" name="mdi:close" @click.stop="onClose" />
      </span>
    </template>
    <template #empty>
      <div>没有匹配的人</div>
    </template>
  </c-select>
</template>
```

:::

## Popup 位置

`placement` 控制下拉位置（`bottom`/`top`/`auto`，基于 [@floating-ui](https://floating-ui.com/) 自动 flip）。`popupClassName` 给浮层挂自定义类。

```vue
<c-select v-model="value" :options="options" placement="top" popup-class-name="my-select-popup" />
```

## 虚拟列表（大数据量）

`virtualScroll` 启用后下拉框只渲染可视区域 + 缓冲区，能流畅承载几千上万条选项。`virtualItemHeight` 控制单项高度（默认 32px），`virtualMaxHeight` 控制下拉最大高度（默认 240px）。键盘 PageUp/PageDown/Home/End 自动滚到对应位置。

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

const value = ref()
const options = Array.from({ length: 5000 }, (_, i) => ({ label: `Option ${i}`, value: i }))
</script>

<template>
  <c-select
    v-model="value"
    filterable
    :options="options"
    virtual-scroll
    :virtual-item-height="32"
    :virtual-max-height="320"
  />
</template>
```

## 嵌套分组

`options` 数组里的 group 节点可以再嵌套 group：

```vue
<c-select
  :options="[
    {
      label: '前端',
      options: [
        {
          label: '框架',
          options: [
            { label: 'Vue', value: 'vue' },
            { label: 'React', value: 'react' },
          ],
        },
        {
          label: '工具链',
          options: [
            { label: 'Vite', value: 'vite' },
            { label: 'Webpack', value: 'webpack' },
          ],
        },
      ],
    },
  ]"
/>
```

## 命中高亮

`highlightMatch` 让 filterable 模式下命中的子串包在 `<mark class="ccui-select__highlight">` 里：

```vue
<c-select v-model="value" filterable highlight-match :options="options" />
```

## Teleport 浮层

默认浮层渲染在组件内部 DOM。需要把浮层挂到指定容器（避免被父级 `overflow:hidden` 截断）时：

```vue
<!-- 挂到 body -->
<c-select v-model="value" :options="options" popup-append-to-body />

<!-- 挂到自定义容器 -->
<c-select v-model="value" :options="options" :get-popup-container="() => myRef" />
```

## labelInValue 模式

默认 `modelValue` 只是 value。某些场景下需要同时拿到 label（比如展示已选项的额外字段、避免再去 options 里查找）。设置 `labelInValue` 后绑定值变成 `{ value, label }` 形态：

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

// 单选：{ value: 'jack', label: 'Jack' }
const single = ref()
// 多选：[{ value: 'jack', label: 'Jack' }, ...]
const multi = ref([])
</script>

<template>
  <c-select v-model="single" label-in-value :options="options" />
  <c-select v-model="multi" mode="multiple" label-in-value :options="options" />
</template>
```

## 选择数量上限

`maxCount` 限制 multiple / tags 模式下最多可选数：

```vue
<c-select v-model="value" mode="multiple" :max-count="3" :options="options" />
```

到达上限后再点选项或按 Enter 创建 tag 都不会触发 update。

## ARIA 与键盘导航

放在 `<c-form-item>` 里时自动注入校验上下文，同时本组件内置：

| 按键        | 行为                             |
| ----------- | -------------------------------- |
| Enter       | 打开下拉 / 选中当前项 / 创建 tag |
| Esc         | 关闭下拉                         |
| ↑ / ↓       | 上一项 / 下一项（跳过 disabled） |
| Home / End  | 首项 / 末项                      |
| PageUp/Down | 翻页                             |
| Backspace   | 多选 + 搜索为空时删最后一个 tag  |

ARIA 已挂：`role="combobox"` + `aria-expanded` + `aria-controls` + `aria-haspopup="listbox"` + `aria-activedescendant`，每个选项有独立 `id` + `role="option"` + `aria-selected` + `aria-disabled`。

## optionLabelProp 已选展示字段

下拉里的 label 通常较长（带说明、详情）。`optionLabelProp` 让单选 / 多选已选展示用另一个字段，下拉项里仍按 `label` 渲染：

```vue
<script setup lang="ts">
const data = [
  { label: 'Apple - red, sweet', value: 'apple', short: 'Apple' },
  { label: 'Banana - yellow, soft', value: 'banana', short: 'Banana' },
]
</script>

<template>
  <c-select :options="data" option-label-prop="short" />
</template>
```

字段缺失时回退到 `label`。

## showSearch 别名

`showSearch` 等价于 `filterable`，与其他社区库 API 对齐：

```vue
<c-select :options="options" show-search :filter-option="false" @search="onSearch" />
```

## 自定义浮层动画

通过 `transitionName` 设置 Vue Transition 名（默认 `ccui-select-fade`，淡入 + 4px 上滑）。给浮层换一个动画只需提供匹配的 CSS：

```vue
<c-select :options="options" transition-name="my-zoom" />
<style>
.my-zoom-enter-active,
.my-zoom-leave-active {
  transition:
    opacity 0.2s,
    transform 0.2s;
}
.my-zoom-enter-from,
.my-zoom-leave-to {
  opacity: 0;
  transform: scaleY(0.9);
}
</style>
```

## 拖拽排序已选 tag

`tagsDraggable` 启用后，多选 / tags 模式下用户可以拖拽 tag 调整顺序：

```vue
<c-select v-model="value" mode="multiple" tags-draggable :options="options" />
```

被拖中的 tag 会降透明，drop 目标会高亮边框，松开后 `update:modelValue` 直接给出新顺序。

## FormItem 联动

放在 `<c-form-item>` 里时自动注入校验上下文：

- `validateStatus` 改变会同步到 Select 的 error / warning 边框颜色
- `modelValue` 改变后自动 `validate('change')`
- 下拉关闭后自动 `validate('blur')`

也可以手动设置 `status="error" | "warning" | "success" | "validating"` 临时覆盖。

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-select v-model="value" :variant="variant" :options="opts" placeholder="切换 variant 观察样式" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
const opts = [
  { label: 'Alpha', value: 'alpha' },
  { label: 'Beta', value: 'beta' },
  { label: 'Gamma', value: 'gamma' },
]
</script>
```

:::

## Props

| 参数                     | 类型                                                  | 默认值             | 说明                                            |
| ------------------------ | ----------------------------------------------------- | ------------------ | ----------------------------------------------- |
| modelValue               | `string / number / array`                             | --                 | 绑定值                                          |
| options                  | `Array<SelectOption \| SelectGroupOption>`            | `[]`               | 选项列表，含 `options` 数组的节点视为分组       |
| fieldNames               | `{ label?, value?, disabled?, options? }`             | --                 | 字段名映射                                      |
| mode                     | `'default' / 'multiple' / 'tags'`                     | `'default'`        | 模式；`tags` 允许 Enter 输入新值                |
| multiple                 | `boolean`                                             | `false`            | 兼容旧 prop，等价于 `mode="multiple"`           |
| filterable               | `boolean`                                             | `false`            | 显示搜索框                                      |
| filterOption             | `boolean / (input, option) => boolean`                | `true`             | 过滤策略；`false` 走远程搜索；函数自定义谓词    |
| placement                | `'bottom' / 'top' / 'auto'`                           | `'bottom'`         | 浮层位置（基于 floating-ui，自动 flip / shift） |
| popupClassName           | `string`                                              | `''`               | 浮层附加类                                      |
| placeholder              | `string`                                              | --                 | 占位文本                                        |
| disabled                 | `boolean`                                             | `false`            | 是否禁用                                        |
| clearable                | `boolean`                                             | `false`            | 是否可清空                                      |
| loading                  | `boolean`                                             | `false`            | 加载中                                          |
| size                     | `'large' / 'default' / 'small'`                       | `'default'`        | 尺寸                                            |
| noDataText               | `string`                                              | `No data`          | 空状态文本                                      |
| loadingText              | `string`                                              | `Loading`          | 加载文本                                        |
| maxTagCount              | `number`                                              | `3`                | 多选最多直接展示的标签数                        |
| status                   | `'' / 'error' / 'warning' / 'success' / 'validating'` | `''`               | 显式校验状态，覆盖 FormItem 注入                |
| labelInValue             | `boolean`                                             | `false`            | 启用后 modelValue 变成 `{ value, label }` 形态  |
| autoFocus                | `boolean`                                             | `false`            | 挂载后自动聚焦                                  |
| defaultActiveFirstOption | `boolean`                                             | `true`             | 打开下拉时是否预选第一个非禁用项                |
| highlightMatch           | `boolean`                                             | `false`            | 搜索命中子串包 `<mark>`                         |
| maxCount                 | `number`                                              | `0`                | 多选/tags 最大可选数，0 表示不限                |
| getPopupContainer        | `(triggerNode) => HTMLElement \| null`                | --                 | 自定义浮层挂载点（自动 Teleport 到该容器）      |
| popupAppendToBody        | `boolean`                                             | `false`            | 等价于 `getPopupContainer: () => document.body` |
| virtualScroll            | `boolean`                                             | `false`            | 启用虚拟列表                                    |
| virtualItemHeight        | `number`                                              | `32`               | 虚拟列表单项高度（px）                          |
| virtualMaxHeight         | `number`                                              | `240`              | 虚拟列表最大可视高度（px）                      |
| optionLabelProp          | `string`                                              | --                 | 已选展示字段（不影响下拉项渲染和过滤）          |
| showSearch               | `boolean`                                             | `false`            | `filterable` 别名                               |
| transitionName           | `string`                                              | `ccui-select-fade` | 浮层 Vue Transition 名称                        |
| tagsDraggable            | `boolean`                                             | `false`            | 多选 / tags 模式下允许拖拽 tag 重排             |

## 事件

| 事件              | 回调签名              | 说明                          |
| ----------------- | --------------------- | ----------------------------- |
| update:modelValue | `(value)`             | 选中值变化                    |
| change            | `(value)`             | 选中值变化（与 v-model 同步） |
| search            | `(input: string)`     | 搜索文本变化                  |
| visible-change    | `(visible: boolean)`  | 下拉显示状态变化              |
| clear             | `()`                  | 点击清除按钮                  |
| focus             | `(event: FocusEvent)` | 根元素获得焦点                |
| blur              | `(event: FocusEvent)` | 根元素失去焦点                |

## 插槽

| 插槽     | 参数                   | 说明                             |
| -------- | ---------------------- | -------------------------------- |
| option   | `{ option, selected }` | 自定义下拉项内容                 |
| tag      | `{ option, onClose }`  | 自定义已选 tag（多选/tags 模式） |
| selected | `{ option }`           | 自定义单选选中态展示             |
| empty    | --                     | 自定义空状态                     |
| prefix   | --                     | 选择器左侧 prefix                |
| suffix   | --                     | 选择器右侧 suffix                |

## 类型

```ts
interface SelectOption {
  label?: unknown
  value?: string | number
  disabled?: boolean
  [key: string]: unknown
}

interface SelectGroupOption {
  label?: unknown
  options: SelectOption[]
  [key: string]: unknown
}

interface SelectFieldNames {
  label?: string
  value?: string
  disabled?: string
  options?: string
}

interface ResolvedSelectOption {
  raw: SelectOption // 原始数据
  label: unknown
  value: string | number
  disabled: boolean
  groupLabel?: unknown
}

type SelectFilterOption = boolean | ((input: string, option: SelectOption) => boolean)
```

## 解析与匹配优先级

- `mode` 优先于 `multiple`；`mode='tags'` 时 `filterable` 应同时开启以露出输入框。
- `filterOption=false` 完全跳过前端过滤；函数返回 `true` 即视为命中。
- `fieldNames` 不影响 `modelValue`：传入和回传仍然是 `value` 字段（按映射后的字段）的原始值。
- 注入到 FormItem 时 `status` 优先级高于 `formItem.validateStatus`。


---

# Skeleton 骨架屏

> 文档链接：https://vaebe.github.io/ccui/components/skeleton/index.html

在内容真正加载完成前先显示一个轮廓占位，缓解"白屏 + 跳动"的视觉割裂。

## 何时使用

- 网络较慢，加载需 1 秒以上。
- 图文混排的列表 / 详情页。
- 第一次加载数据时使用；后续刷新优先用 `loading` 状态。

## 基本使用

完全无参时显示一个标题 + 三段段落的默认占位。

:::demo

```vue
<template>
  <c-skeleton />
</template>
```

:::

## 带动画

`active` 开启微光扫描动画，提示"正在加载"。

:::demo

```vue
<template>
  <c-skeleton active />
</template>
```

:::

## 带头像

`avatar` 设为 `true` 显示左侧圆形占位；传对象可调形状与大小。

:::demo

```vue
<template>
  <c-skeleton avatar />
  <hr style="margin: 16px 0; border: 0; border-top: 1px dashed var(--ccui-color-border)" />
  <c-skeleton :avatar="{ shape: 'square', size: 'large' }" active />
</template>
```

:::

## 段落自定义

`paragraph` 传对象可改 `rows`（行数）和 `width`（宽度，可数组分别设每行宽）。

:::demo

```vue
<template>
  <c-skeleton :paragraph="{ rows: 4 }" />
  <hr style="margin: 16px 0; border: 0; border-top: 1px dashed var(--ccui-color-border)" />
  <c-skeleton :paragraph="{ rows: 3, width: ['80%', '95%', '60%'] }" active />
</template>
```

:::

## 标题自定义

`title` 传对象可控制宽度。

:::demo

```vue
<template>
  <c-skeleton :title="{ width: 240 }" :paragraph="false" />
  <hr style="margin: 16px 0; border: 0; border-top: 1px dashed var(--ccui-color-border)" />
  <c-skeleton :title="{ width: '50%' }" :paragraph="{ rows: 2 }" active />
</template>
```

:::

## 圆角化

`round` 让占位条变圆角，与圆角文本组件视觉更协调。

:::demo

```vue
<template>
  <c-skeleton round active avatar :paragraph="{ rows: 3 }" />
</template>
```

:::

## 切换为真实内容

`loading=false` 时直接渲染默认插槽，常用于异步加载完成后揭示真实内容。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(true)

function refresh() {
  loading.value = true
  setTimeout(() => {
    loading.value = false
  }, 1500)
}
refresh()
</script>

<template>
  <c-skeleton :loading="loading" active avatar :paragraph="{ rows: 3 }">
    <div style="display: flex; gap: 12px">
      <div
        style="width: 48px; height: 48px; border-radius: 50%; background: #1677ff; color: white; display: flex; align-items: center; justify-content: center; font-weight: 600"
      >
        CC
      </div>
      <div>
        <h4 style="margin: 0">真实标题已加载</h4>
        <p style="margin: 4px 0; color: var(--ccui-color-text-secondary)">这里是异步取回的内容…</p>
      </div>
    </div>
  </c-skeleton>
  <c-button style="margin-top: 12px" @click="refresh">重新加载</c-button>
</template>
```

:::

## API

### Props

| 参数      | 类型                         | 默认值  | 说明                       |
| --------- | ---------------------------- | ------- | -------------------------- |
| active    | boolean                      | `false` | 显示扫光动画               |
| loading   | boolean                      | `true`  | `false` 时显示默认插槽内容 |
| avatar    | `boolean \| { shape, size }` | `false` | 头像占位                   |
| title     | `boolean \| { width }`       | `true`  | 标题占位                   |
| paragraph | `boolean \| { rows, width }` | `true`  | 段落占位                   |
| round     | boolean                      | `false` | 圆角化占位条               |

### Slots

| 名称    | 说明                               |
| ------- | ---------------------------------- |
| default | `loading=false` 时的真实内容渲染区 |


---

# SkeletonNode 自定义骨架

> 文档链接：https://vaebe.github.io/ccui/components/skeleton-node/index.html

自定义形状的骨架占位容器，作为独立顶层组件存在（**不通过 Skeleton.Node 静态属性挂载**）。

default slot 内可放任意 VNode（最常见是一个 Icon）；本组件提供动画背景 + 居中布局。

## 基本使用

:::demo

```vue
<template>
  <c-space>
    <c-skeleton-node active>
      <svg viewBox="0 0 1024 1024" width="48" height="48" fill="currentColor">
        <path d="M512 64L128 256l384 192 384-192L512 64zM128 768l384 192 384-192V384L512 576 128 384v384z" />
      </svg>
    </c-skeleton-node>
    <c-skeleton-node :width="200" :height="200" />
  </c-space>
</template>
```

:::

## 自定义尺寸

`width` / `height` 接 number（自动加 px）或 CSS 字符串（`'50%'` / `'10rem'`）。

:::demo

```vue
<template>
  <c-space direction="vertical">
    <c-skeleton-node width="100%" height="120px" active />
    <c-skeleton-node :width="240" :height="80" />
  </c-space>
</template>
```

:::

## SkeletonNode 参数

| 参数   | 类型               | 默认      | 说明                       |
| ------ | ------------------ | --------- | -------------------------- |
| active | `boolean`          | `false`   | 是否启用动画               |
| width  | `string \| number` | `'160px'` | 占位宽度；number 自动加 px |
| height | `string \| number` | `'96px'`  | 占位高度；number 自动加 px |

## SkeletonNode 插槽

| 插槽名  | 说明                            |
| ------- | ------------------------------- |
| default | 占位内部内容（图标 / VNode 等） |


---

# Slider 滑块

> 文档链接：https://vaebe.github.io/ccui/components/slider/index.html

滑块组件用于在数值区间内进行选择。

## 何时使用

- 当用户需要在数值区间内进行选择时
- 当需要调整设置值时，如音量、亮度等
- 当需要选择范围值时

## 基本使用

基本的滑块用法。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(50)

    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" />
    <p>当前值: {{ value }}</p>
  </div>
</template>

<style></style>
```

:::

## 范围选择

支持选择数值范围。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const range = ref([20, 80])

    return {
      range,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="range" :range="true" />
    <p>当前范围: {{ range }}</p>
  </div>
</template>

<style></style>
```

:::

## 垂直模式

垂直方向的滑块。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(30)

    return {
      value,
    }
  },
})
</script>

<template>
  <div style="height: 200px;">
    <c-slider v-model="value" vertical />
  </div>
</template>

<style></style>
```

:::

## 步长

设置步长，取值必须大于 0，并且可被 (max - min) 整除。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(40)

    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" :step="10" />
    <p>当前值: {{ value }}</p>
  </div>
</template>

<style></style>
```

:::

## 显示间断点

使用 `show-stops` 属性可以显示间断点。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(40)

    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" :step="10" show-stops />
  </div>
</template>

<style></style>
```

:::

## 带标记

使用 `marks` 属性可以显示标记。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(40)
    const marks = {
      0: '0°C',
      26: '26°C',
      37: '37°C',
      50: '50°C',
    }

    return {
      value,
      marks,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" :marks="marks" />
  </div>
</template>

<style></style>
```

:::

## 带输入框

通过设置 `show-input` 属性可以显示输入框。支持单值模式和范围模式。

### 单值模式

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(50)

    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" show-input />
    <p>当前值: {{ value }}</p>
  </div>
</template>

<style></style>
```

:::

### 范围模式

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const range = ref([20, 80])

    return {
      range,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="range" :range="true" show-input />
    <p>当前范围: {{ range }}</p>
  </div>
</template>

<style></style>
```

:::

## 定制 Tooltip 显示内容

通过 `tips-renderer` 属性可以定制 Tooltip 显示内容，设置 `show-tooltip="false"` 可以隐藏 Tooltip。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value1 = ref(50)
    const value2 = ref(30)

    function formatTooltip(value) {
      return `${value}%`
    }

    return {
      value1,
      value2,
      formatTooltip,
    }
  },
})
</script>

<template>
  <div>
    <h4>自定义 Tooltip 内容</h4>
    <c-slider v-model="value1" :tips-renderer="formatTooltip" />
    <p>当前值: {{ value1 }}</p>

    <h4>隐藏 Tooltip</h4>
    <c-slider v-model="value2" :show-tooltip="false" />
    <p>当前值: {{ value2 }}</p>
  </div>
</template>

<style></style>
```

:::

## Tooltip 位置

通过 `placement` 属性可以设置 Tooltip 的显示位置。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value1 = ref(25)
    const value2 = ref(50)
    const value3 = ref(75)
    const value4 = ref(90)

    return {
      value1,
      value2,
      value3,
      value4,
    }
  },
})
</script>

<template>
  <div>
    <h4>顶部显示（默认）</h4>
    <c-slider v-model="value1" placement="top" />

    <h4>底部显示</h4>
    <c-slider v-model="value2" placement="bottom" />

    <h4>右侧显示</h4>
    <c-slider v-model="value3" placement="right" />

    <h4>左侧显示</h4>
    <c-slider v-model="value4" placement="left" />
  </div>
</template>

<style></style>
```

:::

## 尺寸变体

Slider 提供三种尺寸：large、default、small。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value1 = ref(30)
    const value2 = ref(50)
    const value3 = ref(70)

    return {
      value1,
      value2,
      value3,
    }
  },
})
</script>

<template>
  <div>
    <h4>大尺寸</h4>
    <c-slider v-model="value1" size="large" />

    <h4>默认尺寸</h4>
    <c-slider v-model="value2" />

    <h4>小尺寸</h4>
    <c-slider v-model="value3" size="small" />
  </div>
</template>

<style></style>
```

:::

## 禁用状态

通过设置 `disabled` 属性来禁用滑块。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(50)

    return {
      value,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" disabled />
  </div>
</template>

<style></style>
```

:::

## 无障碍访问

Slider 组件支持完整的无障碍访问功能。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref(50)

    function formatValueText(value) {
      return `当前值为 ${value}`
    }

    return {
      value,
      formatValueText,
    }
  },
})
</script>

<template>
  <div>
    <c-slider v-model="value" label="音量控制" :format-value-text="formatValueText" />
  </div>
</template>

<style></style>
```

:::

## API

### Slider Props

| 参数                  | 说明                                                                                 | 类型                   | 可选值                      | 默认值  |
| --------------------- | ------------------------------------------------------------------------------------ | ---------------------- | --------------------------- | ------- |
| model-value / v-model | 绑定值                                                                               | number / number[]      | —                           | 0       |
| min                   | 最小值                                                                               | number                 | —                           | 0       |
| max                   | 最大值                                                                               | number                 | —                           | 100     |
| disabled              | 是否禁用                                                                             | boolean                | —                           | false   |
| step                  | 步长                                                                                 | number                 | —                           | 1       |
| show-input            | 是否显示输入框，支持单值模式和范围模式                                               | boolean                | —                           | false   |
| show-input-controls   | 在显示输入框的情况下，是否显示输入框的控制按钮                                       | boolean                | —                           | true    |
| input-size            | 输入框的尺寸                                                                         | string                 | large / default / small     | default |
| show-stops            | 是否显示间断点                                                                       | boolean                | —                           | false   |
| show-tooltip          | 是否显示 tooltip                                                                     | boolean                | —                           | true    |
| format-tooltip        | 格式化 tooltip message                                                               | function(value)        | —                           | —       |
| tips-renderer         | 自定义 tooltip 内容                                                                  | function(value) / null | —                           | —       |
| placement             | Tooltip 显示位置                                                                     | string                 | top / right / bottom / left | top     |
| range                 | 是否为范围选择                                                                       | boolean                | —                           | false   |
| vertical              | 是否竖向模式                                                                         | boolean                | —                           | false   |
| height                | Slider 高度，竖向模式时必填                                                          | string                 | —                           | 200px   |
| size                  | Slider 尺寸                                                                          | string                 | large / default / small     | default |
| label                 | 屏幕阅读器标签                                                                       | string                 | —                           | —       |
| aria-label            | 无障碍标签                                                                           | string                 | —                           | —       |
| range-start-label     | 范围选择起始标签                                                                     | string                 | —                           | —       |
| range-end-label       | 范围选择结束标签                                                                     | string                 | —                           | —       |
| format-value-text     | 格式化值文本用于无障碍访问                                                           | function(value)        | —                           | —       |
| tooltip-class         | tooltip 的自定义类名                                                                 | string                 | —                           | —       |
| marks                 | 标记，key 的类型必须为 number 且取值在闭区间 [min, max] 内，每个标记可以单独设置样式 | object                 | —                           | —       |
| validate-event        | 是否触发表单验证                                                                     | boolean                | —                           | true    |
| persistent            | 是否持久化显示 tooltip                                                               | boolean                | —                           | true    |
| show-default-tooltip  | 是否显示默认 tooltip（当 tipsRenderer 为 null 时）                                   | boolean                | —                           | false   |
| precision             | 数值精度                                                                             | number                 | —                           | —       |

### Slider Events

| 事件名 | 说明                                               | 回调参数   |
| ------ | -------------------------------------------------- | ---------- |
| change | 值改变时触发（使用鼠标拖拽时，只在松开鼠标后触发） | 改变后的值 |
| input  | 数据改变时触发（使用鼠标拖拽时，活动过程实时触发） | 改变后的值 |


---

# Space 间距

> 文档链接：https://vaebe.github.io/ccui/components/space/index.html

设置组件之间的间距。

## 何时使用

- 避免组件紧贴在一起，拉开统一的空间。
- 适合行内元素的水平间距。
- 可以设置各种水平对齐方式。

## 基本使用

:::demo

```vue
<template>
  <c-space>
    <c-button>Button</c-button>
    <c-tag>Tag</c-tag>
    <span>Text</span>
  </c-space>
</template>
```

:::

## 垂直间距

:::demo

```vue
<template>
  <c-space direction="vertical">
    <c-button>Button 1</c-button>
    <c-button>Button 2</c-button>
    <c-button>Button 3</c-button>
  </c-space>
</template>
```

:::

## 间距大小

:::demo

```vue
<template>
  <c-space size="small">
    <c-button>small</c-button>
    <c-button>small</c-button>
  </c-space>
  <br /><br />
  <c-space size="middle">
    <c-button>middle</c-button>
    <c-button>middle</c-button>
  </c-space>
  <br /><br />
  <c-space size="large">
    <c-button>large</c-button>
    <c-button>large</c-button>
  </c-space>
  <br /><br />
  <c-space :size="40">
    <c-button>40px</c-button>
    <c-button>40px</c-button>
  </c-space>
</template>
```

:::

## 分隔符

:::demo

```vue
<template>
  <c-space split="·">
    <a href="#">Link 1</a>
    <a href="#">Link 2</a>
    <a href="#">Link 3</a>
  </c-space>
</template>
```

:::

## Space 参数

| 参数      | 类型                                                     | 默认值       | 说明                   |
| --------- | -------------------------------------------------------- | ------------ | ---------------------- |
| align     | 'start' / 'end' / 'center' / 'baseline'                  | --           | 对齐方式               |
| direction | 'horizontal' / 'vertical'                                | 'horizontal' | 间距方向               |
| size      | 'small' / 'middle' / 'large' / number / [number, number] | 'small'      | 间距大小               |
| wrap      | boolean                                                  | false        | 自动换行（仅水平方向） |
| split     | string                                                   | --           | 设置拆分               |


---

# SpaceCompact 紧凑组合

> 文档链接：https://vaebe.github.io/ccui/components/space-compact/index.html

让多个输入类组件视觉上贴边拼接为一组紧凑控件，作为独立顶层组件存在（**不通过 Space.Compact 静态属性挂载**）。

::: tip 与 `<c-space>` 的差异

- `<c-space>` 子项之间留 gap，视觉上是独立组件
- `<c-space-compact>` 子项之间**贴边合并**：相邻 border 重叠（`margin: -1px`）、圆角合并（中间项 `border-radius: 0`、首尾项分别保留外侧圆角）

适合「Input + 选择器 + 按钮」类组合（搜索框 + 搜索按钮、Input + InputNumber、Select + Input 等）。
:::

## 基本使用

:::demo

```vue
<template>
  <c-space-compact>
    <c-input style="width: 240px" placeholder="搜索关键词" />
    <c-button type="primary">搜索</c-button>
  </c-space-compact>
</template>
```

:::

## 多个输入拼接

:::demo

```vue
<template>
  <c-space-compact>
    <c-input style="width: 100px" placeholder="国家" />
    <c-input style="width: 140px" placeholder="城市" />
    <c-input style="width: 160px" placeholder="街道" />
    <c-button>提交</c-button>
  </c-space-compact>
</template>
```

:::

## 纵向紧凑

:::demo

```vue
<template>
  <c-space-compact direction="vertical" style="width: 240px">
    <c-input placeholder="第一行" />
    <c-input placeholder="第二行" />
    <c-input placeholder="第三行" />
  </c-space-compact>
</template>
```

:::

## block 撑满父容器

:::demo

```vue
<template>
  <c-space-compact block>
    <c-input placeholder="搜索关键词" />
    <c-button type="primary">搜索</c-button>
  </c-space-compact>
</template>
```

:::

## SpaceCompact 参数

| 参数      | 类型                             | 默认           | 说明                                 |
| --------- | -------------------------------- | -------------- | ------------------------------------ |
| direction | `'horizontal' \| 'vertical'`     | `'horizontal'` | 紧凑布局方向                         |
| size      | `'large' \| 'middle' \| 'small'` | `'middle'`     | 控件尺寸（透传到子项 SCSS modifier） |
| block     | `boolean`                        | `false`        | 撑满父容器宽度                       |

## SpaceCompact 插槽

| 插槽名  | 说明                                  |
| ------- | ------------------------------------- |
| default | 紧凑组合的子控件（input / button 等） |


---

# Spin 加载中

> 文档链接：https://vaebe.github.io/ccui/components/spin/index.html

加载状态的占位指示器。

## 何时使用

- 异步加载需要 0.5 – 2 秒，给用户一个"正在处理"的反馈。
- 区块级 loading：在表格 / 卡片 / 表单上覆盖加载态。
- 全屏 loading：路由切换或重要异步任务。

## 基本使用

不带任何参数即可显示一个旋转指示。

:::demo

```vue
<template>
  <c-spin />
</template>
```

:::

## 不同尺寸

`size` 接受 `small` / `default` / `large`。

:::demo

```vue
<template>
  <div style="display: flex; gap: 24px; align-items: center">
    <c-spin size="small" />
    <c-spin />
    <c-spin size="large" />
  </div>
</template>
```

:::

## 加上提示文字

`tip` 在指示器下方加一行说明，让等待原因更明确。

:::demo

```vue
<template>
  <c-spin tip="加载中…" />
  &nbsp;&nbsp;&nbsp;&nbsp;
  <c-spin size="large" tip="正在打包，请稍候" />
</template>
```

:::

## 容器内嵌

包裹任意子元素后，`spinning=true` 时在子元素上方覆盖一层加载蒙板。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(true)
</script>

<template>
  <c-spin :spinning="loading">
    <div style="padding: 30px; background: var(--ccui-area); border-radius: 4px">
      <h4 style="margin-top: 0">面板标题</h4>
      <p style="margin: 0">这块内容会被遮罩盖住，加载结束后浮现。</p>
    </div>
  </c-spin>
  <c-button style="margin-top: 12px" @click="loading = !loading"> {{ loading ? '关闭' : '打开' }} loading </c-button>
</template>
```

:::

## 延迟显示

`delay` 让 loading 在异步任务很快完成时根本不闪一下，避免"闪屏"。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(false)

function fast() {
  loading.value = true
  setTimeout(() => (loading.value = false), 200)
}
function slow() {
  loading.value = true
  setTimeout(() => (loading.value = false), 1500)
}
</script>

<template>
  <c-spin :spinning="loading" :delay="500">
    <div style="padding: 30px; background: var(--ccui-area); border-radius: 4px">
      <p style="margin: 0">delay=500ms：仅当请求 ≥ 500ms 才出现 loading</p>
    </div>
  </c-spin>
  <div style="display: flex; gap: 8px; margin-top: 12px">
    <c-button @click="fast">短任务（200ms，不出 loading）</c-button>
    <c-button type="primary" @click="slow"> 长任务（1.5s，出 loading） </c-button>
  </div>
</template>
```

:::

## 全屏模式

`fullscreen` 把 Spin 提到 body 顶层、覆盖整屏，常用于路由切换或重要异步操作。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const visible = ref(false)

function trigger() {
  visible.value = true
  setTimeout(() => (visible.value = false), 1500)
}
</script>

<template>
  <c-button type="primary" @click="trigger">触发 1.5 秒全屏 loading</c-button>
  <c-spin v-if="visible" fullscreen tip="处理中…" />
</template>
```

:::

## 自定义指示器

`#indicator` slot 完全接管旋转图形，可以用 emoji、纯文字、或任何带动画的 VNode。

:::demo

```vue
<template>
  <div style="display: flex; gap: 32px; align-items: center">
    <c-spin tip="加载中">
      <template #indicator>
        <span style="font-size: 28px; display: inline-block; animation: spin 1s linear infinite">⏳</span>
      </template>
    </c-spin>
    <c-spin tip="拼命计算">
      <template #indicator>
        <span style="font-size: 24px">🧠💭</span>
      </template>
    </c-spin>
  </div>
</template>

<style scoped>
@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}
</style>
```

:::

## 关闭后展示内容

`spinning=false` 时遮罩消失，内容完整可见；切换按钮观察过渡。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(false)
</script>

<template>
  <c-spin :spinning="loading">
    <div style="padding: 16px; background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); border-radius: 6px">
      <h4 style="margin: 0 0 8px">订单 #20260515-001</h4>
      <p style="margin: 0; color: var(--ccui-color-text-secondary)">已发货 · 顺丰速运 · SF1234567890</p>
    </div>
  </c-spin>
  <c-button style="margin-top: 12px" type="primary" @click="loading = !loading">
    {{ loading ? '关闭' : '打开' }} loading
  </c-button>
</template>
```

:::

## 异步请求业务

实际请求里用 `try/finally` 把 loading 复位，保证异常路径也能解开。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(false)
const list = ref([
  { id: 1, name: '初始记录 A' },
  { id: 2, name: '初始记录 B' },
])

async function reload() {
  loading.value = true
  try {
    await new Promise((resolve) => setTimeout(resolve, 1200))
    list.value = [
      { id: Date.now(), name: '远程数据 1' },
      { id: Date.now() + 1, name: '远程数据 2' },
      { id: Date.now() + 2, name: '远程数据 3' },
    ]
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <c-button type="primary" style="margin-bottom: 12px" @click="reload">重新加载</c-button>
  <c-spin :spinning="loading" tip="正在拉取最新数据…">
    <ul style="margin: 0; padding: 0 0 0 20px; background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); border-radius: 6px">
      <li v-for="item in list" :key="item.id" style="padding: 6px 0">{{ item.name }}</li>
    </ul>
  </c-spin>
</template>
```

:::

## 包裹表格

表格上方放 toolbar、外层套 Spin，是后台管理最常见的写法。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(true)
const rows = [
  { id: 1, name: '张三', dept: '设计' },
  { id: 2, name: '李四', dept: '研发' },
  { id: 3, name: '王五', dept: '产品' },
]
</script>

<template>
  <c-button style="margin-bottom: 12px" @click="loading = !loading">切换 loading</c-button>
  <c-spin :spinning="loading">
    <table style="width: 100%; border-collapse: collapse; background: var(--ccui-color-bg-container)">
      <thead>
        <tr style="background: var(--ccui-area)">
          <th style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary); text-align: left">ID</th>
          <th style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary); text-align: left">姓名</th>
          <th style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary); text-align: left">部门</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="row in rows" :key="row.id">
          <td style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary)">{{ row.id }}</td>
          <td style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary)">{{ row.name }}</td>
          <td style="padding: 8px; border: 1px solid var(--ccui-color-border-secondary)">{{ row.dept }}</td>
        </tr>
      </tbody>
    </table>
  </c-spin>
</template>
```

:::

## 多 Spin 互不干扰

每个 Spin 都是独立挂载，可以在网格里分别控制——单独刷新某张卡片不会让相邻卡片闪一下。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const cards = ref([
  { id: 1, title: '日活跃用户', value: '12,345', loading: false },
  { id: 2, title: '本月订单', value: '¥ 28,900', loading: true },
  { id: 3, title: '客单价', value: '¥ 156', loading: false },
])

function refresh(card) {
  card.loading = true
  setTimeout(() => (card.loading = false), 1000)
}
</script>

<template>
  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px">
    <c-spin v-for="card in cards" :key="card.id" :spinning="card.loading">
      <div
        style="background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); border-radius: 6px; padding: 16px; cursor: pointer"
        @click="refresh(card)"
      >
        <p style="margin: 0; color: var(--ccui-color-text-tertiary); font-size: 12px">{{ card.title }}</p>
        <p style="margin: 6px 0 0; font-size: 20px; font-weight: 600">{{ card.value }}</p>
        <p style="margin: 6px 0 0; color: var(--ccui-color-primary); font-size: 12px">点击刷新</p>
      </div>
    </c-spin>
  </div>
</template>
```

:::

## API

### Props

| 参数       | 类型                              | 默认值      | 说明                             |
| ---------- | --------------------------------- | ----------- | -------------------------------- |
| spinning   | boolean                           | `true`      | 是否显示                         |
| size       | `'small' \| 'default' \| 'large'` | `'default'` | 尺寸                             |
| tip        | string                            | —           | 指示器下方的说明                 |
| delay      | number                            | `0`         | 延迟显示（毫秒），避免快任务闪屏 |
| fullscreen | boolean                           | `false`     | 全屏覆盖                         |

### Slots

| 名称      | 说明                               |
| --------- | ---------------------------------- |
| default   | 被包裹的内容（容器内嵌模式）       |
| indicator | 自定义旋转图形（替代内置四点动画） |


---

# Splitter 分隔面板

> 文档链接：https://vaebe.github.io/ccui/components/splitter/index.html

通过拖拽分隔条调整两个或多个面板的相对尺寸。常用于"代码编辑器布局"、"文件浏览器"、"双栏对比"。

## 何时使用

- 需要让用户在多个区域间动态分配空间。
- IDE / 数据浏览器 / Diff 视图等。

## 基本使用

水平布局，左右两栏可拖动调整。

:::demo

```vue
<template>
  <c-splitter style="height: 200px; border: 1px solid var(--ccui-color-border-secondary)">
    <c-splitter-panel :default-size="200" :min="100">
      <div style="padding: 16px">Left</div>
    </c-splitter-panel>
    <c-splitter-panel :min="100">
      <div style="padding: 16px">Right</div>
    </c-splitter-panel>
  </c-splitter>
</template>
```

:::

## 垂直布局

`layout="vertical"` 切换成上下分隔。

:::demo

```vue
<template>
  <c-splitter layout="vertical" style="height: 280px; border: 1px solid var(--ccui-color-border-secondary)">
    <c-splitter-panel :default-size="100" :min="50">
      <div style="padding: 16px">Top</div>
    </c-splitter-panel>
    <c-splitter-panel>
      <div style="padding: 16px">Bottom</div>
    </c-splitter-panel>
  </c-splitter>
</template>
```

:::

## 多面板

放多个 `<c-splitter-panel>` 即可形成"三栏布局"，每两栏之间一条分隔条。

:::demo

```vue
<template>
  <c-splitter style="height: 220px; border: 1px solid var(--ccui-color-border-secondary)">
    <c-splitter-panel :default-size="160" :min="80">
      <div style="padding: 16px; background: var(--ccui-area); color: var(--ccui-color-text); height: 100%">侧边栏</div>
    </c-splitter-panel>
    <c-splitter-panel>
      <div style="padding: 16px">主内容</div>
    </c-splitter-panel>
    <c-splitter-panel :default-size="200" :min="100">
      <div style="padding: 16px; background: var(--ccui-area); color: var(--ccui-color-text); height: 100%">右侧详情</div>
    </c-splitter-panel>
  </c-splitter>
</template>
```

:::

## 限制最小 / 最大尺寸

每个面板可独立设置 `min` / `max`，防止被拖到不可用尺寸。

:::demo

```vue
<template>
  <c-splitter style="height: 200px; border: 1px solid var(--ccui-color-border-secondary)">
    <c-splitter-panel :default-size="200" :min="120" :max="320">
      <div style="padding: 12px">min=120, max=320</div>
    </c-splitter-panel>
    <c-splitter-panel :min="80">
      <div style="padding: 12px">min=80</div>
    </c-splitter-panel>
  </c-splitter>
</template>
```

:::

## 不可拖动

设置 `:resizable="false"` 让面板交界处不出现拖拽条（可用作单纯的 flex 布局容器）。

:::demo

```vue
<template>
  <c-splitter style="height: 160px; border: 1px solid var(--ccui-color-border-secondary)">
    <c-splitter-panel :default-size="200" :resizable="false">
      <div style="padding: 12px; background: var(--ccui-area); color: var(--ccui-color-text); height: 100%">固定 200px</div>
    </c-splitter-panel>
    <c-splitter-panel>
      <div style="padding: 12px">弹性</div>
    </c-splitter-panel>
  </c-splitter>
</template>
```

:::

## 监听尺寸变化

`resize` / `resizeStart` / `resizeEnd` 都返回当前各面板像素尺寸数组。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const sizes = ref('（未拖动）')

function onResize(arr) {
  sizes.value = arr.map((n) => Math.round(n)).join(' / ')
}
</script>

<template>
  <c-splitter style="height: 180px; border: 1px solid var(--ccui-color-border-secondary)" @resize="onResize">
    <c-splitter-panel :default-size="200" :min="80">
      <div style="padding: 12px">A</div>
    </c-splitter-panel>
    <c-splitter-panel :min="80">
      <div style="padding: 12px">B</div>
    </c-splitter-panel>
    <c-splitter-panel :default-size="160" :min="80">
      <div style="padding: 12px">C</div>
    </c-splitter-panel>
  </c-splitter>
  <p style="margin-top: 8px; color: var(--ccui-color-text-secondary)">当前尺寸：{{ sizes }}</p>
</template>
```

:::

## API

### Splitter Props

| 参数        | 类型                         | 默认值         | 说明                                |
| ----------- | ---------------------------- | -------------- | ----------------------------------- |
| layout      | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局方向                            |
| orientation | `'horizontal' \| 'vertical'` | -              | `layout` 的别名；显式 `layout` 优先 |

### Splitter Events

| 事件名      | 回调签名            | 触发时机           |
| ----------- | ------------------- | ------------------ |
| resize      | `(sizes: number[])` | 拖拽过程中持续触发 |
| resizeStart | `(sizes: number[])` | 开始拖拽           |
| resizeEnd   | `(sizes: number[])` | 结束拖拽           |

### SplitterPanel Props

| 参数                | 类型                                            | 默认值  | 说明                                                         |
| ------------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------ |
| size                | `number \| string`                              | —       | 由外部状态接管的尺寸                                         |
| defaultSize         | `number \| string`                              | —       | 初始尺寸（不接管时生效）                                     |
| min                 | `number \| string`                              | `0`     | 最小尺寸                                                     |
| max                 | `number \| string`                              | —       | 最大尺寸                                                     |
| resizable           | `boolean`                                       | `true`  | 是否在该面板右 / 下侧画拖拽条                                |
| collapsible         | `boolean \| { start?: boolean; end?: boolean }` | `false` | 是否允许折叠；对象形态分别声明两端                           |
| showCollapsibleIcon | `boolean`                                       | `false` | 是否在 resizer 上渲染折叠 / 展开按钮（需配合 `collapsible`） |


---

# Steps 步骤条

> 文档链接：https://vaebe.github.io/ccui/components/steps/index.html

引导用户按顺序完成任务，把多步流程拆解成可见的进度。

## 基本使用

`current` 标识当前进行到第几步（从 0 开始），`items` 描述每步标题与子说明。

:::demo

```vue
<template>
  <c-steps
    :current="1"
    :items="[
      { title: '已完成', description: '提交订单' },
      { title: '进行中', description: '商家确认' },
      { title: '待处理', description: '物流派送' },
      { title: '待处理', description: '完成' },
    ]"
  />
</template>
```

:::

## 全局状态

`status` 控制当前步骤的状态语义：`process`（默认）/ `finish` / `wait` / `error`。

:::demo

```vue
<template>
  <p style="color: var(--ccui-color-text-secondary); margin: 0 0 6px">status="error"（当前步骤报错）</p>
  <c-steps
    :current="1"
    status="error"
    :items="[{ title: '已完成' }, { title: '出错了', description: '无法继续' }, { title: '待处理' }]"
  />
</template>
```

:::

## 单项状态

`StepItem.status` 可对单个步骤覆盖全局状态（用于"跳跃错误"等场景）。

:::demo

```vue
<template>
  <c-steps
    :current="2"
    :items="[
      { title: '步骤 1', status: 'finish' },
      { title: '步骤 2', status: 'error', description: '校验失败' },
      { title: '步骤 3', status: 'process' },
      { title: '步骤 4', status: 'wait' },
    ]"
  />
</template>
```

:::

## 垂直布局

`direction="vertical"` 把步骤竖排，适合配置向导或长流程。

:::demo

```vue
<template>
  <c-steps
    direction="vertical"
    :current="1"
    :items="[
      { title: '注册账号', description: '填写公司信息并提交' },
      { title: '上传资质', description: '营业执照、税务登记' },
      { title: '审核中', description: '一般 1-3 个工作日' },
      { title: '上线运营' },
    ]"
  />
</template>
```

:::

## 小尺寸

`size="small"` 让圆点 / 文字更紧凑，适合放在 toolbar 中。

:::demo

```vue
<template>
  <c-steps size="small" :current="1" :items="[{ title: '准备' }, { title: '执行' }, { title: '完成' }]" />
</template>
```

:::

## 点状步骤条

`progress-dot` 用圆点替代序号，常用于"轻量进度"展示。

:::demo

```vue
<template>
  <c-steps
    progress-dot
    :current="1"
    :items="[
      { title: '下单', description: '已创建订单' },
      { title: '支付', description: '等待付款' },
      { title: '发货', description: '商品出库' },
      { title: '签收' },
    ]"
  />
</template>
```

:::

## 受控切换

通过 `update:current` 事件接收用户的点击，配合按钮控制流程进度。

:::demo

```vue
<script setup>
import { ref } from 'vue'

const cur = ref(0)
const items = [{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }, { title: '第四步' }]
</script>

<template>
  <c-steps :current="cur" :items="items" @update:current="(i) => (cur = i)" />
  <div style="margin-top: 12px">
    <c-button :disabled="cur === 0" @click="cur -= 1">上一步</c-button>
    <c-button type="primary" style="margin-inline-start: 8px" :disabled="cur === items.length - 1" @click="cur += 1">
      下一步
    </c-button>
  </div>
</template>
```

:::

## API

### Props

| 参数           | 类型                         | 默认值         | 说明                                          |
| -------------- | ---------------------------- | -------------- | --------------------------------------------- |
| current        | number                       | `0`            | 当前步骤（从 0 开始），支持 `v-model:current` |
| items          | `StepItem[]`                 | `[]`           | 步骤数据                                      |
| direction      | `'horizontal' \| 'vertical'` | `'horizontal'` | 排列方向                                      |
| size           | `'default' \| 'small'`       | `'default'`    | 尺寸                                          |
| type           | `'default' \| 'navigation'`  | `'default'`    | 风格：默认 / 导航                             |
| status         | `StepStatus`                 | `'process'`    | 当前步骤的全局状态                            |
| labelPlacement | `'horizontal' \| 'vertical'` | `'horizontal'` | 描述与标题排布                                |
| progressDot    | boolean                      | `false`        | 点状步骤条                                    |

### StepItem

| 字段        | 类型         | 说明                 |
| ----------- | ------------ | -------------------- |
| title       | string       | 标题                 |
| description | string       | 子说明               |
| icon        | string       | 自定义 icon class    |
| status      | `StepStatus` | 单项状态（覆盖全局） |
| disabled    | boolean      | 禁用本步骤的点击     |
| subTitle    | string       | 标题右侧的辅助文案   |

### Events

| 事件名         | 回调签名          | 说明         |
| -------------- | ----------------- | ------------ |
| update:current | `(index: number)` | 当前步骤变化 |

### 类型定义

```ts
type StepStatus = 'wait' | 'process' | 'finish' | 'error'
```


---

# Switch 开关

> 文档链接：https://vaebe.github.io/ccui/components/switch/index.html

开关选择器。

## 何时使用

- 需要表示开关状态/两种状态之间的切换时。
- 与 Checkbox 的区别：切换 Switch 会直接触发状态改变。

## 基本使用

最简形式，绑 `v-model`。

:::demo

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

<template>
  <c-switch v-model="v" />
  <span style="margin-left: 12px">{{ v }}</span>
</template>
```

:::

## 内嵌文字

`checked-children` / `unchecked-children` 在开关内部显示文字。

:::demo

```vue
<template>
  <c-switch checked-children="开" unchecked-children="关" :model-value="true" />
  &nbsp;
  <c-switch checked-children="ON" unchecked-children="OFF" :model-value="false" />
</template>
```

:::

## 尺寸

:::demo

```vue
<template>
  <c-switch :model-value="true" />
  &nbsp;
  <c-switch size="small" :model-value="true" />
</template>
```

:::

## 禁用 / 加载

:::demo

```vue
<template>
  <c-switch disabled :model-value="false" />
  &nbsp;
  <c-switch disabled :model-value="true" />
  &nbsp;
  <c-switch loading :model-value="true" />
  &nbsp;
  <c-switch loading :model-value="false" />
</template>
```

:::

## 自定义开关值

`checkedValue` / `uncheckedValue` 改变开关绑定值，常用于 `'on' / 'off'`、`1 / 0` 这类二元枚举。

:::demo

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

<template>
  <c-switch v-model="status" checked-value="on" unchecked-value="off" />
  <span style="margin-left: 12px">当前状态：{{ status }}</span>
</template>
```

:::

## 监听 change 事件

`change` 在状态改变时触发，回调里可发请求、做联动等。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
const log = ref<string[]>([])

function onChange(val: boolean) {
  log.value.unshift(`${new Date().toLocaleTimeString()}：切到 ${val ? '开' : '关'}`)
  if (log.value.length > 5) log.value.length = 5
}
</script>

<template>
  <c-switch v-model="enabled" @change="onChange" />
  <ul style="margin-top: 12px; color: #888; font-size: 12px">
    <li v-for="(item, i) in log" :key="i">{{ item }}</li>
  </ul>
</template>
```

:::

## API

### Props

| 参数              | 类型                          | 默认值      | 说明               |
| ----------------- | ----------------------------- | ----------- | ------------------ |
| modelValue        | `boolean \| string \| number` | `false`     | v-model 绑定值     |
| checkedValue      | `boolean \| string \| number` | `true`      | 选中时的值         |
| uncheckedValue    | `boolean \| string \| number` | `false`     | 未选中时的值       |
| disabled          | boolean                       | `false`     | 禁用               |
| loading           | boolean                       | `false`     | 加载状态           |
| size              | `'default' \| 'small'`        | `'default'` | 大小               |
| checkedChildren   | string                        | `--`        | 选中时显示的内容   |
| uncheckedChildren | string                        | `--`        | 未选中时显示的内容 |
| autofocus         | boolean                       | `false`     | 自动聚焦           |

### Events

| 事件名 | 回调签名                 | 触发时机       |
| ------ | ------------------------ | -------------- |
| change | `(value, e: MouseEvent)` | 状态改变时触发 |
| click  | `(e: MouseEvent)`        | 点击时触发     |


---

# Table 表格

> 文档链接：https://vaebe.github.io/ccui/components/table/index.html

展示结构化数据，覆盖列渲染、排序、过滤、行选择、固定列、展开行和合并单元格等高频能力。

## Basic

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" bordered></c-table>
</template>

<script setup>
const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Role', dataIndex: 'role', key: 'role' },
  { title: 'Age', dataIndex: 'age', key: 'age', align: 'right' },
]

const dataSource = [
  { id: 1, name: 'Alice', role: 'Admin', age: 32 },
  { id: 2, name: 'Tom', role: 'Member', age: 28 },
  { id: 3, name: 'Bob', role: 'Member', age: 24 },
]
</script>
```

:::

## 模板式列声明

通过 `<c-table-column>` 子组件声明列，替代 `columns` 数组写法；用 `<c-table-column-group>` 把多列合并到一个表头分组（thead 双行）；用 `<c-table-summary>` 在 `<tfoot>` 渲染汇总行。三者都是平铺顶层组件，与 `:columns` 数组互斥（数组非空时优先）。

:::demo

```vue
<template>
  <c-table :data-source="dataSource" row-key="id" bordered>
    <c-table-column title="姓名" data-index="name" column-key="name" :width="120" />
    <c-table-column-group title="成绩">
      <c-table-column title="语文" data-index="chinese" column-key="chinese" align="right" />
      <c-table-column title="数学" data-index="math" column-key="math" align="right" />
      <c-table-column title="英语" data-index="english" column-key="english" align="right" />
    </c-table-column-group>
    <c-table-column title="班级" data-index="grade" column-key="grade" />
    <c-table-summary>
      <tr>
        <td>合计</td>
        <td style="text-align:right">{{ sum('chinese') }}</td>
        <td style="text-align:right">{{ sum('math') }}</td>
        <td style="text-align:right">{{ sum('english') }}</td>
        <td>—</td>
      </tr>
    </c-table-summary>
  </c-table>
</template>

<script setup>
const dataSource = [
  { id: 1, name: 'Alice', chinese: 92, math: 88, english: 95, grade: '高一(1)班' },
  { id: 2, name: 'Tom', chinese: 78, math: 96, english: 82, grade: '高一(1)班' },
  { id: 3, name: 'Bob', chinese: 85, math: 90, english: 76, grade: '高一(2)班' },
]

function sum(field) {
  return dataSource.reduce((s, r) => s + r[field], 0)
}
</script>
```

:::

## 自定义单元格渲染

三种写法：列上 `customRender` 函数 / 全局 `#body-cell` slot（按 `column.key` 区分） / 全局 `#header-cell` slot（自定义表头标签）。函数式与 slot 同时存在时 slot 优先。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" bordered>
    <template #body-cell="{ column, record }">
      <template v-if="column.key === 'status'">
        <span :style="{ color: record.status === 'active' ? '#52c41a' : '#999', fontWeight: 600 }">
          ● {{ record.status === 'active' ? '在职' : '离职' }}
        </span>
      </template>
      <template v-else-if="column.key === 'action'">
        <a style="margin-inline-end: 12px" @click="onEdit(record)">编辑</a>
        <a style="color:var(--ccui-color-error)" @click="onDelete(record)">删除</a>
      </template>
    </template>
    <template #header-cell="{ column }">
      <template v-if="column.key === 'salary'">💰 {{ column.title }}</template>
    </template>
  </c-table>
  <p style="color:var(--ccui-color-text-secondary);margin-top:8px">{{ log || '点击编辑 / 删除查看回调' }}</p>
</template>

<script setup>
import { ref } from 'vue'

const log = ref('')

const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  {
    title: 'Salary',
    dataIndex: 'salary',
    key: 'salary',
    align: 'right',
    customRender: ({ text }) => `¥${text.toLocaleString()}`,
  },
  { title: '状态', dataIndex: 'status', key: 'status' },
  { title: '操作', key: 'action', width: 160 },
]

const dataSource = [
  { id: 1, name: 'Alice', salary: 18000, status: 'active' },
  { id: 2, name: 'Tom', salary: 25000, status: 'inactive' },
  { id: 3, name: 'Bob', salary: 12000, status: 'active' },
]

function onEdit(r) {
  log.value = `编辑 #${r.id} ${r.name}`
}
function onDelete(r) {
  log.value = `删除 #${r.id} ${r.name}`
}
</script>
```

:::

## 树形数据

`dataSource` 中的行通过 `children` 字段携带子节点即自动展开为树（默认字段名 `children`，可通过 `childrenColumnName` 改）；`indentSize` 控制每层缩进像素，默认 15。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" bordered :indent-size="24"></c-table>
</template>

<script setup>
const columns = [
  { title: '名称', dataIndex: 'name', key: 'name' },
  { title: '类型', dataIndex: 'type', key: 'type', width: 120 },
  { title: '负责人', dataIndex: 'owner', key: 'owner', width: 120 },
]

const dataSource = [
  {
    id: 1,
    name: '产品研发中心',
    type: '部门',
    owner: 'Alice',
    children: [
      {
        id: 11,
        name: '前端组',
        type: '小组',
        owner: 'Tom',
        children: [
          { id: 111, name: 'Web 团队', type: '团队', owner: 'Bob' },
          { id: 112, name: '移动团队', type: '团队', owner: 'Carol' },
        ],
      },
      { id: 12, name: '后端组', type: '小组', owner: 'Dan' },
    ],
  },
  { id: 2, name: '市场部', type: '部门', owner: 'Eve' },
]
</script>
```

:::

## Sort And Filter

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id"></c-table>
</template>

<script setup>
const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name', sorter: true },
  {
    title: 'Role',
    dataIndex: 'role',
    key: 'role',
    filterMultiple: false,
    filters: [
      { text: 'Admin', value: 'admin' },
      { text: 'Member', value: 'member' },
    ],
  },
  { title: 'Age', dataIndex: 'age', key: 'age', sorter: (a, b) => a.age - b.age },
]

const dataSource = [
  { id: 1, name: 'Alice', role: 'admin', age: 32 },
  { id: 2, name: 'Tom', role: 'member', age: 28 },
  { id: 3, name: 'Bob', role: 'member', age: 24 },
]
</script>
```

:::

## 固定列

通过 `column.fixed = 'left' | 'right'` 把列吸附在左右两侧；为固定列指定 `width`（数值或带 `px` 的字符串）方可正确计算粘性偏移。当存在任意左固定列时，行选择列与展开图标列会自动跟随固定到左侧。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" :scroll="{ x: 1200 }"></c-table>
</template>

<script setup>
const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name', width: 120, fixed: 'left' },
  { title: 'City', dataIndex: 'city', key: 'city', width: 200 },
  { title: 'Address', dataIndex: 'address', key: 'address', width: 400 },
  { title: 'Phone', dataIndex: 'phone', key: 'phone', width: 200 },
  { title: 'Action', dataIndex: 'action', key: 'action', width: 120, fixed: 'right' },
]

const dataSource = [
  { id: 1, name: 'Alice', city: 'Beijing', address: 'No. 12, Long Road', phone: '13800000001', action: 'Edit' },
  { id: 2, name: 'Tom', city: 'Shanghai', address: 'No. 8, Park Avenue', phone: '13800000002', action: 'Edit' },
]
</script>
```

:::

## 展开行

通过 `expandable.expandedRowRender` 渲染展开内容；支持 `expandedRowKeys` 受控、`defaultExpandAllRows`、`rowExpandable` 和 `expandRowByClick`。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" :expandable="expandable"></c-table>
</template>

<script setup>
const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Role', dataIndex: 'role', key: 'role' },
]

const dataSource = [
  { id: 1, name: 'Alice', role: 'Admin', detail: 'Joined 2024-08, owns billing module.' },
  { id: 2, name: 'Tom', role: 'Member', detail: 'Joined 2025-02, owns dashboards.' },
]

const expandable = {
  expandedRowRender: (record) => record.detail,
}
</script>
```

:::

## 合并单元格

通过 `column.onCell` 为单元格返回 `rowSpan` / `colSpan`，被覆盖的单元格返回 `0` 即可。`column.onHeaderCell` 同样支持表头的合并。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" bordered></c-table>
</template>

<script setup>
const columns = [
  {
    title: 'Team',
    dataIndex: 'team',
    key: 'team',
    onCell: (_record, index) => (index === 0 ? { rowSpan: 2 } : { rowSpan: 0 }),
  },
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Role', dataIndex: 'role', key: 'role' },
]

const dataSource = [
  { id: 1, team: 'Platform', name: 'Alice', role: 'Lead' },
  { id: 2, team: 'Platform', name: 'Tom', role: 'Engineer' },
]
</script>
```

:::

## Row Selection

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" :row-selection="rowSelection"></c-table>
</template>

<script setup>
import { computed, ref } from 'vue'

const selectedRowKeys = ref([2])

const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Role', dataIndex: 'role', key: 'role' },
  { title: 'Age', dataIndex: 'age', key: 'age', align: 'right' },
]

const dataSource = [
  { id: 1, name: 'Alice', role: 'Admin', age: 32 },
  { id: 2, name: 'Tom', role: 'Member', age: 28 },
  { id: 3, name: 'Bob', role: 'Member', age: 24, disabled: true },
]

const rowSelection = computed(() => ({
  selectedRowKeys: selectedRowKeys.value,
  getCheckboxProps: (record) => ({ disabled: record.disabled }),
  onChange: (keys) => {
    selectedRowKeys.value = keys
  },
}))
</script>
```

:::

## 单选 + 选中行实时统计

`rowSelection.type = 'radio'` 把多选改成单选。配合 `getCheckboxProps` 可禁用特定行；`onSelect` 在每次勾选时回传当前行 + 全部选中行，便于做实时汇总。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" :row-selection="rowSelection"></c-table>
  <p style="color:var(--ccui-color-text-secondary);margin-top:8px">
    当前已选：<b>{{ selected ? selected.name : '（未选）' }}</b> ，价格：<b
      >¥{{ selected ? selected.price.toLocaleString() : 0 }}</b
    >
  </p>
</template>

<script setup>
import { computed, ref } from 'vue'

const selectedKey = ref(1)

const columns = [
  { title: '套餐', dataIndex: 'name', key: 'name' },
  { title: '说明', dataIndex: 'desc', key: 'desc' },
  {
    title: '价格',
    dataIndex: 'price',
    key: 'price',
    align: 'right',
    customRender: ({ text }) => `¥${text.toLocaleString()}`,
  },
]

const dataSource = [
  { id: 1, name: '基础版', desc: '个人使用 / 1 用户', price: 0 },
  { id: 2, name: '团队版', desc: '5 用户 / 优先支持', price: 199 },
  { id: 3, name: '企业版', desc: '需联系销售', price: 999, disabled: true },
]

const rowSelection = computed(() => ({
  type: 'radio',
  selectedRowKeys: [selectedKey.value],
  getCheckboxProps: (record) => ({ disabled: record.disabled }),
  onChange: (keys) => {
    selectedKey.value = keys[0]
  },
}))

const selected = computed(() => dataSource.find((r) => r.id === selectedKey.value))
</script>
```

:::

## loading / size / showHeader

`loading=true` 显示遮罩；`size` 三档紧凑度（`small` / `middle` / `default`）；`showHeader=false` 隐藏表头变成卡片化数据列表。

:::demo

```vue
<template>
  <div style="display:flex;gap:8px;margin-bottom:12px;align-items:center">
    <c-segmented v-model="size" :options="['small', 'middle', 'default']" />
    <c-button @click="reload">刷新（模拟 loading）</c-button>
    <label style="margin-inline-start:8px;color:var(--ccui-color-text-secondary)"> <input v-model="showHeader" type="checkbox" /> 显示表头 </label>
  </div>
  <c-table
    :columns="columns"
    :data-source="dataSource"
    row-key="id"
    bordered
    :size="size"
    :loading="loading"
    :show-header="showHeader"
  ></c-table>
</template>

<script setup>
import { ref } from 'vue'

const size = ref('default')
const loading = ref(false)
const showHeader = ref(true)

const columns = [
  { title: '名称', dataIndex: 'name', key: 'name' },
  { title: '状态', dataIndex: 'status', key: 'status' },
  { title: '更新时间', dataIndex: 'updated', key: 'updated' },
]

const dataSource = [
  { id: 1, name: '部署 #1024', status: 'success', updated: '2025-05-15 10:32' },
  { id: 2, name: '部署 #1025', status: 'failed', updated: '2025-05-15 11:08' },
  { id: 3, name: '部署 #1026', status: 'pending', updated: '2025-05-15 12:14' },
]

function reload() {
  loading.value = true
  setTimeout(() => (loading.value = false), 1200)
}
</script>
```

:::

## 自定义空态

`#empty` slot 接管「无数据」占位区，常用于「未筛选到结果」与「真的没数据」分文案，或在空态嵌入引导按钮。

:::demo

```vue
<template>
  <div style="margin-bottom:8px">
    <c-segmented
      v-model="mode"
      :options="[
        { label: '空数据', value: 'empty' },
        { label: '有数据', value: 'full' },
      ]"
    />
  </div>
  <c-table :columns="columns" :data-source="mode === 'empty' ? [] : dataSource" row-key="id" bordered>
    <template #empty>
      <div style="padding:24px 0;text-align:center;color:var(--ccui-color-text-tertiary)">
        <div style="font-size:32px">📭</div>
        <div style="margin-top:6px">还没有任何记录</div>
        <c-button type="primary" size="small" style="margin-top:12px" @click="onCreate">创建第一条</c-button>
      </div>
    </template>
  </c-table>
  <p v-if="log" style="color:var(--ccui-color-text-secondary);margin-top:8px">{{ log }}</p>
</template>

<script setup>
import { ref } from 'vue'

const mode = ref('empty')
const log = ref('')

const columns = [
  { title: '名称', dataIndex: 'name', key: 'name' },
  { title: '状态', dataIndex: 'status', key: 'status' },
]

const dataSource = [{ id: 1, name: '示例', status: 'active' }]

function onCreate() {
  log.value = '点击「创建第一条」按钮'
}
</script>
```

:::

## change 事件全量追踪

`@change` 在过滤 / 排序任意一项变化时触发，回调签名 `(filters, sorter, currentData)`。业务侧最常用于埋点 / 后端 API 联动 / 持久化筛选状态。

:::demo

```vue
<template>
  <c-table :columns="columns" :data-source="dataSource" row-key="id" @change="onChange"></c-table>
  <pre style="margin-top:8px;padding:8px;background:var(--ccui-area);font-size:12px;max-height:200px;overflow:auto">{{
    log
  }}</pre>
</template>

<script setup>
import { ref } from 'vue'

const log = ref('（操作过滤 / 排序后查看回调参数）')

const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name', sorter: (a, b) => a.name.localeCompare(b.name) },
  {
    title: 'Role',
    dataIndex: 'role',
    key: 'role',
    filters: [
      { text: 'Admin', value: 'admin' },
      { text: 'Member', value: 'member' },
    ],
  },
  { title: 'Age', dataIndex: 'age', key: 'age', sorter: (a, b) => a.age - b.age },
]

const dataSource = [
  { id: 1, name: 'Alice', role: 'admin', age: 32 },
  { id: 2, name: 'Tom', role: 'member', age: 28 },
  { id: 3, name: 'Bob', role: 'member', age: 24 },
  { id: 4, name: 'Carol', role: 'admin', age: 41 },
  { id: 5, name: 'Dan', role: 'member', age: 36 },
]

function onChange(filters, sorter, currentData) {
  log.value = JSON.stringify(
    {
      filters,
      sorter: { columnKey: sorter?.columnKey, order: sorter?.order },
      currentDataCount: currentData?.length,
    },
    null,
    2,
  )
}
</script>
```

:::

## 参数

### Table

| 参数               | 类型                               | 默认值     | 说明                                                 |
| ------------------ | ---------------------------------- | ---------- | ---------------------------------------------------- |
| columns            | TableColumn[]                      | []         | 列配置（与子组件 `<c-table-column>` 互斥；数组优先） |
| dataSource         | any[]                              | []         | 行数据                                               |
| rowKey             | string / (record, index) => string | 'key'      | 行唯一标识                                           |
| bordered           | boolean                            | false      | 是否带边框                                           |
| loading            | boolean                            | false      | 是否显示加载遮罩                                     |
| showHeader         | boolean                            | true       | 是否显示表头                                         |
| size               | 'small' / 'middle' / 'default'     | 'default'  | 紧凑度                                               |
| rowSelection       | TableRowSelection                  | --         | 行选择配置                                           |
| expandable         | TableExpandable                    | --         | 展开行配置                                           |
| scroll             | { x?, y? }                         | --         | 横/纵向滚动；横向滚动通常配合 fixed 使用             |
| childrenColumnName | string                             | 'children' | 树形数据子节点字段名                                 |
| indentSize         | number                             | 15         | 树形数据每层缩进 px                                  |

### Slots

| 名称        | 作用域                            | 说明                                             |
| ----------- | --------------------------------- | ------------------------------------------------ |
| default     | --                                | 模板式列声明容器，放 `<c-table-column>` 等子组件 |
| body-cell   | `{ text, record, index, column }` | 单元格统一自定义渲染，按 `column.key` 区分列     |
| header-cell | `{ column, index }`               | 表头单元格统一自定义渲染                         |
| empty       | --                                | 空数据占位                                       |

### TableColumn

| 字段           | 类型                                                      | 说明                        |
| -------------- | --------------------------------------------------------- | --------------------------- |
| title          | string                                                    | 表头标题                    |
| dataIndex      | string / Array<string \| number>                          | 取值路径                    |
| key            | string                                                    | 列唯一标识                  |
| width          | string / number                                           | 列宽（固定列必须给数值）    |
| align          | 'left' / 'center' / 'right'                               | 对齐方式                    |
| fixed          | 'left' / 'right'                                          | 固定列方向                  |
| sorter         | boolean / (a, b) => number                                | 排序                        |
| sortOrder      | 'ascend' / 'descend' / null                               | 受控排序顺序                |
| filters        | TableFilterOption[]                                       | 过滤项                      |
| filteredValue  | TableFilterValue[]                                        | 受控过滤值                  |
| filterMultiple | boolean                                                   | 是否多选过滤                |
| customRender   | (scope) => VNodeChild                                     | 单元格自定义渲染            |
| onCell         | (record, index) => { rowSpan?, colSpan?, style?, class? } | 合并单元格 / 单元格属性扩展 |
| onHeaderCell   | (column) => { rowSpan?, colSpan?, style?, class? }        | 表头单元格属性扩展          |
| children       | TableColumn[]                                             | 子列（仅 ColumnGroup 生成） |

### TableRowSelection

| 字段                   | 类型                                          | 说明                                         |
| ---------------------- | --------------------------------------------- | -------------------------------------------- |
| type                   | 'checkbox' / 'radio'                          | 选择方式，默认多选                           |
| selectedRowKeys        | (string \| number)[]                          | 受控选中行 key                               |
| defaultSelectedRowKeys | (string \| number)[]                          | 非受控初始选中                               |
| columnWidth            | string / number                               | 选择列宽                                     |
| hideSelectAll          | boolean                                       | 是否隐藏「全选」表头复选框                   |
| fixed                  | boolean                                       | 是否固定到左侧（有 left fixed 列时自动跟随） |
| getCheckboxProps       | (record) => { disabled?, name? }              | 单行复选框属性扩展，最常用于禁用特定行       |
| onChange               | (selectedRowKeys, selectedRows) => void       | 选中变化回调                                 |
| onSelect               | (record, selected, selectedRows) => void      | 单行勾选变化                                 |
| onSelectAll            | (selected, selectedRows, changedRows) => void | 表头全选 / 反选                              |

### TableExpandable

| 字段                   | 类型                          | 说明                     |
| ---------------------- | ----------------------------- | ------------------------ |
| expandedRowKeys        | TableSelectionKey[]           | 受控展开行 key           |
| defaultExpandedRowKeys | TableSelectionKey[]           | 非受控初始展开           |
| defaultExpandAllRows   | boolean                       | 是否默认全部展开         |
| expandedRowRender      | (record, index) => VNodeChild | 展开行内容               |
| rowExpandable          | (record) => boolean           | 行是否可展开             |
| columnWidth            | string / number               | 展开图标列宽，默认 48    |
| fixed                  | boolean                       | 是否固定展开图标列到左侧 |
| expandRowByClick       | boolean                       | 是否点击行触发展开       |
| onExpand               | (expanded, record) => void    | 单行展开/收起回调        |
| onChange               | (expandedRowKeys) => void     | 展开 key 集合变化回调    |

### TableColumn（子组件 `<c-table-column>`）

与上表 `TableColumn` 字段一一对应，作为子组件 props 时命名调整：`key` → `column-key`（避开 Vue 保留属性）；`children` 由嵌入的 `<c-table-column>` 子组件自动收集，不需手写。

| Slots        | 作用域                            | 说明                                                  |
| ------------ | --------------------------------- | ----------------------------------------------------- |
| customRender | `{ text, record, index, column }` | 列内单元格自定义渲染（slot 优先于 customRender prop） |

### TableColumnGroup（子组件 `<c-table-column-group>`）

| 参数         | 类型                             | 说明               |
| ------------ | -------------------------------- | ------------------ |
| title        | string                           | 分组表头标题       |
| align        | 'left' / 'center' / 'right'      | 分组表头对齐       |
| fixed        | 'left' / 'right'                 | 整组固定列方向     |
| onHeaderCell | (column) => TableCellRenderProps | 表头单元格属性扩展 |

默认 slot 放 `<c-table-column>` 子列；子列在 tbody 中被展平渲染，在 thead 表现为「分组标题 + 子列标题」双行结构。

### TableSummary（子组件 `<c-table-summary>`）

| 参数  | 类型                       | 默认值 | 说明                                       |
| ----- | -------------------------- | ------ | ------------------------------------------ |
| fixed | boolean / 'top' / 'bottom' | false  | 汇总行是否贴底/贴顶（依赖容器 `scroll.y`） |

默认 slot 直接写 `<tr><td>...</td></tr>`，Table 渲染到 `<tfoot>`。

## 事件

| 事件                   | 说明                               |
| ---------------------- | ---------------------------------- |
| change                 | (filters, sorter, currentData)     |
| update:filters         | 过滤变化                           |
| update:sorter          | 排序变化                           |
| update:selectedRowKeys | 行选择变化                         |
| update:expandedRowKeys | 展开行变化                         |
| expand                 | (expanded, record) — 单行展开/收起 |


---

# TableColumn 表格列

> 文档链接：https://vaebe.github.io/ccui/components/table-column/index.html

模板式表格列声明，作为 `<c-table>` 的子组件出现（**不通过 Table.Column 静态属性挂载**，平铺独立顶层组件）。

::: tip 与 `columns` prop 的关系
`<c-table>` 同时支持两种列声明，**二选一**：

- **数组式（默认）**：`<c-table :columns="columns" :data-source="data" />`。简洁，适合列定义可序列化、来自后端的场景。
- **模板式**：在 `<c-table>` 默认 slot 内放 `<c-table-column>`。适合需要把列结构写在模板里、配合 `v-if` / `v-for` 动态增删列、或者用 scoped slot 渲染单元格的场景。

**两者互斥：`columns` prop 非空时优先用 prop，模板式子组件被忽略**。
:::

## 何时使用

- 列定义需要写在模板里、配合 `v-if` 条件渲染。
- 单元格内容需要复杂的 `scoped slot`（嵌套组件、表单控件等）。
- 偏好把列结构写成 JSX 风格的模板而不是数组配置。

## 基本使用

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', name: 'Tom', age: 28, role: 'admin' },
        { key: '2', name: 'Alice', age: 32, role: 'user' },
        { key: '3', name: 'Bob', age: 24, role: 'user' },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="姓名" data-index="name" column-key="name" />
    <c-table-column title="年龄" data-index="age" column-key="age" :sorter="true" />
    <c-table-column title="角色" data-index="role" column-key="role" />
  </c-table>
</template>
```

:::

## customRender slot 自定义单元格

`customRender` scoped slot 优先于同名 prop；`scope` 含 `{ text, record, index, column }`。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', name: 'Tom', age: 28 },
        { key: '2', name: 'Alice', age: 32 },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="姓名" data-index="name" column-key="name" />
    <c-table-column title="年龄" data-index="age" column-key="age">
      <template #customRender="{ text }">
        <c-tag :type="text > 30 ? 'warning' : 'info'">{{ text }} 岁</c-tag>
      </template>
    </c-table-column>
  </c-table>
</template>
```

:::

## 动态列（v-if / v-for）

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const showRole = ref(true)
    return {
      showRole,
      data: [
        { key: '1', name: 'Tom', age: 28, role: 'admin' },
        { key: '2', name: 'Alice', age: 32, role: 'user' },
      ],
    }
  },
})
</script>

<template>
  <c-space direction="vertical">
    <c-switch v-model="showRole" /> 显示角色列
    <c-table :data-source="data">
      <c-table-column title="姓名" data-index="name" column-key="name" />
      <c-table-column title="年龄" data-index="age" column-key="age" />
      <c-table-column v-if="showRole" title="角色" data-index="role" column-key="role" />
    </c-table>
  </c-space>
</template>
```

:::

## 排序 + 过滤

`sorter` / `filters` 与 columns 数组里同名字段语义一致。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', name: 'Tom', age: 28, role: 'admin' },
        { key: '2', name: 'Alice', age: 32, role: 'user' },
        { key: '3', name: 'Bob', age: 24, role: 'user' },
      ],
      roleFilters: [
        { text: '管理员', value: 'admin' },
        { text: '普通用户', value: 'user' },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="姓名" data-index="name" column-key="name" />
    <c-table-column title="年龄" data-index="age" column-key="age" :sorter="true" />
    <c-table-column title="角色" data-index="role" column-key="role" :filters="roleFilters" :filter-multiple="false" />
  </c-table>
</template>
```

:::

## TableColumn 参数

| 参数           | 类型                                      | 默认   | 说明                                                    |
| -------------- | ----------------------------------------- | ------ | ------------------------------------------------------- |
| title          | `string`                                  | `''`   | 列标题                                                  |
| dataIndex      | `string \| Array<string \| number>`       | -      | 字段路径，支持 `'a.b'` 字符串或 `['a','b']` 数组        |
| columnKey      | `string`                                  | -      | 列 key（用于 sorter / filter 标识；不传则用 dataIndex） |
| width          | `string \| number`                        | -      | 列宽度                                                  |
| align          | `'left' \| 'center' \| 'right'`           | -      | 内容对齐                                                |
| fixed          | `'left' \| 'right'`                       | -      | 固定列方向                                              |
| sorter         | `boolean \| (a, b) => number`             | -      | 是否可排序 / 自定义排序函数                             |
| sortOrder      | `'ascend' \| 'descend' \| null`           | -      | 受控排序态                                              |
| filters        | `{ text, value }[]`                       | -      | 过滤选项                                                |
| filteredValue  | `Array`                                   | -      | 受控过滤态                                              |
| filterMultiple | `boolean`                                 | `true` | 是否多选过滤                                            |
| customRender   | `(scope) => VNodeChild`                   | -      | 函数式自定义渲染（slot 优先）                           |
| onCell         | `(record, index) => TableCellRenderProps` | -      | 单元格 props 工厂                                       |
| onHeaderCell   | `(column) => TableCellRenderProps`        | -      | 表头单元格 props 工厂                                   |

## TableColumn 插槽

| 插槽名       | 作用域参数                        | 说明             |
| ------------ | --------------------------------- | ---------------- |
| customRender | `{ text, record, index, column }` | 自定义单元格内容 |


---

# TableColumnGroup 表格列分组

> 文档链接：https://vaebe.github.io/ccui/components/table-column-group/index.html

表格列分组组件，作为 `<c-table>` 的子组件，让 thead 多生成一行「分组标题」，子叶子列在 tbody 中被展平渲染（**不通过 Table.ColumnGroup 静态属性挂载**，平铺独立顶层组件）。

::: tip 使用前提
TableColumnGroup 必须与 [`<c-table-column>`](/components/table-column/) 一起使用（模板式列声明）。
:::

## 何时使用

- 多列共享一个上位标题，需要分组表头展示（如「姓名」分为「姓」「名」两列）。
- 报表场景：横向月份分组、维度分组。

## 基本使用

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', firstName: '张', lastName: '三', age: 28, role: 'admin' },
        { key: '2', firstName: '李', lastName: '四', age: 32, role: 'user' },
        { key: '3', firstName: '王', lastName: '五', age: 24, role: 'user' },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column-group title="姓名">
      <c-table-column title="姓" data-index="firstName" column-key="firstName" />
      <c-table-column title="名" data-index="lastName" column-key="lastName" />
    </c-table-column-group>
    <c-table-column title="年龄" data-index="age" column-key="age" />
    <c-table-column title="角色" data-index="role" column-key="role" />
  </c-table>
</template>
```

:::

## 多组并存

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', firstName: '张', lastName: '三', q1: 100, q2: 120 },
        { key: '2', firstName: '李', lastName: '四', q1: 90, q2: 110 },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column-group title="姓名">
      <c-table-column title="姓" data-index="firstName" column-key="firstName" />
      <c-table-column title="名" data-index="lastName" column-key="lastName" />
    </c-table-column-group>
    <c-table-column-group title="销售额">
      <c-table-column title="Q1" data-index="q1" column-key="q1" />
      <c-table-column title="Q2" data-index="q2" column-key="q2" />
    </c-table-column-group>
  </c-table>
</template>
```

:::

## 组外独立列与组并存

非分组的顶层列自动 `rowspan=2` 跨双行。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', name: '张三', q1: 100, q2: 120 },
        { key: '2', name: '李四', q1: 90, q2: 110 },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="姓名" data-index="name" column-key="name" />
    <c-table-column-group title="销售额">
      <c-table-column title="Q1" data-index="q1" column-key="q1" />
      <c-table-column title="Q2" data-index="q2" column-key="q2" />
    </c-table-column-group>
  </c-table>
</template>
```

:::

## TableColumnGroup 参数

| 参数         | 类型                               | 默认 | 说明                                 |
| ------------ | ---------------------------------- | ---- | ------------------------------------ |
| title        | `string`                           | `''` | 组标题，渲染在 thead 顶部行          |
| align        | `'left' \| 'center' \| 'right'`    | -    | 组标题对齐                           |
| fixed        | `'left' \| 'right'`                | -    | 组固定方向（实际固定行为以子列为准） |
| onHeaderCell | `(column) => TableCellRenderProps` | -    | 组标题单元格 props 工厂              |

## TableColumnGroup 插槽

| 插槽名  | 说明                         |
| ------- | ---------------------------- |
| default | 子 `<c-table-column>` 列声明 |


---

# TableSummary 表格汇总

> 文档链接：https://vaebe.github.io/ccui/components/table-summary/index.html

表格汇总行，在 `<c-table>` 底部渲染 `<tfoot>` 汇总区（**不通过 Table.Summary 静态属性挂载**，平铺独立顶层组件）。

::: tip 使用前提
TableSummary 必须作为 `<c-table>` 的子组件使用。default slot 内放 `<tr>` / `<td>` 原生标签（也可放多个 `<tr>` 行），由 Table 直接挂到 tfoot。
:::

## 何时使用

- 表格底部需要展示「合计」「平均值」「总数」等汇总信息。
- 报表 / 财务 / 数据看板的总计行。

## 基本使用

:::demo

```vue
<script>
import { computed, defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const data = [
      { key: '1', name: '苹果', qty: 10, price: 5 },
      { key: '2', name: '香蕉', qty: 20, price: 3 },
      { key: '3', name: '橙子', qty: 15, price: 4 },
    ]
    const totalQty = computed(() => data.reduce((sum, r) => sum + r.qty, 0))
    const totalAmount = computed(() => data.reduce((sum, r) => sum + r.qty * r.price, 0))
    return { data, totalQty, totalAmount }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="名称" data-index="name" column-key="name" />
    <c-table-column title="数量" data-index="qty" column-key="qty" />
    <c-table-column title="单价" data-index="price" column-key="price" />
    <c-table-summary>
      <tr>
        <td><b>合计</b></td>
        <td>{{ totalQty }}</td>
        <td>{{ totalAmount }} 元</td>
      </tr>
    </c-table-summary>
  </c-table>
</template>
```

:::

## 多行汇总

可在 default slot 内放多个 `<tr>` 渲染多行汇总。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {
      data: [
        { key: '1', name: '苹果', qty: 10 },
        { key: '2', name: '香蕉', qty: 20 },
      ],
    }
  },
})
</script>

<template>
  <c-table :data-source="data">
    <c-table-column title="名称" data-index="name" column-key="name" />
    <c-table-column title="数量" data-index="qty" column-key="qty" />
    <c-table-summary>
      <tr>
        <td>小计</td>
        <td>30</td>
      </tr>
      <tr>
        <td>含税</td>
        <td>33</td>
      </tr>
    </c-table-summary>
  </c-table>
</template>
```

:::

## TableSummary 参数

| 参数  | 类型                           | 默认    | 说明                                                   |
| ----- | ------------------------------ | ------- | ------------------------------------------------------ |
| fixed | `boolean \| 'top' \| 'bottom'` | `false` | 滚动场景汇总行是否粘性（真实粘性依赖 `scroll.y` 容器） |

## TableSummary 插槽

| 插槽名  | 说明                                                  |
| ------- | ----------------------------------------------------- |
| default | 汇总行内容，需要包一层或多层 `<tr>` / `<td>` 原生节点 |


---

# Tabs 选项卡

> 文档链接：https://vaebe.github.io/ccui/components/tabs/index.html

选项卡切换组件。

## 何时使用

用户需要通过平级的区域将大块内容进行收纳和展现，保持界面整洁。

## Tabs基本使用

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const activeTab = ref('1')
    return {
      activeTab,
    }
  },
})
</script>

<template>
  <c-tabs v-model="activeTab" class="my-tabs">
    <c-tab label="周一" name="1">
      我们终将远行，和过去稚嫩的自己告别。这是一个流行告别的时代，陪你颠沛流离的人越来越少，直至没有。我们也要习惯昔日好友的渐行渐远，因为我们终将长大，长大到可以独自一人抵挡风雨。
    </c-tab>
    <c-tab label="周二" name="2">
      人生就是一辆开往坟墓的列车，路途上会有很多站，很难有人可以自始至终地陪你走完。当陪你的人要下车时，即使不舍也该心存感激，然后挥手道别。人生就是如此，没有谁会一直陪伴谁，我们应该怀着感恩之心，和过去的好友告别。毕竟曾经在我们人生某一个艰难的时刻，她们的确给过我们温暖。
    </c-tab>
    <c-tab label="疯狂星期四" name="3"> V我50 </c-tab>
  </c-tabs>
</template>

<style lang="scss">
.my-tabs {
  .okUi-tab {
    padding: 20px;
    font-size: 30px;
    font-weight: bold;
  }
}
</style>
```

:::

## Tabs卡片风格的标签

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const activeTab = ref('1')
    return {
      activeTab,
    }
  },
})
</script>

<template>
  <c-tabs v-model="activeTab" type="card" class="my-tabs">
    <c-tab label="周一" name="1">
      我们终将远行，和过去稚嫩的自己告别。这是一个流行告别的时代，陪你颠沛流离的人越来越少，直至没有。我们也要习惯昔日好友的渐行渐远，因为我们终将长大，长大到可以独自一人抵挡风雨。
    </c-tab>
    <c-tab label="周二" name="2">
      人生就是一辆开往坟墓的列车，路途上会有很多站，很难有人可以自始至终地陪你走完。当陪你的人要下车时，即使不舍也该心存感激，然后挥手道别。人生就是如此，没有谁会一直陪伴谁，我们应该怀着感恩之心，和过去的好友告别。毕竟曾经在我们人生某一个艰难的时刻，她们的确给过我们温暖。
    </c-tab>
    <c-tab label="疯狂星期四" name="3"> V我100别问为什么，问就是有中间商 </c-tab>
  </c-tabs>
</template>

<style lang="scss">
.my-tabs {
  .okUi-tab {
    padding: 20px;
    font-size: 30px;
    font-weight: bold;
  }
}
</style>
```

:::

## Tabs带有边框的卡片风格

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const activeTab = ref('1')
    return {
      activeTab,
    }
  },
})
</script>

<template>
  <c-tabs v-model="activeTab" type="border-card" class="my-tabs">
    <c-tab label="周一" name="1">
      我们终将远行，和过去稚嫩的自己告别。这是一个流行告别的时代，陪你颠沛流离的人越来越少，直至没有。我们也要习惯昔日好友的渐行渐远，因为我们终将长大，长大到可以独自一人抵挡风雨。
    </c-tab>
    <c-tab label="周二" name="2">
      人生就是一辆开往坟墓的列车，路途上会有很多站，很难有人可以自始至终地陪你走完。当陪你的人要下车时，即使不舍也该心存感激，然后挥手道别。人生就是如此，没有谁会一直陪伴谁，我们应该怀着感恩之心，和过去的好友告别。毕竟曾经在我们人生某一个艰难的时刻，她们的确给过我们温暖。
    </c-tab>
    <c-tab label="疯狂星期四" name="3">
      工厂模式其实就是将创建对象的过程单独封装：比如说点一份西红柿炒蛋，我们不用关心西红柿怎么切、怎么打鸡蛋这些菜品制作过程中的问题，我们只关心摆上桌那道菜。在工厂模式里，我传参这个过程就是点菜，工厂函数里面运转的逻辑就相当于炒菜的厨师和上桌的服务员做掉的那部分工作——这部分工作我们同样不用关心，我们只要能拿到工厂交付给我们的实例结果就行了。
    </c-tab>
  </c-tabs>
</template>

<style lang="scss">
.my-tabs {
  .okUi-tab {
    padding: 20px;
    font-size: 30px;
    font-weight: bold;
  }
}
</style>
```

:::

## Tabs自定义标签页标题

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const activeTab = ref('1')
    return {
      activeTab,
    }
  },
})
</script>

<template>
  <c-tabs v-model="activeTab" class="my-tabs">
    <c-tab label="周一" name="1">
      <template #title> 周一 </template>
      我们终将远行，和过去稚嫩的自己告别。这是一个流行告别的时代，陪你颠沛流离的人越来越少，直至没有。我们也要习惯昔日好友的渐行渐远，因为我们终将长大，长大到可以独自一人抵挡风雨。
    </c-tab>
    <c-tab label="周二" name="2">
      人生就是一辆开往坟墓的列车，路途上会有很多站，很难有人可以自始至终地陪你走完。当陪你的人要下车时，即使不舍也该心存感激，然后挥手道别。人生就是如此，没有谁会一直陪伴谁，我们应该怀着感恩之心，和过去的好友告别。毕竟曾经在我们人生某一个艰难的时刻，她们的确给过我们温暖。
    </c-tab>
    <c-tab label="疯狂星期四" name="3">
      保证一个类仅有一个实例，并提供一个访问它的全局访问点，这样的模式就叫做单例模式。
    </c-tab>
  </c-tabs>
</template>

<style lang="scss">
.my-tabs {
  .okUi-tab {
    padding: 20px;
    font-size: 30px;
    font-weight: bold;
  }
}
</style>
```

:::

## Tabs标签位置的设置

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const activeTab = ref('1')

    const checkedRadio = ref('top')
    return {
      activeTab,
      checkedRadio,
    }
  },
})
</script>

<template>
  <c-radio-group v-model="checkedRadio" direction="row">
    <c-radio label="top"> top </c-radio>
    <c-radio label="right"> right </c-radio>
    <c-radio label="bottom"> bottom </c-radio>
    <c-radio label="left"> left </c-radio>
  </c-radio-group>

  <c-tabs v-model="activeTab" class="my-tabs" :tab-position="checkedRadio">
    <c-tab label="周一" name="1"> 疲惫的一天 </c-tab>
    <c-tab label="周二" name="2"> 开心 </c-tab>
    <c-tab label="疯狂星期四" name="3"> 狂吃 </c-tab>
  </c-tabs>
</template>

<style lang="scss">
.my-tabs {
  height: 200px;

  .okUi-tab {
    padding: 20px;
    font-size: 30px;
    font-weight: bold;
  }
}
</style>
```

:::

## Tabs参数

| 参数         | 类型                                  | 默认 | 说明                      |
| ------------ | ------------------------------------- | ---- | ------------------------- |
| v-model      | [ModelValueType](#modelvaluetype)     | -    | 绑定值，选中选项卡的 name |
| type         | [TabsType](#itabstype)                | -    | 风格类型                  |
| tab-position | [ITabPositionType](#itabpositiontype) | top  | 选项卡所在位置            |

## Tabs事件

| 事件   | 类型                                  | 说明                  |
| ------ | ------------------------------------- | --------------------- |
| change | [BeforeChangeType](#beforechangetype) | activeName 改变时触发 |

## tabs类型定义

### ModelValueType

```ts
export type ModelValueType = string | number
```

### ITabsType

```ts
export type ITabsType = '' | 'card' | 'border-card'
```

### ITabPositionType

```ts
export type ITabPositionType = 'top' | 'right' | 'bottom' | 'left'
```

### BeforeChangeType

```ts
export type Active = string | number | null
export type BeforeChangeType = (id: Active) => boolean
```

## Tabs插槽

默认插槽

## Tab参数

| 参数  | 类型                    | 默认 | 说明                                              |
| ----- | ----------------------- | ---- | ------------------------------------------------- |
| label | [LabelType](#labeltype) | -    | 选项卡标题                                        |
| name  | [NameType](#nametype)   | -    | 与选项卡绑定值 value 对应的标识符，表示选项卡别名 |

## tab类型定义

### LabelType

```ts
export type LabelType = string | number
```

### NameType

```ts
export type NameType = string | number
```

## Tab插槽

| 插槽名 | 说明       |
| ------ | ---------- |
| title  | 标签页标题 |
| -      | 默认插槽   |


---

# Tag 标签

> 文档链接：https://vaebe.github.io/ccui/components/tag/index.html

进行标记和分类的小标签。

## 何时使用

- 用于标记事物的属性和维度。
- 进行分类。

## 基本使用

:::demo

```vue
<template>
  <c-tag>Tag 1</c-tag>
  <c-tag color="primary"> Primary </c-tag>
  <c-tag color="success"> Success </c-tag>
  <c-tag color="warning"> Warning </c-tag>
  <c-tag color="error"> Error </c-tag>
  <c-tag color="processing"> Processing </c-tag>
</template>
```

:::

## 多彩标签

:::demo

```vue
<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px">
    <c-tag color="magenta"> magenta </c-tag>
    <c-tag color="red"> red </c-tag>
    <c-tag color="volcano"> volcano </c-tag>
    <c-tag color="orange"> orange </c-tag>
    <c-tag color="gold"> gold </c-tag>
    <c-tag color="lime"> lime </c-tag>
    <c-tag color="green"> green </c-tag>
    <c-tag color="cyan"> cyan </c-tag>
    <c-tag color="blue"> blue </c-tag>
    <c-tag color="geekblue"> geekblue </c-tag>
    <c-tag color="purple"> purple </c-tag>
  </div>
</template>
```

:::

## 可关闭

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const visible = ref(true)
    return { visible }
  },
})
</script>

<template>
  <c-tag v-if="visible" closable @close="visible = false"> 可关闭 </c-tag>
  <c-button v-else size="small" @click="visible = true"> 重置 </c-button>
</template>
```

:::

## 自定义颜色

:::demo

```vue
<template>
  <c-tag color="#f50"> #f50 </c-tag>
  <c-tag color="#2db7f5"> #2db7f5 </c-tag>
  <c-tag color="#87d068"> #87d068 </c-tag>
</template>
```

:::

## Tag 参数

| 参数     | 类型    | 默认值    | 说明                                 |
| -------- | ------- | --------- | ------------------------------------ |
| color    | string  | 'default' | 颜色：预设色板名 / 状态色 / 任意 hex |
| closable | boolean | false     | 是否可关闭                           |
| icon     | string  | --        | 图标类名                             |

## Tag 事件

| 事件名 | 参数       | 说明           |
| ------ | ---------- | -------------- |
| close  | (e: Event) | 关闭按钮被点击 |

## Tag 插槽

| 插槽名  | 说明       |
| ------- | ---------- |
| default | 标签内容   |
| icon    | 自定义图标 |


---

# Textarea 多行文本

> 文档链接：https://vaebe.github.io/ccui/components/textarea/index.html

多行文本输入框，作为独立顶层组件存在（不挂在 Input 命名空间下）。

## 何时使用

- 需要多行长文本输入时。
- 需要根据内容自动调整高度（`autoSize`）。
- 需要显示字符计数 / 限制最大长度（`showCount` / `maxLength`）。

## 基本使用

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const value = ref('')
    return { value }
  },
})
</script>

<template>
  <c-textarea v-model="value" placeholder="请输入" :rows="3" />
</template>
```

:::

## 自动调整高度

`autoSize` 支持 `boolean | { minRows, maxRows }` 三种形态：

- `false`（默认）：固定 `rows`。
- `true`：高度跟随内容，无上限。
- 对象：限制最小 / 最大行数。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      v1: ref(''),
      v2: ref(''),
    }
  },
})
</script>

<template>
  <c-textarea v-model="v1" :auto-size="true" placeholder="autoSize=true 跟随内容" />
  <c-textarea
    v-model="v2"
    :auto-size="{ minRows: 2, maxRows: 6 }"
    placeholder="autoSize={ minRows:2, maxRows:6 }"
    style="margin-top: 12px"
  />
</template>
```

:::

## 字符计数

`showCount` 支持 `boolean | { formatter }`，与 `maxLength` 配合显示 `N / max`。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      v1: ref(''),
      v2: ref(''),
    }
  },
})
</script>

<template>
  <c-textarea v-model="v1" :show-count="true" :max-length="100" placeholder="默认 N / max" />
  <c-textarea
    v-model="v2"
    :show-count="{ formatter: ({ count, maxLength }) => `${count} 字 / ${maxLength}` }"
    :max-length="50"
    placeholder="自定义 formatter"
    style="margin-top: 12px"
  />
</template>
```

:::

## 清除按钮

`allowClear` 支持 `boolean | { clearIcon }`，`clearIcon` 接 Iconify name 或 VNode。

:::demo

```vue
<script>
import { defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    return {
      v1: ref('可以清除'),
      v2: ref('Iconify 图标'),
    }
  },
})
</script>

<template>
  <c-textarea v-model="v1" allow-clear placeholder="默认清除按钮" />
  <c-textarea
    v-model="v2"
    :allow-clear="{ clearIcon: 'mdi:close-circle' }"
    placeholder="自定义 Iconify 图标"
    style="margin-top: 12px"
  />
</template>
```

:::

## 校验状态

:::demo

```vue
<template>
  <c-textarea status="error" placeholder="error 态" />
  <c-textarea status="warning" placeholder="warning 态" style="margin-top: 12px" />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-textarea v-model="value" :variant="variant" :rows="3" placeholder="切换 variant 观察样式" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
</script>
```

:::

## Textarea 参数

| 参数         | 类型                                              | 默认     | 说明                                                |
| ------------ | ------------------------------------------------- | -------- | --------------------------------------------------- |
| modelValue   | string                                            | --       | 绑定值（v-model）                                   |
| defaultValue | string                                            | --       | 非受控初值，仅首次挂载使用                          |
| placeholder  | string                                            | --       | 占位符                                              |
| rows         | number                                            | 2        | 原生 rows，autoSize 开启时忽略                      |
| autoSize     | boolean \| { minRows?: number; maxRows?: number } | false    | 高度自适应                                          |
| allowClear   | boolean \| { clearIcon?: VNode \| string }        | false    | 是否显示清除按钮                                    |
| showCount    | boolean \| { formatter?: (info) => string }       | false    | 显示字符计数                                        |
| maxLength    | number                                            | --       | 最大长度（透传原生 maxlength）                      |
| size         | 'large' \| 'default' \| 'small'                   | default  | 尺寸                                                |
| disabled     | boolean                                           | false    | 是否禁用                                            |
| readonly     | boolean                                           | false    | 是否只读                                            |
| status       | '' \| 'error' \| 'warning'                        | ''       | 校验状态，Form 联动会自动透传                       |
| resize       | 'none' \| 'both' \| 'horizontal' \| 'vertical'    | vertical | 原生 textarea CSS resize，autoSize=true 时强制 none |

## Textarea 事件

| 事件名            | 参数       | 说明                              |
| ----------------- | ---------- | --------------------------------- |
| update:modelValue | value      | 绑定值改变时触发（v-model）       |
| input             | value      | 输入时触发                        |
| change            | value      | 失焦时触发                        |
| focus             | event      | 获得焦点                          |
| blur              | event      | 失去焦点                          |
| clear             | --         | 点击清除按钮时触发                |
| press-enter       | event      | Enter（不含 Shift/Ctrl/Alt/Meta） |
| resize            | { height } | autoSize 引起的高度变化           |

## Textarea 插槽

| 插槽名 | 说明                 |
| ------ | -------------------- |
| suffix | 文本框下方的附加内容 |


---

# 主题定制 / 深色模式

> 文档链接：https://vaebe.github.io/ccui/components/theme/index.html

ccui 的所有组件样式都建立在一套 `--ccui-*` CSS 变量之上。深色模式、品牌色定制、圆角调整都归结为一件事：**覆盖这些 CSS 变量**。本页梳理三种由浅入深的用法。

## 深色模式怎么生效

深色样式集中在 `darkTheme.css`，所有规则都 scope 在 `.dark` 选择器下，形如：

```css
.dark {
  --ccui-color-bg-container: #141414;
  --ccui-color-text: rgba(255, 255, 255, 0.85);
  /* …整套 token 的深色取值 */
}
```

只要某个祖先元素带上 `.dark` 类，其子树内的 ccui 组件就会就地切换到深色取值。因此「切换深色」=「在合适的元素上挂 `.dark` 类」。`darkTheme.css` 已在文档站全局引入；接入你自己的应用时，从 `@vaebe/ccui-theme/darkTheme.css` 引入一次即可。

## 应用级深色切换（主推）

整站统一切换深色，推荐把 `.dark` 类挂在根元素（`<html>` 或 `<body>`）上。这样所有组件、布局、自定义样式同时切换，无需逐处包裹。

下面是一个「跟随系统 + 手动切换」的最小实现：首屏跟随系统偏好，用户手动点击后记住选择并落到 `localStorage`。

```ts
const STORAGE_KEY = 'ccui-theme'

function applyDark(isDark: boolean) {
  document.documentElement.classList.toggle('dark', isDark)
}

// 1. 初始化：优先读取用户已保存的选择，否则跟随系统
const media = window.matchMedia('(prefers-color-scheme: dark)')
const saved = localStorage.getItem(STORAGE_KEY) // 'dark' | 'light' | null
applyDark(saved ? saved === 'dark' : media.matches)

// 2. 手动切换：写入存储并即时应用
function setTheme(isDark: boolean) {
  localStorage.setItem(STORAGE_KEY, isDark ? 'dark' : 'light')
  applyDark(isDark)
}

// 3. 未手动指定时，继续跟随系统变化
media.addEventListener('change', (e) => {
  if (!localStorage.getItem(STORAGE_KEY)) applyDark(e.matches)
})
```

把 `setTheme(true / false)` 接到你的开关按钮即可。Vue 项目里也可以直接用 `useDark` / `useToggle`（来自 VueUse）托管同样的逻辑，行为一致。

## 局部 / 子树方案

只想让页面的某一块走深色（例如预览面板、对比区域），无需触碰根元素，用 `c-config-provider` 的 `theme.algorithm` 即可。设为 `'dark'` 时，ConfigProvider 会在其包裹层挂上 `.dark` 类，从而只让这棵子树切换深色。

:::demo

```vue
<template>
  <c-config-provider :theme="{ algorithm: 'dark' }">
    <c-card title="子树深色" style="width: 320px">
      <c-space>
        <c-button type="primary">主按钮</c-button>
        <c-button>默认按钮</c-button>
      </c-space>
    </c-card>
  </c-config-provider>
</template>
```

:::

`algorithm` 与 `token` 可以同时使用：先由 `algorithm: 'dark'` 给出整套深色基线，再用 `token` 覆盖个别值。

## token 体系简介

ccui 的设计变量统一以 `--ccui-` 开头，覆盖颜色、圆角、字号、间距、动效、层级等。组件样式只读这些变量，所以你既可以直接在 CSS 里覆盖变量，也可以通过 `c-config-provider` 的 `theme.token` 用 camelCase 形式传入（如 `colorPrimary`、`borderRadius`），ConfigProvider 会自动映射成对应的 `--ccui-*` 变量并下传给子组件。

### 关键色 light / dark 对照

下表节选几个最常用的 token，列出浅色与深色两套取值，方便对照理解变量在两种模式下的差异：

| token（camelCase） | CSS 变量                    | Light             | Dark                    |
| ------------------ | --------------------------- | ----------------- | ----------------------- |
| colorPrimary       | `--ccui-color-primary`      | `#1677ff`         | `#1668dc`               |
| colorSuccess       | `--ccui-color-success`      | `#52c41a`         | `#49aa19`               |
| colorWarning       | `--ccui-color-warning`      | `#faad14`         | `#d89614`               |
| colorError         | `--ccui-color-error`        | `#ff4d4f`         | `#dc4446`               |
| colorText          | `--ccui-color-text`         | `rgba(0,0,0,.88)` | `rgba(255,255,255,.85)` |
| colorBgContainer   | `--ccui-color-bg-container` | `#ffffff`         | `#141414`               |
| colorBgBase        | `--ccui-color-bg-base`      | `#ffffff`         | `#000000`               |
| colorBorder        | `--ccui-color-border`       | `#d9d9d9`         | `#424242`               |
| borderRadius       | `--ccui-border-radius`      | `6px`             | `6px`                   |

### 自定义 token 覆盖品牌色

最常见的需求是换一套品牌主色。把 camelCase 的 token 传给 `theme.token`，作用域内组件就会跟着走新主色。下面的示例可以在几个预设主色之间实时切换：

:::demo

```vue
<template>
  <c-config-provider :theme="{ token: { colorPrimary: color, borderRadius: radius } }">
    <c-space>
      <c-button type="primary">主按钮</c-button>
      <c-button type="primary" danger>危险按钮</c-button>
      <c-switch :default-checked="true" />
    </c-space>
  </c-config-provider>

  <div style="margin-top: 16px; display: flex; gap: 8px; align-items: center; flex-wrap: wrap">
    <c-button v-for="c in colors" :key="c" :style="{ background: c, color: 'var(--ccui-color-text-light-solid)', border: 'none' }" @click="color = c">
      {{ c }}
    </c-button>
    <span style="margin-inline-start: 8px">圆角</span>
    <c-input-number v-model:value="radius" :min="0" :max="20" style="width: 96px" />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const colors = ['#1677ff', '#52c41a', '#722ed1', '#fa541c']
const color = ref('#1677ff')
const radius = ref(6)
</script>
```

:::

`theme.token` 接收的字段与上表的 camelCase 名一一对应，`colorPrimary` / `borderRadius` / `colorError` 等都可以一起传。需要更细的派生色（hover / active / 边框 / 浅底）时，直接覆盖对应的 `--ccui-color-primary-hover` 等 CSS 变量即可。

## 三种方案怎么选

- 整站统一深色：在根元素切 `.dark` 类（**主推**），配合全局引入的 `darkTheme.css`。
- 仅局部子树深色：用 `c-config-provider` 的 `theme.algorithm: 'dark'` 包裹。
- 定制品牌色 / 圆角：用 `c-config-provider` 的 `theme.token`，或直接覆盖 `--ccui-*` 变量。


---

# TimePicker 时间选择框

> 文档链接：https://vaebe.github.io/ccui/components/time-picker/index.html

输入或选择时间的控件。三列（时 / 分 / 秒）滚动选择，可控制各列显示与步长，支持 `disabledHours` / `disabledMinutes` / `disabledSeconds` 屏蔽，支持 `showNow` 与 `showOk` 控制 footer 行为。

## 基本使用

最简单的用法，默认 `format: 'HH:mm:ss'`，`showOk: true`，需要点确定才提交。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" />
</template>
```

:::

## 选中即提交

把 `show-ok` 和 `show-now` 关闭后，点击单元格立即触发 `change` 并关闭面板。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" :show-ok="false" :show-now="false" />
</template>
```

:::

## 自定义格式

`format` 控制输入框展示与字符串解析；`valueFormat` 决定 `v-model` 输出形态。

- `valueFormat="string"`（默认）：按 `format` 输出字符串。
- `valueFormat="date"`：输出原生 `Date` 实例。
- `valueFormat="number"`：输出毫秒时间戳。

:::demo

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

const a = ref('')
const b = ref<Date | null>(null)
const c = ref<number | null>(null)
</script>

<template>
  <c-time-picker v-model="a" format="HH:mm" :show-second="false" />
  <c-time-picker v-model="b" value-format="date" />
  <c-time-picker v-model="c" value-format="number" />
</template>
```

:::

## 步长

`hour-step` / `minute-step` / `second-step` 控制各列步长。常见用法：5 分钟一档、30 秒一档。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" :minute-step="5" :second-step="15" />
</template>
```

:::

## 屏蔽时间

`disabled-hours` / `disabled-minutes` / `disabled-seconds` 返回不可选值的数组。`disabled-minutes` 接收当前选中小时，`disabled-seconds` 接收当前小时与分钟，可以做联动屏蔽（比如 9:00 之前禁选）。

:::demo

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

const value = ref('')

function disabledHours() {
  return Array.from({ length: 9 }, (_, i) => i)
}

function disabledMinutes(h: number) {
  if (h === 9) return [0, 1, 2, 3, 4]
  return []
}
</script>

<template>
  <c-time-picker v-model="value" :disabled-hours="disabledHours" :disabled-minutes="disabledMinutes" />
</template>
```

:::

## 隐藏某列

只选「时:分」或「时」，关掉对应列即可。

:::demo

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

const onlyHourMinute = ref('')
const onlyHour = ref('')
</script>

<template>
  <c-time-picker v-model="onlyHourMinute" format="HH:mm" :show-second="false" />
  <c-time-picker v-model="onlyHour" format="HH" :show-minute="false" :show-second="false" />
</template>
```

:::

## 三种尺寸

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" size="small" placeholder="small" />
  <c-time-picker v-model="value" placeholder="default" />
  <c-time-picker v-model="value" size="large" placeholder="large" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive({ meeting: '' })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { meeting: [{ required: true, message: '请选择会议时间' }] }
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="meeting" label="会议时间" prop="meeting">
      <c-time-picker v-model="form.meeting" />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()"> 校验 </c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" popup-append-to-body />
</template>
```

:::

## 12 小时制

打开 `use-12-hours` 后，小时列按 `[12, 1, 2, ..., 11]` 排列，并追加 AM / PM 列。未显式传 `format` 时，输入框默认按 `'h:mm:ss a'` 渲染。`disabled-hours` 仍按 24 小时数字配置，组件内部完成映射。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" use-12-hours />
  <p>v-model 值: {{ value }}</p>
</template>
```

:::

## 键盘导航

打开面板后 Tab 进入任意 cell（每个 cell 均为 `tabindex=0`），即可使用键盘切换：

- `ArrowUp` / `ArrowDown`：在当前列内上下移动（环绕到首 / 尾）。
- `Home` / `End`：跳到当前列首项 / 末项。
- `Enter`：相当于点击「确定」，或在 `show-ok=false` 时关闭面板。
- `Escape`：关闭面板。

:::demo

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

const value = ref('')
</script>

<template>
  <c-time-picker v-model="value" />
</template>
```

:::

## 自动滚动到选中

弹层打开时，每一列会基于 `offsetTop` / `clientHeight` 自动计算 `scrollTop`，将当前选中项滚动到列中央。下例预置 `14:30:45`，展开面板即可看到三列均已对齐到选中行。

:::demo

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

const value = ref('14:30:45')
</script>

<template>
  <c-time-picker v-model="value" />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-time-picker v-model="value" :variant="variant" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
</script>
```

:::

## 自定义单元格 cell slot

`#cell` slot 以 `{ value, type, label, selected, disabled }` 作 scope，可在不打破列布局的前提下追加业务标记（如「营业时段高亮」）。`type` 取值为 `'hour' | 'minute' | 'second' | 'period'`。

:::demo

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

const value = ref('10:30:00')

// 业务：营业时段（9:00 - 18:00）小时加底色
const BIZ_HOURS = new Set([9, 10, 11, 12, 13, 14, 15, 16, 17])
</script>

<template>
  <c-time-picker v-model="value">
    <template #cell="{ value: v, type, label }">
      <span :class="['my-time-cell', type === 'hour' && BIZ_HOURS.has(v) ? 'my-time-cell--biz' : '']">
        {{ label }}
      </span>
    </template>
  </c-time-picker>
</template>

<style scoped>
.my-time-cell--biz {
  color: #1677ff;
  font-weight: 600;
}
</style>
```

:::

## API

### Props

| 参数              | 类型                                                       | 默认值                  | 说明                                                                                                       |
| ----------------- | ---------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| modelValue        | string / Date / Dayjs / number / null                      | --                      | 当前选中时间，支持 `v-model`                                                                               |
| format            | string                                                     | `''`                    | 输入框显示与字符串解析格式（dayjs format token）；为空时按 `use12Hours` 兜底 `'h:mm:ss a'` 或 `'HH:mm:ss'` |
| use12Hours        | boolean                                                    | `false`                 | 12 小时制：小时列按 `[12, 1, ..., 11]` 排列并追加 AM / PM 列                                               |
| valueFormat       | `'string' \| 'date' \| 'number'`                           | `'string'`              | `v-model` 输出形态：按 format 字符串 / Date 实例 / 毫秒时间戳                                              |
| placeholder       | string                                                     | `请选择时间`            | 占位文案                                                                                                   |
| disabled          | boolean                                                    | `false`                 | 是否禁用                                                                                                   |
| clearable         | boolean                                                    | `true`                  | 是否显示清除按钮                                                                                           |
| size              | `'small' \| 'default' \| 'large'`                          | `'default'`             | 输入框尺寸                                                                                                 |
| status            | `'' \| 'error' \| 'warning' \| ...`                        | `''`                    | 校验状态；置于 `FormItem` 时自动继承                                                                       |
| placement         | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`          | 浮层方位                                                                                                   |
| popupClassName    | string                                                     | --                      | 浮层根元素自定义 class                                                                                     |
| popupAppendToBody | boolean                                                    | `false`                 | 是否把浮层 Teleport 到 `document.body`                                                                     |
| getPopupContainer | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                      | 自定义浮层挂载点，优先级高于 `popupAppendToBody`                                                           |
| autoFocus         | boolean                                                    | `false`                 | 挂载后自动 focus 输入框                                                                                    |
| inputReadOnly     | boolean                                                    | `true`                  | 输入框只读                                                                                                 |
| transitionName    | string                                                     | `ccui-time-picker-fade` | 浮层过渡名                                                                                                 |
| showHour          | boolean                                                    | `true`                  | 是否显示小时列                                                                                             |
| showMinute        | boolean                                                    | `true`                  | 是否显示分钟列                                                                                             |
| showSecond        | boolean                                                    | `true`                  | 是否显示秒列                                                                                               |
| hourStep          | number                                                     | `1`                     | 小时步长                                                                                                   |
| minuteStep        | number                                                     | `1`                     | 分钟步长                                                                                                   |
| secondStep        | number                                                     | `1`                     | 秒步长                                                                                                     |
| disabledHours     | `() => number[]`                                           | --                      | 不可选小时数组                                                                                             |
| disabledMinutes   | `(hour: number) => number[]`                               | --                      | 不可选分钟（接收当前选中小时联动）                                                                         |
| disabledSeconds   | `(hour: number, minute: number) => number[]`               | --                      | 不可选秒（接收当前小时分钟联动）                                                                           |
| showNow           | boolean                                                    | `true`                  | 是否显示「此刻」按钮                                                                                       |
| showOk            | boolean                                                    | `true`                  | 是否显示「确定」按钮；`false` 时点击单元格立即提交并关闭                                                   |
| nowText           | string                                                     | `此刻`                  | 「此刻」按钮文案                                                                                           |
| okText            | string                                                     | `确定`                  | 「确定」按钮文案                                                                                           |

### Events

| 事件名            | 回调签名                                    | 触发时机                           |
| ----------------- | ------------------------------------------- | ---------------------------------- |
| update:modelValue | `(value: string \| Date \| number \| null)` | 提交时间或清除时                   |
| change            | `(value, timeString: string)`               | 提交时间或清除时（带格式化字符串） |
| open-change       | `(open: boolean)`                           | 浮层打开 / 关闭时                  |
| focus             | --                                          | 输入框聚焦                         |
| blur              | --                                          | 输入框失焦                         |

### Slots

| 名称       | scope                                                                                                                      | 说明                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| cell       | `{ value: number; type: 'hour' \| 'minute' \| 'second' \| 'period'; label: string; selected: boolean; disabled: boolean }` | 自定义时间单元格内容；不传走默认 `label`（两位补零字符串） |
| clearIcon  | --                                                                                                                         | 自定义清除图标                                             |
| suffixIcon | --                                                                                                                         | 自定义时钟图标                                             |

## 范围选择 TimeRangePicker

时间区间选择请使用独立的 [`TimeRangePicker`](/components/time-range-picker/) 组件，`v-model` 是 `[start, end]` 元组，两端各自独立的 `disabled` / `allowEmpty` / `placeholder`。

## 已知限制（未交付）

- **showTime 嵌入 DatePicker**：DatePicker 推到 90% 时一并接通。
- **滚轮 snap**：打开时已可自动滚动到选中项（见上文 "自动滚动到选中"），但鼠标滚轮 / 触控板的 snap-to-cell 吸附交互暂未实现，留给后续。


---

# TimeRangePicker 时间范围选择

> 文档链接：https://vaebe.github.io/ccui/components/time-range-picker/index.html

时间区间选择控件，`v-model` 是 `[start, end]` 元组。两端各自独立的 TimePicker 面板，支持独立 `disabled` / `allowEmpty` / `placeholder`，可配 `order` 自动保序。

## 基本使用

`v-model` 直接绑定 `[start, end]` 数组。任一端为空时元组对应位置是 `null` 或空串（按 `value-format` 决定）。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-time-range-picker v-model="value" />
  <p>v-model：{{ value }}</p>
</template>
```

:::

## 自定义格式

`format` 决定输入与展示格式；`valueFormat` 决定 `v-model` 输出形态（string / date / number）。

:::demo

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

const value = ref<[string, string] | null>(['09:00', '18:00'])
</script>

<template>
  <c-time-range-picker v-model="value" format="HH:mm" />
</template>
```

:::

## 两端独立禁用 disabled

`disabled` 支持元组 `[boolean, boolean]`，分别锁两端输入。例如「开始可选 / 结束锁定」。

:::demo

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

const value = ref<[string, string] | null>(['09:00:00', '18:00:00'])
</script>

<template>
  <c-time-range-picker v-model="value" :disabled="[false, true]" />
</template>
```

:::

## 两端独立允许为空 allowEmpty

`allowEmpty` 接元组 `[boolean, boolean]`，分别配置「开始可空 / 结束可空」。业务侧常用「开始日期可空 / 结束日期必填」之类的不对称需求。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-time-range-picker v-model="value" :allow-empty="[true, false]" />
</template>
```

:::

## 自定义分隔符

`separator` 默认 `~`，可改成箭头 `→` 或文字 `至`。

:::demo

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

const value = ref<[string, string] | null>(null)
</script>

<template>
  <c-time-range-picker v-model="value" separator="→" />
  <c-time-range-picker v-model="value" separator="至" />
</template>
```

:::

## API

### Props

| 参数            | 类型                                                                  | 默认值       | 说明                                              |
| --------------- | --------------------------------------------------------------------- | ------------ | ------------------------------------------------- |
| modelValue      | `[DateValue, DateValue] \| null`                                      | --           | 时间范围元组，支持 `v-model`                      |
| format          | string                                                                | `''`         | 时间格式（dayjs token）；空时按 `use12Hours` 兜底 |
| valueFormat     | `'string' \| 'date' \| 'number'`                                      | `'string'`   | `v-model` 输出形态                                |
| use12Hours      | boolean                                                               | `false`      | 12 小时制                                         |
| placeholder     | `string \| [string, string]`                                          | --           | 占位文案；元组分别给两端                          |
| disabled        | `boolean \| [boolean, boolean]`                                       | `false`      | 是否禁用；元组分别锁两端                          |
| allowEmpty      | `boolean \| [boolean, boolean]`                                       | `false`      | 是否允许该端为空；元组分别配置                    |
| order           | boolean                                                               | `true`       | start > end 时自动交换                            |
| separator       | string                                                                | `~`          | 中间分隔符                                        |
| size            | `'small' \| 'default' \| 'large'`                                     | `'default'`  | 输入框尺寸                                        |
| status          | `'' \| 'error' \| 'warning' \| ...`                                   | `''`         | 校验状态                                          |
| placement       | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'`            | `bottomLeft` | 浮层方位                                          |
| clearable       | boolean                                                               | `true`       | 是否显示清除按钮                                  |
| showHour        | boolean                                                               | `true`       | 是否显示小时列                                    |
| showMinute      | boolean                                                               | `true`       | 是否显示分钟列                                    |
| showSecond      | boolean                                                               | `true`       | 是否显示秒列                                      |
| hourStep        | number                                                                | `1`          | 小时步进                                          |
| minuteStep      | number                                                                | `1`          | 分钟步进                                          |
| secondStep      | number                                                                | `1`          | 秒步进                                            |
| disabledHours   | `(which: 'start' \| 'end') => number[]`                               | --           | 按 which 区分两端的小时禁用                       |
| disabledMinutes | `(which: 'start' \| 'end', selectedHour: number) => number[]`         | --           | 按 which + 当前 hour 返回禁用分钟                 |
| disabledSeconds | `(which: 'start' \| 'end', selectedHour, selectedMinute) => number[]` | --           | 按 which + 时分返回禁用秒                         |

### Events

| 事件名            | 回调签名                      | 触发时机                           |
| ----------------- | ----------------------------- | ---------------------------------- |
| update:modelValue | `(value: [...] \| null)`      | 任一端变更或清除                   |
| change            | `(value, [startStr, endStr])` | 选中或清除时（带格式化字符串元组） |
| open-change       | `(open: boolean)`             | 任一端面板打开 / 关闭              |


---

# Timeline 时间线

> 文档链接：https://vaebe.github.io/ccui/components/timeline/index.html

可视化地呈现时间流信息。

## 何时使用

- 当有一系列信息需按时间排列时
- 需要有一条时间轴进行视觉上的串联时

## 基本使用

Timeline 可拆分成多个按照时间戳排列的活动，时间戳是其区分于其他控件的重要特征。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div class="demo-timeline-basic">
    <c-timeline>
      <c-timeline-item timestamp="2025/09/09">
        <p>更新 Github 模板</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/08">
        <p>更新 Github 模板</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/07">
        <p>更新 Github 模板</p>
      </c-timeline-item>
    </c-timeline>
  </div>
</template>

<style></style>
```

:::

## 自定义节点样式

可根据实际场景自定义节点尺寸、颜色，或直接使用图标。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div class="demo-timeline-node">
    <c-timeline>
      <c-timeline-item timestamp="2025/09/09" type="primary">
        <p>支持使用图标</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/08" color="#0bbd87">
        <p>支持自定义颜色</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/07" size="large">
        <p>支持自定义尺寸</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/06" type="warning" hollow>
        <p>支持空心点</p>
      </c-timeline-item>
    </c-timeline>
  </div>
</template>

<style></style>
```

:::

## 自定义时间戳

当内容在垂直方向上过高时，可将时间戳置于内容之上。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div class="demo-timeline-timestamp">
    <c-timeline>
      <c-timeline-item timestamp="2025/09/09" placement="top">
        <div>
          <h4>更新 Github 模板</h4>
          <p>Tom 在 2025/09/09 20:46 提交了更新</p>
        </div>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/08" placement="top">
        <div>
          <h4>更新 Github 模板</h4>
          <p>Tom 在 2025/09/08 20:46 提交了更新</p>
        </div>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/07" placement="top">
        <div>
          <h4>更新 Github 模板</h4>
          <p>Tom 在 2025/09/07 20:46 提交了更新</p>
        </div>
      </c-timeline-item>
    </c-timeline>
  </div>
</template>

<style></style>
```

:::

## 垂直居中

垂直居中样式的 Timeline-Item。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div class="demo-timeline-center">
    <c-timeline>
      <c-timeline-item timestamp="2025/09/09" center>
        <div>
          <h4>更新 Github 模板</h4>
          <p>Tom 在 2025/09/09 20:46 提交了更新</p>
        </div>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/08" center>
        <div>
          <h4>更新 Github 模板</h4>
          <p>Tom 在 2025/09/08 20:46 提交了更新</p>
        </div>
      </c-timeline-item>
    </c-timeline>
  </div>
</template>

<style></style>
```

:::

## 自定义节点

可以通过插槽自定义节点。

:::demo

```vue
<script>
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    return {}
  },
})
</script>

<template>
  <div class="demo-timeline-dot">
    <c-timeline>
      <c-timeline-item timestamp="2025/09/09">
        <template #dot>
          <div
            style="width: 16px; height: 16px; background: #409eff; border-radius: 50%; display: flex; align-items: center; justify-content: center;"
          >
            <span style="color: white; font-size: 10px;">✓</span>
          </div>
        </template>
        <p>自定义节点内容</p>
      </c-timeline-item>
      <c-timeline-item timestamp="2025/09/08" type="success">
        <p>普通节点</p>
      </c-timeline-item>
    </c-timeline>
  </div>
</template>

<style></style>
```

:::

## API

### Timeline Slots

| 插槽名  | 说明                          | 子标签        |
| ------- | ----------------------------- | ------------- |
| default | timeline 组件的自定义默认内容 | Timeline-Item |

### Timeline-Item Props

| 参数           | 说明           | 类型             | 可选值                                | 默认值 |
| -------------- | -------------- | ---------------- | ------------------------------------- | ------ |
| timestamp      | 时间戳         | string           | —                                     | ''     |
| hide-timestamp | 是否隐藏时间戳 | boolean          | —                                     | false  |
| center         | 是否垂直居中   | boolean          | —                                     | false  |
| placement      | 时间戳位置     | string           | top/bottom                            | bottom |
| type           | 节点类型       | string           | [TimelineItemType](#timelineitemtype) | —      |
| color          | 节点颜色       | string           | —                                     | —      |
| size           | 节点尺寸       | string           | normal/large                          | normal |
| icon           | 自定义图标     | string/Component | —                                     | —      |
| hollow         | 是否空心点     | boolean          | —                                     | false  |

### Timeline-Item Events

| 事件名 | 说明 | 回调参数 |
| ------ | ---- | -------- |
| —      | —    | —        |

### Timeline-Item Slots

| 插槽名  | 说明       |
| ------- | ---------- |
| default | 自定义内容 |
| dot     | 自定义节点 |

## Timeline类型定义

### TimelineItemType

```ts
export type TimelineItemType = 'primary' | 'success' | 'warning' | 'danger' | 'info' | ''
```


---

# Tooltip 文字提示

> 文档链接：https://vaebe.github.io/ccui/components/tooltip/index.html

常用于展示鼠标 hover 时的提示信息。

## 何时使用

- 鼠标移入则显示提示，移出消失，气泡浮层不承载复杂文本和操作
- 可用来代替系统默认的 title 提示，提供一个更好的用户体验
- 当某个页面元素需要解释或描述时

## 基本使用

最简单的用法，浮层的大小由内容区域决定。文本内容可通过 `content` 或同名 slot 传入。

:::demo

```vue
<template>
  <c-tooltip content="这是一段提示文字">
    <c-button type="primary" plain>鼠标悬停显示</c-button>
  </c-tooltip>
</template>
```

:::

## 12 个出现位置

通过 `placement` 控制方位。

:::demo

```vue
<script setup>
const tops = ['top-start', 'top', 'top-end']
const lefts = ['left-start', 'left', 'left-end']
const rights = ['right-start', 'right', 'right-end']
const bottoms = ['bottom-start', 'bottom', 'bottom-end']
</script>

<template>
  <div class="demo-tooltip-placement">
    <div class="row">
      <c-tooltip v-for="p in tops" :key="p" :content="`tooltip ${p}`" :placement="p">
        <c-button type="primary" plain>{{ p }}</c-button>
      </c-tooltip>
    </div>
    <div class="center">
      <div class="col">
        <c-tooltip v-for="p in lefts" :key="p" :content="`tooltip ${p}`" :placement="p">
          <c-button type="primary" plain>{{ p }}</c-button>
        </c-tooltip>
      </div>
      <div class="col">
        <c-tooltip v-for="p in rights" :key="p" :content="`tooltip ${p}`" :placement="p">
          <c-button type="primary" plain>{{ p }}</c-button>
        </c-tooltip>
      </div>
    </div>
    <div class="row">
      <c-tooltip v-for="p in bottoms" :key="p" :content="`tooltip ${p}`" :placement="p">
        <c-button type="primary" plain>{{ p }}</c-button>
      </c-tooltip>
    </div>
  </div>
</template>

<style scoped>
.demo-tooltip-placement {
  width: 420px;
  margin: 0 auto;
}
.demo-tooltip-placement .row {
  display: flex;
  justify-content: center;
  gap: 8px;
}
.demo-tooltip-placement .center {
  display: flex;
  justify-content: space-between;
  margin: 10px 0;
}
.demo-tooltip-placement .col {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.demo-tooltip-placement .ccui-button {
  width: 96px;
}
</style>
```

:::

## 内置主题

`effect` 提供 `dark` / `light` 两套内置背景；要更精细的颜色用 `color`。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="Dark 主题" effect="dark">
      <c-button type="primary" plain>Dark</c-button>
    </c-tooltip>
    <c-tooltip content="Light 主题" effect="light">
      <c-button type="primary" plain>Light</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 自定义背景色 color

`color` 优先于 `effect`，接受任意 CSS color，常用于品牌色 / 警告色提示。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="品牌蓝" color="#1677ff">
      <c-button type="primary" plain>蓝</c-button>
    </c-tooltip>
    <c-tooltip content="成功绿" color="#52c41a">
      <c-button type="primary" plain>绿</c-button>
    </c-tooltip>
    <c-tooltip content="警告红" color="#f5222d">
      <c-button type="primary" plain>红</c-button>
    </c-tooltip>
    <c-tooltip content="紫色渐变" color="linear-gradient(135deg, #722ed1, #eb2f96)">
      <c-button type="primary" plain>渐变</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 显隐箭头 show-arrow

通过 `show-arrow` 控制箭头显示/隐藏。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="默认带箭头" placement="top">
      <c-button type="primary" plain>带箭头</c-button>
    </c-tooltip>
    <c-tooltip content="无箭头" placement="top" :show-arrow="false">
      <c-button type="primary" plain>无箭头</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 多行 / HTML 内容

`#content` slot 支持任意 VNode；要把字符串当 HTML 渲染用 `rawContent`。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip placement="top">
      <template #content>
        <div>多行信息</div>
        <div>第二行信息</div>
      </template>
      <c-button type="primary" plain>多行</c-button>
    </c-tooltip>
    <c-tooltip content="<div style='color: #fff700'>HTML 内容</div>" :raw-content="true">
      <c-button type="primary" plain>HTML</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 触发方式

`hover` / `click` / `focus` / `manual` 四种。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="鼠标悬停触发" trigger="hover">
      <c-button type="primary" plain>Hover</c-button>
    </c-tooltip>
    <c-tooltip content="点击触发" trigger="click">
      <c-button type="primary" plain>Click</c-button>
    </c-tooltip>
    <c-tooltip content="聚焦触发" trigger="focus">
      <c-button type="primary" plain>Focus</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 延迟显示 / 隐藏

通过 `show-after` / `hide-after` 控制显隐延迟（ms）。

:::demo

```vue
<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="延迟 1 秒显示" :show-after="1000">
      <c-button type="primary" plain>延迟显示</c-button>
    </c-tooltip>
    <c-tooltip content="延迟 1 秒隐藏" :hide-after="1000">
      <c-button type="primary" plain>延迟隐藏</c-button>
    </c-tooltip>
  </div>
</template>
```

:::

## 禁用

`disabled=true` 时永远不触发显示。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const disabled = ref(false)
</script>

<template>
  <div style="display: flex; gap: 12px">
    <c-tooltip content="禁用状态" :disabled="disabled">
      <c-button type="primary" plain>{{ disabled ? '禁用' : '启用' }}</c-button>
    </c-tooltip>
    <c-button type="primary" plain @click="disabled = !disabled">切换状态</c-button>
  </div>
</template>
```

:::

## 受控显示 v-model:visible

`visible` 配合 `v-model:visible` 双向同步。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const visible = ref(false)
</script>

<template>
  <div style="display: flex; gap: 12px; align-items: center">
    <c-tooltip v-model:visible="visible" content="手动控制显示" trigger="manual">
      <c-button type="primary" plain>受控触发器</c-button>
    </c-tooltip>
    <c-button type="primary" plain @click="visible = !visible">
      {{ visible ? '隐藏' : '显示' }}
    </c-button>
    <span style="color: var(--ccui-color-text-secondary)">visible = {{ visible }}</span>
  </div>
</template>
```

:::

## show / hide 事件追踪

`before-show` / `show` / `before-hide` / `hide` 四个事件覆盖完整生命周期，常用于埋点。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const logs = ref([])
function log(type) {
  logs.value.unshift(`[${new Date().toLocaleTimeString()}] ${type}`)
  if (logs.value.length > 5) logs.value.length = 5
}
</script>

<template>
  <div style="display: flex; gap: 16px; align-items: flex-start">
    <c-tooltip
      content="hover 我观察事件"
      @before-show="log('before-show')"
      @show="log('show')"
      @before-hide="log('before-hide')"
      @hide="log('hide')"
    >
      <c-button type="primary" plain>触发器</c-button>
    </c-tooltip>
    <ul style="margin: 0; padding-left: 18px; color: var(--ccui-color-text-secondary); font-size: 12px">
      <li v-if="!logs.length">尚无事件</li>
      <li v-for="(log, i) in logs" :key="i">{{ log }}</li>
    </ul>
  </div>
</template>
```

:::

## 业务场景：图标提示

「图标 + Tooltip 文字解释」是后台管理表单 / 配置项最常见的辅助说明范式。

:::demo

```vue
<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div style="display: flex; align-items: center; gap: 6px">
      <span>邮箱地址</span>
      <c-tooltip content="用于接收账号通知与重置密码邮件" placement="right">
        <span
          style="display: inline-flex; width: 16px; height: 16px; border-radius: 50%; background: var(--ccui-area); color: var(--ccui-color-text-secondary); align-items: center; justify-content: center; font-size: 11px; cursor: help"
        >
          ?
        </span>
      </c-tooltip>
    </div>
    <div style="display: flex; align-items: center; gap: 6px">
      <span>API 密钥</span>
      <c-tooltip content="密钥泄露后请立即重置；不要提交到代码仓库" color="#f5222d" placement="right">
        <span
          style="display: inline-flex; width: 16px; height: 16px; border-radius: 50%; background: #fff1f0; color: #cf1322; align-items: center; justify-content: center; font-size: 11px; cursor: help"
        >
          !
        </span>
      </c-tooltip>
    </div>
  </div>
</template>
```

:::

## API

### Tooltip Props

| 参数                      | 说明                                                  | 类型                                         | 默认值 |
| ------------------------- | ----------------------------------------------------- | -------------------------------------------- | ------ |
| content                   | 浮层显示文本。也可用同名 `content` slot 传入富文本    | string                                       | —      |
| visible / v-model:visible | 受控显示状态                                          | boolean                                      | false  |
| placement                 | 出现位置（12 种）                                     | `'top' \| 'top-start' \| ... \| 'right-end'` | bottom |
| effect                    | 内置主题                                              | `'dark' \| 'light'`                          | dark   |
| color                     | 自定义背景色（覆盖 `effect`）                         | string                                       | —      |
| show-arrow                | 是否显示箭头                                          | boolean                                      | true   |
| show-after                | 鼠标进入触发显示的延迟（ms）                          | number                                       | 0      |
| hide-after                | 鼠标离开触发隐藏的延迟（ms）                          | number                                       | 200    |
| popper-class              | 浮层根节点 class                                      | string                                       | —      |
| trigger                   | 触发方式                                              | `'hover' \| 'focus' \| 'click' \| 'manual'`  | hover  |
| disabled                  | 是否禁用                                              | boolean                                      | false  |
| offset                    | 距触发器的偏移量（px）                                | number                                       | 8      |
| enterable                 | 鼠标是否可进入到 tooltip 中                           | boolean                                      | true   |
| raw-content               | 是否将 content 作为 HTML 字符串处理                   | boolean                                      | false  |
| fresh                     | 关闭后是否销毁内部内容                                | boolean                                      | false  |
| destroyTooltipOnHide      | 隐藏时销毁 tooltip 节点                               | boolean                                      | false  |
| autoAdjustOverflow        | 自动调整方向避免溢出（接 floating-ui flip）           | boolean                                      | true   |
| align                     | floating-ui offset / flip 等微调参数                  | object                                       | —      |
| getPopupContainer         | 自定义弹层容器（返回 `null` 不 Teleport）             | `(trigger) => HTMLElement \| null`           | —      |
| aria-label                | 屏幕阅读器标签                                        | string                                       | —      |

### Tooltip Events

| 事件名         | 说明                 | 回调参数 |
| -------------- | -------------------- | -------- |
| before-show    | 显示前触发           | —        |
| show           | 显示时触发           | —        |
| before-hide    | 隐藏前触发           | —        |
| hide           | 隐藏时触发           | —        |
| update:visible | v-model:visible 同步 | visible  |

### Tooltip Slots

| 插槽名  | 说明                                |
| ------- | ----------------------------------- |
| default | Tooltip 触发 & 引用的元素           |
| content | 自定义浮层内容（优先于 `content` prop） |


---

# Transfer 穿梭框

> 文档链接：https://vaebe.github.io/ccui/components/transfer/index.html

双列穿梭框。左侧"源"，右侧"目标"，通过中间按钮把选中项从一侧移到另一侧。常见于权限分配 / 字段挑选 / 角色管理等场景。

## 基本使用

`data-source` 给全集，`v-model:target-keys` 控制右侧 keys，`v-model:selected-keys` 控制双列勾选状态。

:::demo

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

const data = Array.from({ length: 8 }).map((_, i) => ({
  key: String(i),
  title: `内容 ${i}`,
  description: `描述 ${i}`,
}))
const target = ref<string[]>(['2', '3'])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer
    v-model:target-keys="target"
    v-model:selected-keys="selected"
    :data-source="data"
    :titles="['源', '目标']"
  />
</template>
```

:::

## 搜索

`show-search` 在两列上方各显示一个搜索框，按 `title`（或自定义 `filterOption`）过滤当前列。

:::demo

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

const data = ['Apple', 'Banana', 'Cherry', 'Durian', 'Elderberry'].map((t, i) => ({
  key: String(i),
  title: t,
}))
const target = ref<string[]>([])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer v-model:target-keys="target" v-model:selected-keys="selected" :data-source="data" show-search />
</template>
```

:::

## 自定义渲染

`render` 函数（或 `render` slot）自定义单项展示，可以加图标、副标题、tag 等。

:::demo

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

const data = [
  { key: '1', title: '管理员', description: '可读写' },
  { key: '2', title: '编辑', description: '可读写文档' },
  { key: '3', title: '访客', description: '只读' },
]
const target = ref<string[]>([])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer v-model:target-keys="target" v-model:selected-keys="selected" :data-source="data">
    <template #render="{ item }">
      <span
        ><strong>{{ item.title }}</strong> · <small style="color:var(--ccui-color-text-tertiary)">{{ item.description }}</small></span
      >
    </template>
  </c-transfer>
</template>
```

:::

## 禁用单项 / 整体

每条数据可单独 `disabled`；整体 `disabled` 让两列都失去交互。

:::demo

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

const data = [
  { key: '1', title: 'Apple' },
  { key: '2', title: 'Banana', disabled: true },
  { key: '3', title: 'Cherry' },
]
const target = ref<string[]>([])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer v-model:target-keys="target" v-model:selected-keys="selected" :data-source="data" />
</template>
```

:::

## 自定义文案

`titles` 替换列标题；`operations` 替换中间按钮文案；`locale` 替换搜索 placeholder / 空数据提示 / 单位词。

:::demo

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

const data = [
  { key: '1', title: 'Apple' },
  { key: '2', title: 'Banana' },
  { key: '3', title: 'Cherry' },
]
const target = ref<string[]>([])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer
    v-model:target-keys="target"
    v-model:selected-keys="selected"
    :data-source="data"
    :titles="['可选', '已选']"
    :operations="['加入', '移除']"
    :locale="{ itemUnit: '项', itemsUnit: '项', searchPlaceholder: '过滤', notFoundContent: '空' }"
    show-search
  />
</template>
```

:::

## 自定义全选区图标

`selections-icon` slot 在每列头部全选区追加一枚状态图标，scope 是 `{ direction, selectedCount, totalCount }`，可以根据「左/右列、当前已勾几个」切换图标。同名 prop 接 Iconify 名或 CSS 类名，slot 优先级更高。

:::demo

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

const data = [
  { key: '1', title: '管理员' },
  { key: '2', title: '编辑' },
  { key: '3', title: '访客' },
  { key: '4', title: '审计员' },
]
const target = ref<string[]>(['2'])
const selected = ref<string[]>([])
</script>

<template>
  <c-transfer
    v-model:target-keys="target"
    v-model:selected-keys="selected"
    :data-source="data"
    :titles="['可选角色', '已分配']"
  >
    <template #selections-icon="{ direction, selectedCount, totalCount }">
      <span v-if="direction === 'right'"><c-icon name="mdi:star" /> {{ selectedCount }}/{{ totalCount }}</span>
      <span v-else><c-icon name="mdi:checkbox-blank-outline" /> {{ selectedCount }}/{{ totalCount }}</span>
    </template>
  </c-transfer>
</template>
```

:::

## API

### Props

| 参数           | 类型                                                          | 默认值       | 说明                                                                    |
| -------------- | ------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------- |
| dataSource     | `TransferItem[]`                                              | `[]`         | 全部数据。`{ key, title?, description?, disabled? }`                    |
| targetKeys     | `string[]`                                                    | `[]`         | 在右侧（target）的 key 集合，支持 `v-model:targetKeys`                  |
| selectedKeys   | `string[]`                                                    | `[]`         | 跨两列勾选的 key，支持 `v-model:selectedKeys`                           |
| titles         | `[string, string]`                                            | `['', '']`   | 两列标题                                                                |
| operations     | `[string, string]`                                            | `['', '']`   | 中间按钮文案：[右移, 左移]；为空时回退到内置 chevron 图标               |
| showSearch     | boolean                                                       | `false`      | 显示搜索框                                                              |
| filterOption   | `(input: string, item: TransferItem) => boolean`              | --           | 自定义过滤；不传走默认 title 包含匹配                                   |
| disabled       | boolean                                                       | `false`      | 整体禁用                                                                |
| render         | `(item: TransferItem) => string \| VNode`                     | --           | 自定义单项渲染                                                          |
| locale         | `{ itemUnit, itemsUnit, notFoundContent, searchPlaceholder }` | --           | 自定义文案                                                              |
| pagination     | `boolean \| number`                                           | `false`      | 分页配置：`true` 用默认 pageSize=10，数字指定 pageSize                  |
| draggable      | boolean                                                       | `false`      | 是否允许右侧列表拖拽排序                                                |
| selectionsIcon | `string \| VNode`                                             | --           | 头部全选区状态图标，string 为 Iconify 名或 CSS 类。同名 slot 优先级更高 |

### Events

| 事件名              | 回调签名                                               | 触发时机                     |
| ------------------- | ------------------------------------------------------ | ---------------------------- |
| update:targetKeys   | `(keys: string[])`                                     | 移动后右侧 keys 变化         |
| update:selectedKeys | `(keys: string[])`                                     | 勾选 / 全选变化              |
| change              | `(targetKeys, direction: 'left' \| 'right', moveKeys)` | 点击移动按钮                 |
| select-change       | `(sourceSelectedKeys, targetSelectedKeys)`             | 双列勾选状态变化（拆出左右） |
| search              | `(direction: 'left' \| 'right', value: string)`        | 搜索框输入                   |

### Slots

| 名称            | 参数                                       | 说明                         |
| --------------- | ------------------------------------------ | ---------------------------- |
| render          | `{ item }`                                 | 自定义单项渲染               |
| selectAllLabels | `{ direction, selectedCount, totalCount }` | 自定义每列头部全选区标签内容 |
| selectionsIcon  | `{ direction, selectedCount, totalCount }` | 自定义每列头部全选区状态图标 |

## 已知限制（未交付）

- **虚拟滚动**：列表项 > 1000 时滚动不优化，复用 `use-virtual-list` 留后续。
- **direction='rtl'**：阿语等 RTL 语言下左右布局未做反转。


---

# Tree 树

> 文档链接：https://vaebe.github.io/ccui/components/tree/index.html

层级数据展示与管理：选中、勾选（含父子半选联动）、展开、异步加载、搜索高亮、自定义渲染、拖拽。

展开态用 `defaultExpandedKeys` / `expandedKeys` 或 `defaultExpandAll` 控制。

## 基本使用

不传 `expandedKeys` 时默认全部折叠。默认整行可点击触发展开 / 折叠 —— 设 `expandAction="false"` 改为仅 switcher 图标响应。

:::demo

```vue
<script setup lang="ts">
const data = [
  {
    key: '0-0',
    title: '一级 1',
    children: [
      { key: '0-0-0', title: '二级 1-1' },
      {
        key: '0-0-1',
        title: '二级 1-2',
        children: [
          { key: '0-0-1-0', title: '三级 1-2-1' },
          { key: '0-0-1-1', title: '三级 1-2-2' },
        ],
      },
    ],
  },
  { key: '0-1', title: '一级 2' },
]
</script>

<template>
  <c-tree :data="data" default-expand-all />
</template>
```

:::

## 展开方式 `expandAction`

`'click'`（默认）整行点击切换展开；`false` 仅 switcher 图标响应，行点击退化为纯选中。

:::demo

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

const rowClick = ref(true)
const data = [
  {
    key: 'src',
    title: 'src',
    children: [
      { key: 'main.ts', title: 'main.ts' },
      { key: 'app.vue', title: 'app.vue' },
    ],
  },
  { key: 'readme', title: 'README.md' },
]
</script>

<template>
  <c-switch v-model="rowClick" checked-children="整行" unchecked-children="仅图标" />
  <c-tree :data="data" :expand-action="rowClick ? 'click' : false" default-expand-all style="margin-top: 12px;" />
</template>
```

:::

## 受控 / 非受控

`v-model:selected-keys`、`v-model:expanded-keys`、`v-model:checked-keys` 都支持双向绑定；只想初始化用 `default-*` 系列。

:::demo

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

const selected = ref<string[]>([])
const expanded = ref<string[]>(['0-0'])
const data = [
  {
    key: '0-0',
    title: '组 A',
    children: [
      { key: '0-0-0', title: 'A-1' },
      { key: '0-0-1', title: 'A-2' },
    ],
  },
]
</script>

<template>
  <c-tree v-model:selected-keys="selected" v-model:expanded-keys="expanded" :data="data" />
  <p>已选：{{ selected.join(', ') || '(无)' }} ｜ 已展开：{{ expanded.join(', ') }}</p>
</template>
```

:::

## 多选

```vue
<c-tree multiple v-model:selected-keys="selected" :data="data" />
```

## 勾选 + 父子半选联动

`checkable` 开启复选框。默认勾选父级会勾选所有可勾选后代；后代部分勾选时父级显示半选；`checkStrictly` 关闭联动。

:::demo

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

const checked = ref<string[]>([])
const data = [
  {
    key: '0-0',
    title: '部门 A',
    children: [
      { key: '0-0-0', title: '小组 1' },
      { key: '0-0-1', title: '小组 2', disableCheckbox: true },
    ],
  },
  {
    key: '0-1',
    title: '部门 B',
    children: [
      { key: '0-1-0', title: '小组 3' },
      { key: '0-1-1', title: '小组 4' },
    ],
  },
]
</script>

<template>
  <c-tree v-model:checked-keys="checked" checkable default-expand-all :data="data" />
  <p>勾选：{{ checked.join(', ') || '(无)' }}</p>
</template>
```

:::

## fieldNames 字段名映射

```vue
<c-tree :data="data" :field-names="{ key: 'id', title: 'name', children: 'items' }" default-expand-all />
```

## 异步加载

`loadData` 在展开非叶子且尚未加载的节点时调用，返回 Promise。回调中给原始 node 写入 `children` 即可。

:::demo

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

const data = ref([
  { key: 'a', title: '可异步展开 A', isLeaf: false },
  { key: 'b', title: '可异步展开 B', isLeaf: false },
])

async function loadData(node: any) {
  await new Promise((resolve) => setTimeout(resolve, 400))
  node.children = [
    { key: `${node.key}-1`, title: `${node.title} - 子 1` },
    { key: `${node.key}-2`, title: `${node.title} - 子 2` },
  ]
}
</script>

<template>
  <c-tree :data="data" :load-data="loadData" />
</template>
```

:::

## 搜索 + 高亮

`searchValue` 自动按节点 title 模糊匹配并保留命中节点的祖先；命中部分会用 `__highlight` span 包裹便于自定义颜色。`filterTreeNode` 接受函数自定义匹配逻辑。

:::demo

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

const keyword = ref('1-2')
const data = [
  {
    key: '0-0',
    title: '一级 1',
    children: [
      { key: '0-0-0', title: '二级 1-1' },
      {
        key: '0-0-1',
        title: '二级 1-2',
        children: [
          { key: '0-0-1-0', title: '三级 1-2-1' },
          { key: '0-0-1-1', title: '三级 1-2-2' },
        ],
      },
    ],
  },
]
</script>

<template>
  <input v-model="keyword" placeholder="搜索节点 title" style="margin-bottom: 8px;" />
  <c-tree :data="data" :search-value="keyword" default-expand-all />
</template>
```

:::

## 自定义渲染

通过 `title` / `switcher` / `icon` 插槽自定义节点。`title` 插槽接收 `{ node, data, expanded }`，`switcher` 接收 `{ expanded, node }`。

:::demo

```vue
<script setup lang="ts">
const data = [
  { key: 'doc', title: '文档', icon: '📄' },
  {
    key: 'folder',
    title: '资料夹',
    icon: '📁',
    children: [{ key: 'sub', title: '子文档', icon: '📄' }],
  },
]
</script>

<template>
  <c-tree :data="data" default-expand-all>
    <template #title="{ node, expanded }">
      <strong style="color: var(--ccui-color-primary);">{{ node.raw.title }}</strong>
      <span v-if="expanded" style="margin-left: 8px; color: var(--ccui-color-text-tertiary);">(展开)</span>
    </template>
    <template #icon="{ node }">{{ node.raw.icon }}</template>
  </c-tree>
</template>
```

:::

## 键盘导航

将焦点设到 Tree 上后，可以用键盘漫游：

| 按键       | 行为                                        |
| ---------- | ------------------------------------------- |
| ↑ / ↓      | 上一个 / 下一个可见节点                     |
| →          | 折叠节点 → 展开；已展开 → 移到第一个子节点  |
| ←          | 已展开 → 折叠；已折叠 → 移到父节点          |
| Home / End | 首个 / 最后一个可见节点                     |
| Enter      | 选中聚焦节点（或勾选，若 `checkable=true`） |
| Space      | 同 Enter                                    |

`focusedKey` 支持受控（`v-model:focused-key`），事件 `focus-change` 同步外部状态。聚焦节点用 roving tabindex（仅它是 `tabindex=0`，其它都是 `-1`），保证 Tab 进入只到一个位置。

## 虚拟滚动

数据量大（数百 / 数千节点）时启用 `virtualScroll`，组件只渲染可视区 + 缓冲区：

```vue
<c-tree :data="hugeData" default-expand-all virtual-scroll :virtual-item-height="32" :virtual-max-height="400" />
```

键盘导航触发的焦点变化会自动滚到可见区。

## showLine 连接线

`showLine` 启用后，每个节点按祖先深度自动渲染垂直连接线。`connector` 插槽可以替换默认渲染：

:::demo

```vue
<script setup lang="ts">
const data = [
  {
    key: 'a',
    title: 'A',
    children: [
      { key: 'a1', title: 'A-1' },
      {
        key: 'a2',
        title: 'A-2',
        children: [{ key: 'a2-1', title: 'A-2-1' }],
      },
    ],
  },
]
</script>

<template>
  <c-tree :data="data" default-expand-all show-line />
</template>
```

:::

```vue
<!-- 自定义 connector 内容 -->
<c-tree :data="data" show-line>
  <template #connector="{ depth }">
    <span style="color: var(--ccui-color-border);">·</span>
  </template>
</c-tree>
```

## 拖拽 hover 自动展开

启用 `draggable` 后，把节点拖到一个折叠节点上停留 `dragHoverExpandDelay`（默认 600ms）会自动展开它，方便把节点拖入深层目录。设为 0 关闭该行为。

```vue
<c-tree :data="data" draggable :drag-hover-expand-delay="800" />
```

## 拖拽 auto-scroll

启用虚拟滚动或自定义滚动容器后，拖到顶/底边缘 `dragAutoScrollEdge`（默认 32px）以内时容器按 `dragAutoScrollSpeed`（默认 12px/帧）滚动。`dragAutoScroll=false` 关闭。

```vue
<c-tree
  :data="big"
  draggable
  virtual-scroll
  :virtual-max-height="240"
  :drag-auto-scroll-edge="48"
  :drag-auto-scroll-speed="20"
/>
```

## 异步加载错误重试

`loadData` 抛错时，对应节点的 switcher 切换成红色感叹号按钮，点击触发重试；同时 emit `load-error` 携带 `{ error, node }`。

```vue
<script setup lang="ts">
async function loadData(node: any) {
  if (Math.random() < 0.5) throw new Error('mock fail')
  node.children = [{ key: `${node.key}-1`, title: 'Loaded' }]
}
function onLoadError(info: { error: Error; node: any }) {
  console.warn('failed to load', info.node.key, info.error)
}
</script>

<template>
  <c-tree :data="data" :load-data="loadData" @load-error="onLoadError" />
</template>
```

或编程式重试 / 查询状态：

```vue
<script setup lang="ts">
import { ref } from 'vue'
const treeRef = ref<any>(null)

function retry(key: string) {
  treeRef.value?.retryLoad(key)
}
</script>

<template>
  <c-tree ref="treeRef" :data="data" :load-data="loadData" />
  <button @click="retry('lazy-1')">手动重试</button>
</template>
```

## 拖拽排序

`draggable` 开启后，`drop` 事件回调里给出 `{ event, node, dragNode, dropPosition }`。组件**不会**自动改写 `data`——业务侧根据 `dropPosition` 改造数据结构。

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

const data = ref([...])

function onDrop(info: { dragNode: any; node: any; dropPosition: 'before' | 'inside' | 'after' }) {
  // 业务自行从 data 中移动 dragNode 到 node 的 dropPosition 位置
  console.log(info)
}
</script>

<template>
  <c-tree :data="data" draggable default-expand-all @drop="onDrop" />
</template>
```

## Props

| 参数                 | 类型                                              | 默认值    | 说明                                                     |
| -------------------- | ------------------------------------------------- | --------- | -------------------------------------------------------- |
| data                 | `TreeNodeData[]`                                  | `[]`      | 树数据                                                   |
| fieldNames           | `{ key?, title?, children?, disabled?, isLeaf? }` | --        | 字段名映射                                               |
| selectable           | `boolean`                                         | `true`    | 是否允许选中                                             |
| multiple             | `boolean`                                         | `false`   | 是否允许多选                                             |
| selectedKeys         | `(string \| number)[]`                            | --        | 选中 key，配 `v-model:selected-keys` 接管                |
| defaultSelectedKeys  | `(string \| number)[]`                            | `[]`      | 初始选中 key                                             |
| checkable            | `boolean`                                         | `false`   | 是否显示勾选框                                           |
| checkedKeys          | `(string \| number)[]`                            | --        | 勾选 key，配 `v-model:checked-keys` 接管                 |
| defaultCheckedKeys   | `(string \| number)[]`                            | `[]`      | 初始勾选 key                                             |
| checkStrictly        | `boolean`                                         | `false`   | 关闭父子勾选联动                                         |
| expandedKeys         | `(string \| number)[]`                            | --        | 展开 key，配 `v-model:expanded-keys` 接管                |
| defaultExpandedKeys  | `(string \| number)[]`                            | `[]`      | 初始展开 key                                             |
| defaultExpandAll     | `boolean`                                         | `false`   | 初始展开所有节点                                         |
| disabled             | `boolean`                                         | `false`   | 整树禁用                                                 |
| loadData             | `(node) => Promise<void>`                         | --        | 异步加载子节点；展开未加载节点时调用                     |
| draggable            | `boolean`                                         | `false`   | 是否允许拖拽                                             |
| showLine             | `boolean`                                         | `false`   | 是否显示连接线（保留接口，样式可由消费者扩展）           |
| blockNode            | `boolean`                                         | `false`   | 是否独占整行                                             |
| expandAction         | `'click' \| false`                                | `'click'` | 点击节点正文是否切换展开；`false` 仅 switcher 图标可展开 |
| searchValue          | `string`                                          | `''`      | 搜索关键字（默认按 title 子串匹配）                      |
| filterTreeNode       | `(node, parentKeys) => boolean`                   | --        | 自定义过滤谓词，返回 true 命中                           |
| indentSize           | `number`                                          | `24`      | 每级缩进像素                                             |
| virtualScroll        | `boolean`                                         | `false`   | 启用虚拟滚动                                             |
| virtualItemHeight    | `number`                                          | `32`      | 虚拟滚动单项高度（px）                                   |
| virtualMaxHeight     | `number`                                          | `320`     | 虚拟滚动可视高度（px）                                   |
| focusedKey           | `string \| number`                                | --        | 聚焦节点 key，配 `v-model:focused-key` 接管              |
| dragHoverExpandDelay | `number`                                          | `600`     | 拖到 inside 区停留多少 ms 后自动展开，0 关闭             |
| dragAutoScroll       | `boolean`                                         | `true`    | 拖到滚动容器边缘自动滚动                                 |
| dragAutoScrollEdge   | `number`                                          | `32`      | 触发 auto-scroll 的边缘范围（px）                        |
| dragAutoScrollSpeed  | `number`                                          | `12`      | auto-scroll 每帧滚动距离（px）                           |

## 事件

| 事件                                         | 回调签名                                                                                        | 说明                 |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------- |
| update:selected-keys                         | `(keys)`                                                                                        | 选中变化（v-model）  |
| update:checked-keys                          | `(keys)`                                                                                        | 勾选变化（v-model）  |
| update:expanded-keys                         | `(keys)`                                                                                        | 展开变化（v-model）  |
| update:focused-key                           | `(key)`                                                                                         | 聚焦变化（v-model）  |
| focus-change                                 | `(key)`                                                                                         | 聚焦节点变化         |
| load-error                                   | `({ error, node })`                                                                             | 异步加载失败         |
| select                                       | `(keys, { selectedKeys, selected, node, event })`                                               | 选中变化             |
| check                                        | `(keys, { checkedKeys, halfCheckedKeys, checked, node, event })`                                | 勾选变化             |
| expand                                       | `(keys, { expanded, node })`                                                                    | 展开变化             |
| load                                         | `(loadedKeys, { node })`                                                                        | 异步加载完成         |
| drop                                         | `({ event, node, dragNode, dropPosition })` <br/> `dropPosition: 'before' / 'inside' / 'after'` | 拖拽放下             |
| dragstart / dragenter / dragover / dragleave | `({ event, node })`                                                                             | 标准拖拽生命周期事件 |

## 插槽

| 插槽      | 参数                                      | 说明                                           |
| --------- | ----------------------------------------- | ---------------------------------------------- |
| title     | `{ node, data, expanded }`                | 自定义节点标题                                 |
| switcher  | `{ expanded, node, loading, loadFailed }` | 自定义展开 / 折叠箭头（含 loading / 错误状态） |
| icon      | `{ node, expanded }`                      | 自定义节点前缀图标                             |
| connector | `{ depth, node }`                         | `showLine` 时每根连接线的内容                  |

## 组件方法（通过 ref 调用）

| 方法                 | 签名                     | 说明                                  |
| -------------------- | ------------------------ | ------------------------------------- |
| `retryLoad(key)`     | `(key) => Promise<void>` | 重试 `loadData`，常用于错误后手动恢复 |
| `isNodeLoading(key)` | `(key) => boolean`       | 节点是否正在异步加载                  |
| `hasLoadError(key)`  | `(key) => boolean`       | 节点最近一次 `loadData` 是否失败      |

## 类型

```ts
type TreeNodeKey = string | number

interface TreeNodeData {
  key?: TreeNodeKey
  title?: VNodeChild | string
  children?: TreeNodeData[]
  disabled?: boolean
  disableCheckbox?: boolean
  selectable?: boolean
  isLeaf?: boolean
  icon?: VNodeChild
  [key: string]: unknown
}

interface FlattenedTreeNode {
  key: TreeNodeKey
  raw: TreeNodeData
  title: VNodeChild | string
  level: number
  parentKeys: TreeNodeKey[]
  isLeaf: boolean
  disabled: boolean
  disableCheckbox: boolean
  selectable: boolean
  hasChildren: boolean
  childKeys: TreeNodeKey[]
}

type TreeDropPosition = 'before' | 'inside' | 'after'
```

## 协议要点

- `key` 必须唯一；不传则按渲染顺序自动生成 `__auto_n` 兜底。
- `disableCheckbox` 与 `disabled` 区分：前者只锁勾选，后者锁选中 + 勾选 + 拖拽。
- 父子勾选联动忽略 `disabled` / `disableCheckbox` 后代——它们不计入"全选"判定。
- `loadData` 完成后由消费者直接修改原 `node.children`，组件通过 reactive 检测重新平铺。
- `drop` 事件**不会**自动改 `data`——业务实现移动逻辑。


---

# TreeSelect 树选择

> 文档链接：https://vaebe.github.io/ccui/components/tree-select/index.html

把 `Tree` 嵌进下拉浮层做为选项面板的选择器。`v-model` 在单选模式下是单值（节点 value），多选模式下是 value 数组。多选默认渲染 checkbox（`treeCheckable=true`），关闭后回退到 `c-tree` 的 multiple selectable 模式。fieldNames 与 Cascader/Select 保持一致（`label/value/children/disabled`），内部映射到 `c-tree` 的 `title/key/...`。

## 单选

最简单用法。点击任意节点（含父节点）提交并关闭面板。

:::demo

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

const value = ref<string | null>(null)
const treeData = [
  {
    value: 'parent-1',
    label: '父节点 1',
    children: [
      { value: 'leaf-1-1', label: '叶子 1-1' },
      { value: 'leaf-1-2', label: '叶子 1-2' },
    ],
  },
  {
    value: 'parent-2',
    label: '父节点 2',
    children: [
      { value: 'leaf-2-1', label: '叶子 2-1' },
      { value: 'leaf-2-2', label: '叶子 2-2' },
    ],
  },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" tree-default-expand-all />
</template>
```

:::

## 多选（默认 checkable）

`multiple` 打开多选；默认 `treeCheckable=true`，节点前显示 checkbox。父节点勾选默认会带上子节点（除非 `treeCheckStrictly`）。多选模式下输入框渲染 tags，超过 `maxTagCount` 折叠成 `+ N`。

:::demo

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

const value = ref<string[] | null>(null)
const treeData = [
  {
    value: 'p1',
    label: '父 1',
    children: [
      { value: 'p1-1', label: '子 1-1' },
      { value: 'p1-2', label: '子 1-2' },
    ],
  },
  {
    value: 'p2',
    label: '父 2',
    children: [
      { value: 'p2-1', label: '子 2-1' },
      { value: 'p2-2', label: '子 2-2' },
    ],
  },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" multiple tree-default-expand-all :max-tag-count="2" />
</template>
```

:::

## treeCheckStrictly

开启后父子节点的勾选状态完全独立（勾父不连子，勾子不影响父）。

:::demo

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

const value = ref<string[] | null>(null)
const treeData = [
  {
    value: 'p1',
    label: '父 1',
    children: [
      { value: 'p1-1', label: '子 1-1' },
      { value: 'p1-2', label: '子 1-2' },
    ],
  },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" multiple tree-check-strictly tree-default-expand-all />
</template>
```

:::

## 多选 selectable（无 checkbox）

`treeCheckable=false` 时多选走 `c-tree` 的 multiple selectable 模式：不显示 checkbox，点击节点高亮并加入选中集合。

:::demo

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

const value = ref<string[] | null>(null)
const treeData = [
  {
    value: 'a',
    label: 'A',
    children: [{ value: 'a1', label: 'A1' }],
  },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" multiple :tree-checkable="false" tree-default-expand-all />
</template>
```

:::

## 自定义字段名 (fieldNames)

如果数据源字段不叫 `label / value / children / disabled`，用 `fieldNames` 映射。组件内部会自动转成 `c-tree` 期望的 `title / key / children / disabled`。

:::demo

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

const value = ref<string | null>(null)
const treeData = [
  {
    v: 'a',
    l: 'A',
    kids: [{ v: 'a1', l: 'A1' }],
  },
]
const fieldNames = { label: 'l', value: 'v', children: 'kids' }
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" :field-names="fieldNames" tree-default-expand-all />
</template>
```

:::

## 三种尺寸

:::demo

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

const value = ref<string | null>(null)
const treeData = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" size="small" />
  <c-tree-select v-model="value" :tree-data="treeData" />
  <c-tree-select v-model="value" :tree-data="treeData" size="large" />
</template>
```

:::

## 表单联动

放进 `c-form-item` 内时，`status` 会自动跟随 `FormItem` 的校验状态。

:::demo

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

const form = reactive<{ owner: string | null }>({ owner: null })
const formRef = ref<{ validate: () => Promise<boolean> } | null>(null)
const rules = { owner: [{ required: true, message: '请选择负责人' }] }
const treeData = [
  {
    value: 'team-a',
    label: '团队 A',
    children: [
      { value: 'alice', label: 'Alice' },
      { value: 'bob', label: 'Bob' },
    ],
  },
]
</script>

<template>
  <c-form ref="formRef" :model="form" :rules="rules" :label-col="{ span: 4 }" :wrapper-col="{ span: 20 }">
    <c-form-item name="owner" label="负责人" prop="owner">
      <c-tree-select v-model="form.owner" :tree-data="treeData" tree-default-expand-all />
    </c-form-item>
    <c-form-item :wrapper-col="{ span: 24 }">
      <c-button type="primary" @click="formRef?.validate()"> 校验 </c-button>
    </c-form-item>
  </c-form>
</template>
```

:::

## 弹层容器

把面板挂到 `document.body` 或自定义容器，避开 overflow 滚动裁切。

:::demo

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

const value = ref<string | null>(null)
const treeData = [{ value: 'a', label: 'A', children: [{ value: 'a1', label: 'A1' }] }]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" popup-append-to-body />
</template>
```

:::

## Variants

录入组件统一 `variant` 形态。四档：`outlined`（默认）/ `filled` / `borderless` / `underlined`。

:::demo

```vue
<template>
  <div style="margin-bottom: 12px">
    <c-segmented v-model="variant" :options="['outlined', 'filled', 'borderless', 'underlined']" />
  </div>
  <c-tree-select v-model="value" :variant="variant" :tree-data="data" placeholder="请选择" />
</template>

<script setup>
import { ref } from 'vue'
const variant = ref('outlined')
const value = ref('')
const data = [
  {
    key: '1',
    title: '父节点 1',
    children: [
      { key: '1-1', title: '叶子 1-1' },
      { key: '1-2', title: '叶子 1-2' },
    ],
  },
  { key: '2', title: '父节点 2' },
]
</script>
```

:::

## API

### Props

| 参数                    | 类型                                                       | 默认值                  | 说明                                                                            |
| ----------------------- | ---------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| modelValue              | `string \| number \| (string \| number)[] \| null`         | --                      | 选中值（单选时为单值，多选时为数组）                                            |
| treeData                | `TreeNodeData[]`                                           | `[]`                    | 数据源（递归 children）                                                         |
| fieldNames              | `{ label?, value?, children?, disabled? }`                 | `{}`                    | 字段名映射                                                                      |
| multiple                | boolean                                                    | `false`                 | 是否多选                                                                        |
| treeCheckable           | boolean                                                    | `true`                  | 多选模式下是否在节点前展示 checkbox（false 则走 multiple selectable）           |
| treeCheckStrictly       | boolean                                                    | `false`                 | 多选 + checkable 时，父子节点是否严格独立                                       |
| treeDefaultExpandAll    | boolean                                                    | `false`                 | 默认全部展开                                                                    |
| treeDefaultExpandedKeys | `(string \| number)[]`                                     | `[]`                    | 默认展开的节点 keys                                                             |
| placeholder             | string                                                     | `请选择`                | 占位文案                                                                        |
| disabled                | boolean                                                    | `false`                 | 是否禁用                                                                        |
| clearable               | boolean                                                    | `true`                  | 是否显示清除按钮                                                                |
| size                    | `'small' \| 'default' \| 'large'`                          | `'default'`             | 输入框尺寸                                                                      |
| status                  | `'' \| 'error' \| 'warning' \| ...`                        | `''`                    | 校验状态；置于 `FormItem` 时自动继承                                            |
| placement               | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `'bottomLeft'`          | 浮层方位                                                                        |
| popupClassName          | string                                                     | --                      | 浮层根元素自定义 class                                                          |
| popupAppendToBody       | boolean                                                    | `false`                 | 是否把浮层 Teleport 到 `document.body`                                          |
| getPopupContainer       | `(trigger: HTMLElement \| null) => HTMLElement \| null`    | --                      | 自定义浮层挂载点                                                                |
| autoFocus               | boolean                                                    | `false`                 | 挂载后自动 focus 输入框                                                         |
| inputReadOnly           | boolean                                                    | `true`                  | 输入框只读（仅单选模式有 input 元素）                                           |
| transitionName          | string                                                     | `ccui-tree-select-fade` | 浮层过渡名                                                                      |
| maxTagCount             | number                                                     | `3`                     | 多选模式输入框最多渲染几个 tag                                                  |
| notFoundContent         | string                                                     | `暂无数据`              | 空数据文案                                                                      |
| popupMaxHeight          | number                                                     | `280`                   | 浮层最大高度（px）                                                              |
| showSearch              | `boolean \| TreeSelectShowSearchConfig`                    | `false`                 | 是否开启搜索过滤；对象形态 `{ filterTreeNode?, treeNodeFilterProp? }`           |
| searchPlaceholder       | string                                                     | `搜索`                  | 搜索框占位文案（`showSearch` 启用时生效；走 ConfigProvider locale 兜底）        |
| loadData                | `(node: TreeNodeData) => Promise<void>`                    | --                      | 异步加载子节点；与节点的 `isLeaf=false` 配合，resolve 后向 node.children mutate |

### Events

| 事件名               | 回调签名                                                  | 触发时机                          |
| -------------------- | --------------------------------------------------------- | --------------------------------- |
| update:modelValue    | `(value: string \| number \| (string\|number)[] \| null)` | 选中变化或清除时                  |
| change               | `(value, labels: string[])`                               | 选中变化或清除时（带 label 数组） |
| popup-visible-change | `(open: boolean)`                                         | 浮层打开 / 关闭时                 |
| focus                | --                                                        | 输入框聚焦                        |
| blur                 | --                                                        | 输入框失焦                        |

## 搜索过滤 showSearch

设置 `showSearch=true` 在浮层顶部渲染搜索框，默认按节点 label 子串匹配（大小写不敏感），命中的节点及其祖先都会显示。

:::demo

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

const value = ref<string | null>(null)
const treeData = [
  {
    value: 'beijing',
    label: '北京',
    children: [
      { value: 'haidian', label: '海淀区' },
      { value: 'chaoyang', label: '朝阳区' },
      { value: 'xicheng', label: '西城区' },
    ],
  },
  {
    value: 'shanghai',
    label: '上海',
    children: [
      { value: 'pudong', label: '浦东新区' },
      { value: 'huangpu', label: '黄浦区' },
      { value: 'minhang', label: '闵行区' },
    ],
  },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" show-search tree-default-expand-all />
</template>
```

:::

## 自定义过滤逻辑 filterTreeNode

`showSearch` 对象形态 `{ filterTreeNode, treeNodeFilterProp }`：`filterTreeNode(input, node)` 自定义命中规则；`treeNodeFilterProp` 切到非 label 字段做子串匹配。

:::demo

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

const value = ref<string | null>(null)
const treeData = [
  {
    value: 'fe',
    label: '前端',
    pinyin: 'qianduan',
    children: [
      { value: 'vue', label: 'Vue.js', pinyin: 'vue' },
      { value: 'react', label: 'React', pinyin: 'react' },
    ],
  },
  {
    value: 'be',
    label: '后端',
    pinyin: 'houduan',
    children: [
      { value: 'go', label: 'Go', pinyin: 'go' },
      { value: 'node', label: 'Node.js', pinyin: 'node' },
    ],
  },
]

// 业务：拼音 + label 双字段匹配
function filterTreeNode(input: string, node: Record<string, unknown>) {
  if (!input) return true
  const kw = input.toLowerCase()
  return String(node.label).toLowerCase().includes(kw) || String(node.pinyin).includes(kw)
}
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" :show-search="{ filterTreeNode }" tree-default-expand-all />
</template>
```

:::

## 异步加载子节点 loadData

`loadData(node)` 返回 Promise；resolve 后向 node.children 写入数据并触发响应式更新。父节点须显式 `isLeaf: false` 才会触发懒加载。

:::demo

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

const value = ref<string | null>(null)
const treeData = reactive([
  { value: 'org-a', label: '部门 A', isLeaf: false },
  { value: 'org-b', label: '部门 B', isLeaf: false },
])

async function loadData(node: { value: string; label: string; children?: unknown[] }) {
  await new Promise((r) => setTimeout(r, 500))
  // mutate 注入子节点
  node.children = [
    { value: `${node.value}-1`, label: `${node.label} 小组 1` },
    { value: `${node.value}-2`, label: `${node.label} 小组 2` },
  ]
}
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" :load-data="loadData" placeholder="点开节点触发懒加载" />
</template>
```

:::

## 键盘导航

输入框聚焦后支持：

- `Enter` / `Space` / `↓`：打开面板
- `Esc` / `Tab`：关闭面板
- 面板打开后 `↑ ↓ ← →` / `Enter` 由 `c-tree` 接管（移动 focus / 展开收起 / 选中）

`showSearch` 启用时，搜索框聚焦后方向键 / `Enter` 仍会转发到 tree。

:::demo

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

const value = ref<string | null>(null)
const treeData = [
  {
    value: '1',
    label: '部门 A',
    children: [
      { value: '1-1', label: '小组 1' },
      { value: '1-2', label: '小组 2' },
    ],
  },
  { value: '2', label: '部门 B' },
]
</script>

<template>
  <c-tree-select v-model="value" :tree-data="treeData" tree-default-expand-all placeholder="聚焦后按方向键试试" />
</template>
```

:::

## 顶层常量

`showCheckedStrategy` 的取值常量：**不挂命名空间**，从 `@vaebe/ccui` 顶层 export。

```ts
import { TREE_SELECT_SHOW_ALL, TREE_SELECT_SHOW_CHILD, TREE_SELECT_SHOW_PARENT } from '@vaebe/ccui'

// TREE_SELECT_SHOW_PARENT === 'SHOW_PARENT'
// TREE_SELECT_SHOW_CHILD  === 'SHOW_CHILD'
// TREE_SELECT_SHOW_ALL    === 'SHOW_ALL'
```

| 常量                    | 说明                                                    |
| ----------------------- | ------------------------------------------------------- |
| TREE_SELECT_SHOW_PARENT | `showCheckedStrategy` 取值：父子都选中时只输出父节点    |
| TREE_SELECT_SHOW_CHILD  | `showCheckedStrategy` 取值：只输出叶子节点              |
| TREE_SELECT_SHOW_ALL    | `showCheckedStrategy` 取值：输出所有选中节点（父 + 子） |

> 当前 TreeSelect 尚未接入 `showCheckedStrategy` 这条 API；常量先 export 出去，方便外部代码提前引用，待后续接入实际逻辑时直接对接。

## 已知限制（未交付）

- **showCheckedStrategy**：多选 checkable 模式下，输出的 v-model 总是 `c-tree` 的 `checkedKeys` 全集；不暴露 `SHOW_PARENT` / `SHOW_CHILD` / `SHOW_ALL` 切换。常量符号已顶层 export，未来接入实际逻辑后即可直接使用。
- **半选 v-model 输出**：多选模式 v-model 不携带 `halfCheckedKeys`（业务需要时可监听 `c-tree` 的 check 事件自取）。


---

# Typography 排版

> 文档链接：https://vaebe.github.io/ccui/components/typography/index.html

文本内容的基本格式。

## 何时使用

- 文章 / 博客 / 详情页中的标题、段落、引用、链接。
- 需要一组语义化的文本类型（强调、次要、错误等）。

## 基本使用

`<c-typography>` 是排版的容器，里面可以放 Title / Paragraph / Text / Link。

:::demo

```vue
<template>
  <c-typography>
    <c-typography-title>Introduction</c-typography-title>
    <c-typography-paragraph>
      In the process of internal desktop applications development, many different design specs and implementations would
      be involved.
    </c-typography-paragraph>
    <c-typography-paragraph>
      After massive project practice and summaries, a coherent design language for background applications can take
      shape.
    </c-typography-paragraph>
    <c-typography-title :level="2">Guidelines and Resources</c-typography-title>
    <c-typography-paragraph>
      <c-typography-link href="#">Design system</c-typography-link>
      <c-typography-text> · </c-typography-text>
      <c-typography-text type="secondary">A UI design language</c-typography-text>
    </c-typography-paragraph>
  </c-typography>
</template>
```

:::

## 五级标题

`level` 取 1–5，对应 `<h1>`–`<h5>`。

:::demo

```vue
<template>
  <c-typography-title>h1. Title</c-typography-title>
  <c-typography-title :level="2">h2. Title</c-typography-title>
  <c-typography-title :level="3">h3. Title</c-typography-title>
  <c-typography-title :level="4">h4. Title</c-typography-title>
  <c-typography-title :level="5">h5. Title</c-typography-title>
</template>
```

:::

## 语义化文本

`type` 表达"次要 / 成功 / 警告 / 危险"四种语义。

:::demo

```vue
<template>
  <c-typography-text>Default</c-typography-text>
  <br />
  <c-typography-text type="secondary">Secondary</c-typography-text>
  <br />
  <c-typography-text type="success">Success</c-typography-text>
  <br />
  <c-typography-text type="warning">Warning</c-typography-text>
  <br />
  <c-typography-text type="danger">Danger</c-typography-text>
  <br />
  <c-typography-text disabled>Disabled</c-typography-text>
</template>
```

:::

## 文本样式装饰

可叠加：`mark` 高亮 / `code` 代码 / `keyboard` 键盘 / `underline` 下划线 / `delete` 删除线 / `strong` 加粗 / `italic` 斜体。

:::demo

```vue
<template>
  <c-typography-text mark>Marked</c-typography-text>&nbsp; <c-typography-text code>code()</c-typography-text>&nbsp;
  <c-typography-text keyboard>Cmd+K</c-typography-text>&nbsp;
  <c-typography-text underline>Underline</c-typography-text>&nbsp;
  <c-typography-text delete>Deleted</c-typography-text>&nbsp; <c-typography-text strong>Strong</c-typography-text>&nbsp;
  <c-typography-text italic>Italic</c-typography-text>
</template>
```

:::

## 链接

`<c-typography-link>` 与 `<a>` 用法一致，自动附带主色 / hover 风格。

:::demo

```vue
<template>
  <c-typography-link href="https://vuejs.org" target="_blank">Vue.js 官网</c-typography-link>
  <br />
  <c-typography-link href="#" type="warning">警告链接</c-typography-link>
  <br />
  <c-typography-link href="#" disabled>禁用链接</c-typography-link>
</template>
```

:::

## 段落组合

实战示例：用 Typography 组合标题 / 段落 / 链接构成一个迷你文章页。

:::demo

```vue
<template>
  <c-typography style="max-width: 720px">
    <c-typography-title>设计语言与组件库</c-typography-title>
    <c-typography-paragraph type="secondary">
      在企业级中后台体系中，统一的设计语言是规模化协作的基石。
    </c-typography-paragraph>
    <c-typography-title :level="3">为什么需要组件库？</c-typography-title>
    <c-typography-paragraph>
      把<c-typography-text mark>设计 token</c-typography-text>沉淀到组件，避免每个页面重新发明轮子；
      把<c-typography-text code>常见交互</c-typography-text>抽象成统一行为，降低用户认知负担。
    </c-typography-paragraph>
    <c-typography-paragraph>
      详细方法可参考
      <c-typography-link href="#">设计指南</c-typography-link>。
    </c-typography-paragraph>
  </c-typography>
</template>
```

:::

## 可复制（copyable）

文本右侧渲染复制按钮，点击调用 `navigator.clipboard.writeText`。3 秒后图标自动恢复。

::: tip 自定义复制图标

通过 **slot `copy-icon`** + scope `{ copied }` 自定义图标，渲染回调式 API 一律走 slot（数据元组 `tooltips: [before, after]` 保留为 prop）。

:::

### 基本复制

最简形式 `:copyable="true"`，复制文字 = 显示文字。

:::demo

```vue
<template>
  <c-typography-text :copyable="true">复制这段文本</c-typography-text>
</template>
```

:::

### 复制不同的文本（cfg.text）

显示一段、复制另一段；典型场景是显示脱敏文本而复制原值。

:::demo

```vue
<template>
  <c-typography-text :copyable="{ text: 'sk-fullsecret123456' }">
    sk-***456（点 <c-icon name="mdi:content-copy" /> 复制完整 token）
  </c-typography-text>
</template>
```

:::

### onCopy 回调与计数

复制完成后触发 `onCopy(text)`，可用于埋点 / 提示 / 计数。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const count = ref(0)
const lastText = ref('')

function handleCopy(text) {
  count.value += 1
  lastText.value = text
}
</script>

<template>
  <c-typography-text :copyable="{ onCopy: handleCopy }">复制我看看</c-typography-text>
  <br />
  <span style="color: var(--ccui-color-text-secondary); font-size: 13px">
    已复制 {{ count }} 次<span v-if="lastText">，上次内容：「{{ lastText }}」</span>
  </span>
</template>
```

:::

### 自定义 tooltips（hover 文字）

`tooltips: [复制前, 复制后]` 替换默认 `['复制', '已复制']`；传 `false` 完全关闭 hover title。

:::demo

```vue
<template>
  <c-typography-text :copyable="{ tooltips: ['点我复制', '搞定！'] }"> 自定义 hover 文字 </c-typography-text>
  <br />
  <c-typography-text :copyable="{ tooltips: false }"> 不显示 hover 提示 </c-typography-text>
</template>
```

:::

### 自定义图标（copy-icon slot）

slot 接收 `{ copied }` 作用域参数，可根据复制态切换图标。

:::demo

```vue
<template>
  <c-typography-text :copyable="true">
    带自定义 icon
    <template #copy-icon="{ copied }">
      {{ copied ? '✅ 已复制' : '📋' }}
    </template>
  </c-typography-text>
</template>
```

:::

### 短延时（copyableDelay）

`copyableDelay` 控制复制后图标恢复的毫秒数（默认 3000），可改为更激进的 800ms。

:::demo

```vue
<template>
  <c-typography-text :copyable="{ copyableDelay: 800 }"> 快速恢复（0.8s） </c-typography-text>
</template>
```

:::

### 在 Title / Paragraph / Link 上的复制

`copyable` 是 Text / Title / Paragraph / Link 4 组件共享 prop。

:::demo

```vue
<template>
  <c-typography-title :level="4" :copyable="true"> 可复制的 H4 标题 </c-typography-title>
  <c-typography-paragraph :copyable="true"> 可复制的段落。Lorem ipsum dolor sit amet. </c-typography-paragraph>
  <c-typography-link href="#" :copyable="{ text: 'https://example.com/full' }"> 可复制的链接 </c-typography-link>
</template>
```

:::

### CopyableConfig

| 字段          | 类型                        | 默认                | 说明                                           |
| ------------- | --------------------------- | ------------------- | ---------------------------------------------- |
| text          | string                      | slot.text           | 实际复制的文本；不传则取 default slot 的纯文本 |
| copyableDelay | number                      | `3000`              | 复制后图标恢复延时（ms）                       |
| tooltips      | `[string, string] \| false` | `['复制','已复制']` | 鼠标 hover 时的 title 文字（hover tooltip）    |
| onCopy        | `(text: string) => void`    | —                   | 复制完成回调                                   |

### slot

| 名称      | 作用域       | 说明                                  |
| --------- | ------------ | ------------------------------------- |
| copy-icon | `{ copied }` | 自定义复制按钮 icon（替代默认 ⎘ / ✓） |

## 可编辑（editable）

点击编辑按钮（或文本本身，配置 `triggerType: ['text']`）切入 textarea 内联编辑；Enter 提交、Escape 取消，blur 自动提交。

### 基本编辑

点 ✎ 进入编辑态；textarea 自动 focus；Enter 提交，Escape 取消。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('点 ✎ 编辑我')
</script>

<template>
  <c-typography-text :editable="{ text, onChange: (v) => (text = v) }">
    {{ text }}
  </c-typography-text>
</template>
```

:::

### 点文本即编辑（triggerType=['text']）

省去 icon，点击文本本身进入编辑态；适合「就地修改」场景。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('点这段文字试试')
</script>

<template>
  <c-typography-text
    :editable="{
      text,
      triggerType: ['text'],
      onChange: (v) => (text = v),
    }"
  >
    {{ text }}
  </c-typography-text>
</template>
```

:::

### icon + text 双触发

两种触发方式可以组合，点 icon 或文本都能进入编辑。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('点 icon 或点文字都可以')
</script>

<template>
  <c-typography-text
    :editable="{
      text,
      triggerType: ['icon', 'text'],
      onChange: (v) => (text = v),
    }"
  >
    {{ text }}
  </c-typography-text>
</template>
```

:::

### maxLength 限制

限制最大字符数；超出后 textarea 原生阻断输入。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('最多 10 个字符')
</script>

<template>
  <c-typography-text
    :editable="{
      text,
      maxLength: 10,
      onChange: (v) => (text = v),
    }"
  >
    {{ text }}
  </c-typography-text>
  <br />
  <span style="color: var(--ccui-color-text-secondary); font-size: 13px">当前 {{ text.length }} / 10 字</span>
</template>
```

:::

### onStart / onCancel / onEnd 三态回调

完整生命周期：进入 → 修改 → 提交（onChange + onEnd）或 取消（onCancel）。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('编辑追踪 demo')
const log = ref([])

function push(msg) {
  log.value.unshift(`${new Date().toLocaleTimeString()}  ${msg}`)
  if (log.value.length > 5) log.value.length = 5
}
</script>

<template>
  <c-typography-text
    :editable="{
      text,
      onStart: () => push('进入编辑'),
      onChange: (v) => {
        text = v
        push(`提交：${v}`)
      },
      onCancel: () => push('Escape 取消'),
      onEnd: () => push('编辑结束'),
    }"
  >
    {{ text }}
  </c-typography-text>
  <ul style="color: var(--ccui-color-text-secondary); font-size: 12px; margin-top: 8px">
    <li v-for="l in log" :key="l">{{ l }}</li>
  </ul>
</template>
```

:::

### 自定义 edit-icon

通过 `#edit-icon` slot 替换默认 ✎ 图标。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('自定义 icon')
</script>

<template>
  <c-typography-text :editable="{ text, onChange: (v) => (text = v), tooltip: '点我编辑' }">
    {{ text }}
    <template #edit-icon>🖊️</template>
  </c-typography-text>
</template>
```

:::

### 用 @update:editable-text 同步外部状态

除 `onChange`，组件还会 emit `update:editable-text` 事件，可直接监听同步外部 ref（与 `onChange` 二选一即可）。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref('emit 同步')
</script>

<template>
  <c-typography-text :editable="{ text }" @update:editable-text="text = $event">
    {{ text }}
  </c-typography-text>
  <br />
  <span style="color: var(--ccui-color-text-secondary); font-size: 13px">外部 ref：「{{ text }}」</span>
</template>
```

:::

### EditableConfig

| 字段        | 类型                      | 默认       | 说明                              |
| ----------- | ------------------------- | ---------- | --------------------------------- |
| triggerType | `Array<'icon' \| 'text'>` | `['icon']` | 编辑触发方式                      |
| tooltip     | `string \| false`         | —          | icon hover tooltip 文字           |
| editing     | boolean                   | —          | 受控编辑态                        |
| text        | string                    | slot.text  | 初始编辑文本                      |
| maxLength   | number                    | —          | 最大字符数                        |
| onStart     | `() => void`              | —          | 进入编辑回调                      |
| onChange    | `(value: string) => void` | —          | Enter 提交时回调                  |
| onCancel    | `() => void`              | —          | Escape 取消时回调                 |
| onEnd       | `() => void`              | —          | 编辑完成回调（onChange 之后触发） |

### slot

| 名称      | 作用域 | 说明                              |
| --------- | ------ | --------------------------------- |
| edit-icon | —      | 自定义编辑按钮 icon（替代默认 ✎） |

## 截断（ellipsis）

文字超出指定行数自动截断；可配合 `expandable` 展开 / 收起，或 `tooltip` 鼠标 hover 看完整内容。

::: warning jsdom 不能测真实尺寸

`ellipsis` 的视觉效果靠 CSS `text-overflow: ellipsis` + `-webkit-line-clamp`。jsdom 无 layout 引擎，**测试只覆盖逻辑分支**（class 是否挂载 / slot 是否渲染 / expand state 切换 / title attribute），实际截断效果请在浏览器 demo 中肉眼验证。

:::

### 单行截断

最常见用法，`ellipsis: true` 等价于 `{ rows: 1 }`。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="true" style="max-width: 300px">
    这是一段很长的文字，单行截断，超出部分会被省略号代替。Lorem ipsum dolor sit amet consectetur adipisicing elit.
    Quisquam, voluptatum.
  </c-typography-paragraph>
</template>
```

:::

### 多行截断

`rows` 控制截断行数（基于 `-webkit-line-clamp`）。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="{ rows: 2 }" style="max-width: 360px">
    两行截断。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere?
  </c-typography-paragraph>
  <c-typography-paragraph :ellipsis="{ rows: 3 }" style="max-width: 360px">
    三行截断。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere? Doloribus
    excepturi nesciunt fuga, dolore minus eligendi tempora?
  </c-typography-paragraph>
  <c-typography-paragraph :ellipsis="{ rows: 5 }" style="max-width: 360px">
    五行截断。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere? Doloribus
    excepturi nesciunt fuga, dolore minus eligendi tempora? Excepturi animi corrupti, alias modi sapiente ipsam
    reiciendis. Atque rem culpa quam debitis pariatur eum laborum modi.
  </c-typography-paragraph>
</template>
```

:::

### 可展开（单向）

`expandable: true` 显示「展开」按钮；展开后按钮消失。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="{ rows: 2, expandable: true }" style="max-width: 360px">
    单向展开。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere?
  </c-typography-paragraph>
</template>
```

:::

### 可展开 + 可收起（collapsible）

`expandable: 'collapsible'` 展开后切「收起」按钮，可来回切换。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="{ rows: 2, expandable: 'collapsible' }" style="max-width: 360px">
    可来回切换。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere?
  </c-typography-paragraph>
</template>
```

:::

### 自定义展开 / 收起文字

`expand-text` 和 `collapse-text` slot 替换默认「展开」/「收起」。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="{ rows: 2, expandable: 'collapsible' }" style="max-width: 360px">
    自定义按钮文字。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere?
    <template #expand-text>▼ 展开更多</template>
    <template #collapse-text>▲ 收起内容</template>
  </c-typography-paragraph>
</template>
```

:::

### tooltip 显示完整内容

`tooltip: true` 用原生 `title` 属性显示完整内容；hover 鼠标即可看；`tooltip: '自定义文字'` 替换为指定字符串。

:::demo

```vue
<template>
  <c-typography-paragraph :ellipsis="{ tooltip: true }" style="max-width: 300px">
    Hover 我看完整内容。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum.
  </c-typography-paragraph>
  <c-typography-paragraph :ellipsis="{ tooltip: '提示：这是脱敏后的预览' }" style="max-width: 300px">
    Hover 看自定义 tooltip 文案。Lorem ipsum dolor sit amet consectetur.
  </c-typography-paragraph>
</template>
```

:::

### 受控展开（expanded）

外部 ref 控制展开态，配合自定义按钮做更复杂的交互。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const expanded = ref(false)
</script>

<template>
  <c-typography-paragraph :ellipsis="{ rows: 2, expanded, onExpand: (v) => (expanded = v) }" style="max-width: 360px">
    受控展开。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam, voluptatum, debitis quasi quaerat
    quibusdam earum sed odio nemo quos repudiandae illo ratione quod sequi animi cumque expedita facere?
  </c-typography-paragraph>
  <c-button @click="expanded = !expanded"> 外部按钮：{{ expanded ? '收起' : '展开' }} </c-button>
</template>
```

:::

### Title 也支持 ellipsis

`ellipsis` 在 Title 上同样生效（长标题截断常见）。

:::demo

```vue
<template>
  <c-typography-title :level="3" :ellipsis="{ rows: 1, tooltip: true }" style="max-width: 300px">
    超长标题示例 Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam.
  </c-typography-title>
</template>
```

:::

## 三大交互组合使用

`copyable` / `editable` / `ellipsis` 可同时启用——按 UI 顺序渲染「截断按钮 → 编辑按钮 → 复制按钮」。

:::demo

```vue
<script setup>
import { ref } from 'vue'
const text = ref(
  '这是一段可以编辑、可以复制、还可以截断展开的多功能文本。Lorem ipsum dolor sit amet consectetur adipisicing elit. Quisquam.',
)
</script>

<template>
  <c-typography-paragraph
    style="max-width: 360px"
    :copyable="{ text }"
    :editable="{ text, onChange: (v) => (text = v) }"
    :ellipsis="{ rows: 2, expandable: 'collapsible' }"
  >
    {{ text }}
  </c-typography-paragraph>
</template>
```

:::

### EllipsisConfig

| 字段       | 类型                          | 默认    | 说明                                                             |
| ---------- | ----------------------------- | ------- | ---------------------------------------------------------------- |
| rows       | number                        | `1`     | 截断行数（>1 走 `-webkit-line-clamp` 多行）                      |
| expandable | `boolean \| 'collapsible'`    | `false` | true 显示展开按钮；`'collapsible'` 同时支持展开 + 收起           |
| expanded   | boolean                       | —       | 受控展开态                                                       |
| tooltip    | `boolean \| string`           | `false` | true 显示 `title` 原生 tooltip（jsdom 友好）；字符串则用该字符串 |
| onExpand   | `(expanded: boolean) => void` | —       | 展开 / 收起回调                                                  |
| onEllipsis | `(clipped: boolean) => void`  | —       | 文本是否被截断的状态变化回调（v2.x 待接入实际 measure）          |

### slot

| 名称          | 作用域 | 说明                               |
| ------------- | ------ | ---------------------------------- |
| expand-text   | —      | 自定义「展开」按钮文字（替代默认） |
| collapse-text | —      | 自定义「收起」按钮文字（替代默认） |

## API

### Title Props

| 参数  | 类型                    | 默认值 | 说明     |
| ----- | ----------------------- | ------ | -------- |
| level | `1 \| 2 \| 3 \| 4 \| 5` | `1`    | 标题级别 |

### Link Props

| 参数   | 类型   | 默认值 | 说明        |
| ------ | ------ | ------ | ----------- |
| href   | string | —      | 链接地址    |
| target | string | —      | 链接 target |

### 通用 Props（Text / Paragraph / Title / Link）

| 参数      | 类型                                                | 默认值  | 说明     |
| --------- | --------------------------------------------------- | ------- | -------- |
| type      | `'secondary' \| 'success' \| 'warning' \| 'danger'` | —       | 文本类型 |
| disabled  | boolean                                             | `false` | 禁用     |
| mark      | boolean                                             | `false` | 高亮     |
| code      | boolean                                             | `false` | 代码样式 |
| keyboard  | boolean                                             | `false` | 键盘样式 |
| underline | boolean                                             | `false` | 下划线   |
| delete    | boolean                                             | `false` | 删除线   |
| strong    | boolean                                             | `false` | 加粗     |
| italic    | boolean                                             | `false` | 斜体     |


---

# Upload 上传

> 文档链接：https://vaebe.github.io/ccui/components/upload/index.html

文件上传控件。提供文件选择、拖拽接收、文件列表、删除四个核心能力。**组件不内置 HTTP 上传请求** —— 业务侧通过 `update:fileList` 拿到文件后自行发请求并回写状态，组件只负责 UI 与状态同步。

## 基本使用

`v-model:fileList` 绑定文件列表，点击按钮选择文件。

:::demo

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

const list = ref<Array<{ uid: string; name: string; status?: string }>>([])
</script>

<template>
  <c-upload v-model:fileList="list" />
  <pre style="margin-top: 12px; font-size: 12px">{{ list }}</pre>
</template>
```

:::

## 拖拽上传

`drag` 把按钮替换成拖拽区，支持点击 / 拖拽两种触发。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref<Array<{ uid: string; name: string }>>([])
</script>

<template>
  <c-upload v-model:fileList="list" drag />
</template>
```

:::

## 照片墙 listType="picture-card"

`listType="picture-card"` 把列表渲染成网格卡片（104×104），适合相册 / 头像批量上传 / 产品图等场景。有 `url` 字段时渲染缩略图，否则渲染占位图标；hover 卡片右上角显示删除按钮，点缩略图触发 `preview` 事件。

:::demo

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

const list = ref([
  { uid: '1', name: 'cover.jpg', status: 'done', url: 'https://picsum.photos/seed/cover/200' },
  { uid: '2', name: 'banner.png', status: 'done', url: 'https://picsum.photos/seed/banner/200' },
  { uid: '3', name: 'logo.svg', status: 'done' },
])
</script>

<template>
  <c-upload v-model:fileList="list" list-type="picture-card" multiple accept="image/*" trigger-text="+ 上传" />
</template>
```

:::

## 多选 + 类型限制

`multiple` 允许多选；`accept` 直接传给 native `<input>`，浏览器会根据 MIME 过滤。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref<Array<{ uid: string; name: string }>>([])
</script>

<template>
  <c-upload v-model:fileList="list" multiple accept="image/*" />
</template>
```

:::

## 数量与大小限制

- `max-count` 限制总数，超出的文件被丢弃 + 触发 `reject(file, 'maxCount')`
- `max-size` 限制单文件字节数，超出 + 触发 `reject(file, 'maxSize')`
- `before-upload` 同步过滤函数，返回 `false` 拒收 + 触发 `reject(file, 'beforeUpload')`

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref<Array<{ uid: string; name: string }>>([])

function onReject(file: File, reason: string) {
  alert(`拒绝 ${file.name}: ${reason}`)
}

function checkExt(file: File) {
  return file.name.endsWith('.txt')
}
</script>

<template>
  <c-upload
    v-model:fileList="list"
    multiple
    :max-count="3"
    :max-size="1024 * 1024"
    :before-upload="checkExt"
    @reject="onReject"
  />
</template>
```

:::

## 持续上传中状态

`default-status="uploading"` 让每个新文件初始为 uploading 状态。业务发完真实请求后，自己改为 `done` / `error`。

:::demo

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

const list = ref<Array<{ uid: string; name: string; status: string; percent: number }>>([])

function onChange(file: { uid: string }, next: typeof list.value) {
  list.value = next
  // 模拟一个 1.5s 的上传
  const target = list.value.find((f) => f.uid === file.uid)
  if (target && target.status === 'uploading') {
    setTimeout(() => {
      target.percent = 100
      target.status = 'done'
    }, 1500)
  }
}
</script>

<template>
  <c-upload :fileList="list" default-status="uploading" @change="onChange" />
</template>
```

:::

## 自定义触发器

default slot 替换默认按钮（拖拽模式下 default slot 不生效）。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref<Array<{ uid: string; name: string }>>([])
</script>

<template>
  <c-upload v-model:fileList="list">
    <c-button type="primary">📤 上传文件</c-button>
  </c-upload>
</template>
```

:::

## 自定义列表项

`itemRender` slot 完全自渲列表，参数 `{ item, remove }`。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref<Array<{ uid: string; name: string }>>([])
</script>

<template>
  <c-upload v-model:fileList="list" multiple>
    <template #itemRender="{ item, remove }">
      <li
        style="display:flex;align-items:center;gap:8px;padding:6px;background:var(--ccui-color-bg-container);border:1px solid var(--ccui-color-border-secondary);border-radius:4px;margin-top:6px"
      >
        <span>📄</span>
        <span style="flex:1">{{ item.name }}</span>
        <c-button size="small" @click="remove">移除</c-button>
      </li>
    </template>
  </c-upload>
</template>
```

:::

## 禁用

`disabled` 关掉点击 / 拖拽 / 列表项的 ✕ 按钮。

:::demo

```vue
<script setup lang="ts">
import { ref } from 'vue'
const list = ref([{ uid: '1', name: 'preset.txt', status: 'done' }])
</script>

<template>
  <c-upload :fileList="list" disabled />
</template>
```

:::

## API

### Props

| 参数            | 类型                                                            | 默认值                       | 说明                                                                       |
| --------------- | --------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| fileList        | `UploadFile[]`                                                  | --                           | 受控文件列表，支持 `v-model:fileList`                                      |
| defaultFileList | `UploadFile[]`                                                  | `[]`                         | 非受控初始列表                                                             |
| accept          | string                                                          | `''`                         | 接受的文件类型（传给 native input.accept）                                 |
| multiple        | boolean                                                         | `false`                      | 是否允许多选                                                               |
| disabled        | boolean                                                         | `false`                      | 是否禁用                                                                   |
| maxCount        | number                                                          | `0`                          | 最大文件数；`0` 表示不限                                                   |
| maxSize         | number                                                          | `0`                          | 单文件最大字节数；`0` 表示不限                                             |
| beforeUpload    | `(file: File, fileList: File[]) => boolean \| Promise<boolean>` | --                           | 过滤函数（同步/异步）；返回 false 拒收                                     |
| drag            | boolean                                                         | `false`                      | 是否渲染拖拽区域代替按钮                                                   |
| showUploadList  | boolean                                                         | `true`                       | 是否渲染文件列表                                                           |
| listType        | `'text' \| 'picture' \| 'picture-card'`                         | `'text'`                     | 列表展示形态；`picture` 行内显示缩略图；`picture-card` 网格卡片（104×104） |
| defaultStatus   | `'uploading' \| 'done' \| 'error'`                              | `'done'`                     | 新加文件的初始 status；业务可改为 'uploading' 让组件持续显示加载态         |
| triggerText     | string                                                          | `点击上传`                   | 默认按钮文案                                                               |
| dragText        | string                                                          | `点击或拖拽文件到此区域上传` | 拖拽区文案                                                                 |
| removeText      | string                                                          | `删除`                       | 列表项 × 按钮的 aria-label                                                 |
| customRequest   | `(options: CustomRequestOptions) => void`                       | --                           | 自定义上传函数（onProgress/onSuccess/onError）                             |
| action          | string                                                          | `''`                         | 上传地址；未传 customRequest 时用默认 XHR POST                             |

### UploadFile

| 字段     | 类型                                            | 说明                         |
| -------- | ----------------------------------------------- | ---------------------------- |
| uid      | string                                          | 唯一标识；组件生成时自动给   |
| name     | string                                          | 文件名                       |
| size     | number                                          | 字节数                       |
| type     | string                                          | MIME                         |
| status   | `'uploading' \| 'done' \| 'error' \| 'removed'` | 状态                         |
| percent  | number                                          | 上传进度（0-100）            |
| url      | string                                          | 已上传的远端 URL（业务回写） |
| response | unknown                                         | 后端响应（业务回写）         |
| raw      | File                                            | 原始 File 对象               |

### Events

| 事件名          | 回调签名                                                          | 触发时机                   |
| --------------- | ----------------------------------------------------------------- | -------------------------- |
| update:fileList | `(list: UploadFile[])`                                            | 列表变化                   |
| change          | `(file: UploadFile, list: UploadFile[])`                          | 单文件添加 / 移除时        |
| remove          | `(file: UploadFile)`                                              | 用户点 × 移除              |
| reject          | `(file: File, reason: 'maxSize' \| 'maxCount' \| 'beforeUpload')` | 文件被拒收                 |
| drop            | `(e: DragEvent)`                                                  | 拖拽放下（仅 `drag=true`） |
| preview         | `(file: UploadFile)`                                              | 点击文件名时触发           |

### Slots

| 名称       | 参数                                       | 说明                               |
| ---------- | ------------------------------------------ | ---------------------------------- |
| default    | --                                         | 自定义触发器（drag=true 时不生效） |
| itemRender | `{ item: UploadFile, remove: () => void }` | 自定义单项渲染                     |

## 已知限制（未交付）

- **进度条**：`percent` 字段已支持渲染百分比文字，但没有彩色进度条 UI；后续接入 `c-progress`。
- **chunk 分片上传 / 断点续传**：复杂场景，留长尾。
- **directory 目录选择**：input.webkitdirectory 暂未透传。


---

# Util 工具集

> 文档链接：https://vaebe.github.io/ccui/components/util/index.html

vue3-ccui 内部使用的公共工具函数。

## 何时使用

- 在自定义组件中需要复用 ccui 内部的一些通用工具函数。

## DOM

| 函数                       | 说明                                   |
| -------------------------- | -------------------------------------- |
| `inBrowser`                | 是否运行在浏览器环境                   |
| `canUseDom()`              | 同上，函数形式                         |
| `getOffset(el)`            | 获取元素相对文档的偏移 `{ top, left }` |
| `isVisible(el)`            | 元素是否可见                           |
| `contains(parent, target)` | 判断 parent 是否包含 target            |

## 函数

| 函数                 | 说明       |
| -------------------- | ---------- |
| `debounce(fn, wait)` | 防抖       |
| `throttle(fn, wait)` | 节流       |
| `noop()`             | 空函数     |
| `isFunction(v)`      | 是否函数   |
| `isObject(v)`        | 是否纯对象 |

## 类型与工具

| 函数                   | 说明                  |
| ---------------------- | --------------------- |
| `classNames(...args)`  | 合并 class 名称       |
| `isNil(v)`             | 是否 null / undefined |
| `clamp(val, min, max)` | 数值边界限制          |

## 使用示例

```ts
import { clamp, classNames, debounce } from '@vaebe/ccui'

const cls = classNames('a', { b: true })
const v = clamp(15, 0, 10) // 10

const onResize = debounce(() => {
  // ...
}, 200)
```


---

# Watermark 水印

> 文档链接：https://vaebe.github.io/ccui/components/watermark/index.html

为页面或局部容器盖上重复的、平铺的水印。常用于"版权提示 / 数据保密 / 防截图泄露"等场景。

## 基本使用

把要保护的内容包在 `<c-watermark>` 里，传入 `content`。

:::demo

```vue
<template>
  <c-watermark content="@vaebe/ccui">
    <div style="height: 200px; background: var(--ccui-area); padding: 16px">水印保护区域，文字会随宽高密铺。</div>
  </c-watermark>
</template>
```

:::

## 多行文字

`content` 传数组时按多行排列。

:::demo

```vue
<template>
  <c-watermark :content="['CCUI', 'Confidential']">
    <div style="height: 200px; background: var(--ccui-color-bg-container); border: 1px dashed var(--ccui-color-border); padding: 16px">多行水印</div>
  </c-watermark>
</template>
```

:::

## 自定义旋转

`rotate` 控制旋转角度（默认 -22°，与常见水印一致）。

:::demo

```vue
<template>
  <c-watermark content="ROTATE 0" :rotate="0">
    <div style="height: 100px; background: var(--ccui-area); padding: 12px">rotate=0</div>
  </c-watermark>
  <c-watermark content="ROTATE -45" :rotate="-45" style="margin-top: 12px">
    <div style="height: 100px; background: var(--ccui-area); padding: 12px">rotate=-45</div>
  </c-watermark>
</template>
```

:::

## 字体样式

`font` 接受 `color` / `fontSize` / `fontWeight` / `fontStyle` / `fontFamily`。

:::demo

```vue
<template>
  <c-watermark content="Important" :font="{ color: 'rgba(255, 0, 0, 0.18)', fontSize: 18, fontWeight: 600 }">
    <div style="height: 160px; background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); padding: 16px">
      自定义颜色 / 字号 / 粗细
    </div>
  </c-watermark>
</template>
```

:::

## 控制密度

`gap` 是相邻水印块的水平 / 垂直间距，`width` / `height` 是单块水印的盒子尺寸。

:::demo

```vue
<template>
  <c-watermark content="dense" :gap="[40, 40]" :width="80" :height="40">
    <div style="height: 160px; background: var(--ccui-area); padding: 12px">高密度</div>
  </c-watermark>
  <c-watermark content="sparse" :gap="[180, 120]" style="margin-top: 12px">
    <div style="height: 160px; background: var(--ccui-area); padding: 12px">低密度</div>
  </c-watermark>
</template>
```

:::

## 图片水印

`image` 接受图片地址（建议是带透明通道的 PNG / SVG），优先于文字。

:::demo

```vue
<template>
  <c-watermark
    image="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAiIGhlaWdodD0iNjQiIHZpZXdCb3g9IjAgMCAxMjAgNjQiPjxyZWN0IHg9IjE0IiB5PSIyMCIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiByeD0iNiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2JhKDAsMCwwLDAuMikiIHN0cm9rZS13aWR0aD0iMi41Ii8+PHRleHQgeD0iNjgiIHk9IjQwIiBmb250LWZhbWlseT0iLWFwcGxlLXN5c3RlbSxTZWdvZSBVSSxzYW5zLXNlcmlmIiBmb250LXNpemU9IjIyIiBmb250LXdlaWdodD0iNzAwIiBmaWxsPSJyZ2JhKDAsMCwwLDAuMTgpIj5jY3VpPC90ZXh0Pjwvc3ZnPg=="
    :width="120"
    :height="64"
  >
    <div style="height: 200px; background: var(--ccui-color-bg-container); border: 1px solid var(--ccui-color-border-secondary); padding: 16px">图片水印（背景层）</div>
  </c-watermark>
</template>
```

:::

## API

### Props

| 参数    | 类型                 | 默认值       | 说明                                         |
| ------- | -------------------- | ------------ | -------------------------------------------- |
| content | `string \| string[]` | `''`         | 文字水印（数组按多行排列）                   |
| image   | string               | `''`         | 图片水印地址（优先于 `content`）             |
| width   | number               | `120`        | 单个水印块的宽度（px）                       |
| height  | number               | `64`         | 单个水印块的高度（px）                       |
| rotate  | number               | `-22`        | 旋转角度（度）                               |
| zIndex  | number               | `9`          | 水印层 `z-index`                             |
| gap     | `[number, number]`   | `[100, 100]` | 水印间距 `[水平, 垂直]`                      |
| offset  | `[number, number]`   | `undefined`  | 偏移量，控制起点位置                         |
| font    | `WatermarkFont`      | `{}`         | 字体样式（color / fontSize / fontWeight 等） |