x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/button.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Button AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Button`；模型：无；已核对事件：click。
+先读 [通用接入](../core.md)。公开导出：`Button, ButtonGroup`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./button-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/button`（包含 base.css、button.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。尺寸优先级为显式 `size` → ButtonGroup → ConfigProvider → `'medium'`；Button 不通过 FormItem 继承尺寸。`disabled` / `loading` 默认关闭。
 
 `click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
@@ -32,4 +34,446 @@ async function save(_event: MouseEvent) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/button.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./button-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+按钮用于触发即时操作，是业务界面里最常见的动作入口。
+
+
+### 何时使用
+
+- 触发提交、保存、删除、打开弹层等即时动作。
+- 在操作区表达主次关系、危险程度和加载反馈。
+- 多个相关动作需要组成按钮组时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button>默认按钮</Button>
+  <Button type="primary">主要按钮</Button>
+  <Button type="outline">描边按钮</Button>
+  <Button type="text">文本按钮</Button>
+</template>
+```
+
+### 外部水波纹
+
+Button 默认开启类似 Ant Design Vue 的外部轮廓水波纹。`disabled`、`loading`、`link` 和 `type="text"` 状态不会展示外部水波纹。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button>默认水波纹</Button>
+  <Button type="primary">主要水波纹</Button>
+  <Button status="danger">危险水波纹</Button>
+  <Button loading>加载不触发</Button>
+  <Button disabled>禁用不触发</Button>
+</template>
+```
+
+### 状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button status="default">默认</Button>
+  <Button status="success">成功</Button>
+  <Button status="warning">警告</Button>
+  <Button status="strong">强调</Button>
+  <Button status="danger">危险</Button>
+  <Button status="info">信息</Button>
+  <Button disabled>禁用</Button>
+</template>
+```
+
+### 状态色实心按钮
+
+五种状态色都提供实心（高亮）形态，**统一使用白字**与主题惯例一致。实心底色即主题种子色：主要 `#1c61ff`、成功 `#00a809`、警告 `#ffb800`、强调 `#ff8200`、危险 `#e02225`。
+
+危险色种子 `#e02225` 的白字对比为 4.75:1，实心底直接使用种子本身，不再需要压暗变体。
+
+实心底与白字在明暗主题下都恒定不翻转，因此暗色下仍是同一块强调色。更换主题种子色（`base.scss` 的 `--x-color-<name>`）后实心按钮整体联动。
+
+亮黄色、亮橙色实底上的白字属于主题惯例内的折中：这类底亮度过高，强行让白字达到正文级 4.5:1 只能压深到底色失去品牌识别。参考 Arco 的橙色实底白字为 2.57:1、Ant Design 的 `warning` 为 1.90:1，本库 `warning` / `strong` 与二者处于同一水平。需要更高可读性时，可改用 `type="outline"`、`plain` 或 `type="text"` 形态，或把种子色选得更深。各状态实测值与回归下限由 `script/check-contrast.js` 守护。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button type="primary">主要</Button>
+  <Button type="primary" status="success">成功</Button>
+  <Button type="primary" status="warning">警告</Button>
+  <Button type="primary" status="strong">强调</Button>
+  <Button type="primary" status="danger">危险</Button>
+</template>
+```
+
+### 类型与边框
+
+`border="false"` 使用弱背景状态色，不会切换成实心危险按钮。需要实心危险按钮时使用 `type="primary" status="danger"`。
+
+`link` 保持透明背景和对应状态文字色，非圆形链接按钮的高度随文字行高变化、没有水平内边距。禁用和加载期间不会响应悬浮或按下颜色。
+
+彩色文字按钮（`plain`、`outline`、`text`、`link`）在亮色主题中沿用品牌主色，暗色主题中使用同色系的亮色档，与 Link、Tag 同源。对比度下限对齐 Arco 同级角色，由 `script/check-contrast.js` 的 `ARCO_BASELINE` 守护。
+
+### 交互三态
+
+按钮的常态、悬浮、按下按**渐深梯度**设计，每一级都可感知且保持轻盈（明度差 ≥ 0.025，由门禁守护）：
+
+| 形态 | 常态 | 悬浮 | 按下 |
+| --- | --- | --- | --- |
+| 默认 / 信息（灰色系） | `fill-2` | `neutral-3` | `neutral-4` |
+| 彩色弱底 / 描边 / 文本（除 warning） | 无色或同色浅底 | 同色浅底混入按钮文字色 10% | 同色浅底混入按钮文字色 16% |
+| warning 弱底 / 描边 / 文本 | 无色或同色浅底 | 同色浅底混入按钮文字色 25% | 同色浅底混入按钮文字色 40% |
+| 链接 | 透明背景、状态文字色 | 保持常态 | 保持常态 |
+| 实色 | 种子实底 | 混白 8%（更亮） | 混恒定深 10%（更深） |
+
+默认按钮不用 `fill-2/3/4` 递进：全局 fill 灰阶在浅端被压缩，`fill-2` 与 `fill-3` 只差 3 个通道，悬浮态几乎看不出变化；改用 `neutral-3/4` 后与 Arco 的步进一致。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button type="dashed">虚线按钮</Button>
+  <Button type="outline">线性按钮</Button>
+  <Button type="text">文本按钮</Button>
+  <Button plain status="success">朴素成功</Button>
+  <Button :border="false" status="danger">无边框危险</Button>
+  <Button link>链接按钮</Button>
+  <Button link status="danger">危险链接</Button>
+  <Button link disabled>禁用链接</Button>
+</template>
+```
+
+### 状态矩阵
+
+Button 的状态色基于组件 alias token 组织，例如 `--x-button-color-bg-danger-subtle`、`--x-button-color-bg-danger-solid`、`--x-button-color-text-danger`。后续自定义主题可以优先覆盖这些组件级 token。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button status="danger">弱危险</Button>
+  <Button type="primary" status="danger">实心危险</Button>
+  <Button type="outline" status="danger">描边危险</Button>
+  <Button type="dashed" status="danger">虚线危险</Button>
+  <Button type="text" status="danger">文本危险</Button>
+  <Button :border="false" status="danger">无边框危险</Button>
+</template>
+```
+
+### 形状
+
+默认使用小圆角；`square` 为直角，`round` 为胶囊形，`circle` 为等宽高圆形，适合图标或单字内容。纯图标按钮请通过 `aria-label` 提供操作名称。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Icon } from 'x-next';
+const sizes = ['mini', 'small', 'medium', 'large', 'huge'] as const;
+</script>
+<template>
+<div v-for="size in sizes" :key="size">
+    <span>{{ size }}</span>
+    <Button :size="size">默认</Button>
+    <Button :size="size" shape="square">直角</Button>
+    <Button :size="size" shape="round">胶囊</Button>
+    <Button v-bind="{ 'aria-label': `${size} 添加` }" :size="size" shape="circle" type="primary" >
+      <template #icon><Icon name="plus" /></template>
+    </Button>
+  </div>
+</template>
+```
+
+### 尺寸
+
+`mini`、`small`、`medium`、`large`、`huge` 的默认高度分别为 24、28、32、36、38px。
+
+以下为默认主题中的尺寸规格；链接和形状选项会按对应规则调整布局。
+
+| 尺寸 | 高度 | 字号 | 字重 | 左右内边距 | 默认圆角 |
+| --- | --- | --- | --- | --- | --- |
+| `mini` | 24px | 12px | 500 | 8px | 4px |
+| `small` | 28px | 13px | 500 | 10px | 4px |
+| `medium` | 32px | 14px | 500 | 14px | 4px |
+| `large` | 36px | 14px | 500 | 20px | 6px |
+| `huge` | 38px | 16px | 500 | 28px | 6px |
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button size="mini">迷你</Button>
+  <Button size="small">小型</Button>
+  <Button size="medium">中型</Button>
+  <Button size="large">大型</Button>
+  <Button size="huge">超大</Button>
+</template>
+```
+
+### 加载与事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(false);
+const logs = ref<string[]>([]);
+
+const runAsync = () => {
+  loading.value = true;
+  logs.value = ['async start', ...logs.value];
+  window.setTimeout(() => {
+    loading.value = false;
+    logs.value = ['async done', ...logs.value];
+  }, 1200);
+};
+
+const pushLog = (label: string) => {
+  logs.value = [`${label} clicked`, ...logs.value];
+};
+</script>
+<template>
+<Button :loading="loading" type="primary" @click="runAsync">异步提交</Button>
+  <Button :debounce="800" @click="pushLog('debounce')">防重复点击</Button>
+  <Button loading @click="pushLog('loading')">加载中</Button>
+  <Button disabled @click="pushLog('disabled')">禁用按钮</Button>
+  <ul aria-live="polite">
+    <li v-for="(log, index) in logs" :key="index">{{ log }}</li>
+  </ul>
+</template>
+```
+
+### 原生表单类型
+
+<form class="example-box example-box-column" @submit.prevent="handleNativeSubmit">
+</form>
+
+`type` 控制视觉样式，`html-type` 控制原生按钮行为。默认 `html-type="button"`，不会因为放进表单而意外提交。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+const handleSubmit = () => {
+  // 处理已经通过原生 submit 事件提交的数据
+};
+</script>
+<template>
+<form @submit.prevent="handleSubmit">
+    <Button type="primary" html-type="submit">提交表单</Button>
+    <Button html-type="reset">重置</Button>
+    <Button>普通按钮</Button>
+  </form>
+</template>
+```
+
+### 文字与图标
+
+按钮支持中英文混排，可以通过 `prefix`、`suffix` 插槽添加图标或附加文字。下面展示不同尺寸的组合，切换加载状态可查看加载图标与内容的排列。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch, Button, Icon } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(false);
+const clickCount = ref(0);
+const sizes = ['mini', 'small', 'medium', 'large', 'huge'] as const;
+import type { ButtonHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "切换文字与图标示例加载" } satisfies ButtonHTMLAttributes;
+</script>
+<template>
+<label>
+    <Switch v-bind="nativeAttrs1" v-model="loading"  />
+    切换加载状态
+  </label>
+  <div class="button-row">
+    <Button v-for="size in sizes" :key="size" :size="size" :loading="loading" @click="clickCount++">
+      保存 Save
+    </Button>
+  </div>
+  <div class="button-row">
+    <Button v-for="size in sizes" :key="size" :size="size" :loading="loading" @click="clickCount++">
+      <template #prefix><Icon name="download" /></template>
+      导出
+      <template #suffix><span>CSV</span></template>
+    </Button>
+  </div>
+  <p aria-live="polite">
+    {{ loading ? '加载中，按钮暂不可点击' : '可点击按钮' }} · 已点击 {{ clickCount }} 次
+  </p>
+</template>
+<style scoped>
+.button-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 12px;
+}
+</style>
+```
+
+### 插槽内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "帮助" } satisfies HTMLAttributes;
+</script>
+<template>
+<Button type="primary">
+    <template #prefix>
+      <span aria-hidden="true">+</span>
+    </template>
+    新建
+  </Button>
+  <Button>
+    导出
+    <template #suffix>
+      <span aria-hidden="true">↓</span>
+    </template>
+  </Button>
+  <Button v-bind="nativeAttrs1" shape="circle" >
+    <template #icon>
+      <span aria-hidden="true">?</span>
+    </template>
+  </Button>
+</template>
+```
+
+### 宽度与窄按钮
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+
+</script>
+<template>
+<Button block type="primary">撑满父容器</Button>
+  <Button narrow>窄按钮</Button>
+  <Button size="large" narrow>大型窄按钮</Button>
+  <Button loading-fill type="primary" loading>填充加载</Button>
+</template>
+```
+
+### 填充加载与恢复
+
+`loading-fill` 在加载时将图标居中覆盖按钮，保留原宽度与圆角；前后缀、图标和文字视觉隐藏，按钮名称仍保留。结束后恢复全部内容。普通 `loading` 在文字前显示加载图标；圆形和仅使用 `icon` 插槽的按钮自动居中覆盖内容，避免固定宽度下并排挤压。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch, Button, Icon } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(false);
+const clickCount = ref(0);
+import type { ButtonHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "切换填充加载" } satisfies ButtonHTMLAttributes;
+</script>
+<template>
+<label>
+    <Switch v-bind="nativeAttrs1" v-model="loading"  />
+    切换填充加载
+  </label>
+  <Button loading-fill :loading="loading" type="primary" @click="clickCount++">
+    <template #prefix><Icon name="download" /></template>
+    导出报告
+    <template #suffix><span>CSV</span></template>
+  </Button>
+  <Button loading-fill :loading="loading" type="outline" shape="round" @click="clickCount++">
+    保存设置
+  </Button>
+  <p aria-live="polite">
+    {{ loading ? '加载中，按钮暂不可点击' : '内容已恢复，可点击按钮' }} · 已点击 {{ clickCount }} 次
+  </p>
+</template>
+```
+
+### 按钮组
+
+按钮组只连接相邻边缘，保留两端的形状；只有一个按钮时仍保留完整圆角。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch, ButtonGroup, Button } from 'x-next';
+import { ref } from 'vue';
+
+const disabled = ref(false);
+const clickCount = ref(0);
+import type { ButtonHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "切换按钮组禁用" } satisfies ButtonHTMLAttributes;
+</script>
+<template>
+<label>
+    <Switch v-bind="nativeAttrs1" v-model="disabled"  />
+    切换按钮组禁用
+  </label>
+  <ButtonGroup type="primary" :disabled="disabled">
+    <Button @click="clickCount++">上一页</Button>
+    <Button @click="clickCount++">下一页</Button>
+  </ButtonGroup>
+  <ButtonGroup status="danger" size="small" :disabled="disabled">
+    <Button @click="clickCount++">移除</Button>
+    <Button @click="clickCount++">清空</Button>
+    <Button disabled>禁用</Button>
+  </ButtonGroup>
+  <ButtonGroup size="large" :disabled="disabled">
+    <Button @click="clickCount++">单个按钮</Button>
+  </ButtonGroup>
+  <ButtonGroup shape="round" :disabled="disabled">
+    <Button @click="clickCount++">左侧</Button>
+    <Button @click="clickCount++">中间</Button>
+    <Button @click="clickCount++">右侧</Button>
+  </ButtonGroup>
+  <p aria-live="polite">按钮组已点击 {{ clickCount }} 次</p>
+</template>
+```
+
+### ButtonGroup
+
+`ButtonGroup` 可作为按钮组样式容器使用，并可通过组级 `type`、`status`、`shape`、`size`、`disabled` 为内部 `Button` 提供默认值。子按钮显式传入同名属性时，以子按钮自身属性为准。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./button-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/charts.md

@@ -0,0 +1,81 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Charts AI 用法
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。本地组件文档导入的选型和配套资源用法。
+
+### 用途与选型
+
+x-next 内置一套手写 SVG 图表，无外部图表库依赖：颜色跟随 `--x-color-*` token 联动主题与换主色，交互与组件库其余部分一致（受控、插槽、无障碍）。
+
+覆盖 AI 面板与后台系统里最常用的五类基础图表；**复杂图表**（K 线 / 桑基 / 关系图 / 地图 / 甘特 / 3D）请在业务侧接入 ECharts 等专业库，不要期望用这里的组件硬拼。
+
+
+### 怎么选
+
+| 要看什么 | 用哪个 | 说明 |
+| --- | --- | --- |
+| 随时间的**变化趋势**（Token、成本、请求量） | [LineChart 折线图](./line-chart.md) | 主图首选。多系列对比、面积填充、堆叠面积 |
+| 按类目**比较大小**（各接口耗时、各渠道量） | [BarChart 柱状趋势图](./bar-chart.md) | 单系列看趋势，多系列并排或堆叠看构成 |
+| 看**占比构成**（模型占比、渠道占比） | [PieChart 饼图](./pie-chart.md) | 建议用环形 + 中心合计；类别超过 7 个改用堆叠柱 |
+| 卡片角落的**迷你走势** | [TrendChart 迷你趋势图](./trend-chart.md) | 无坐标轴、无图例，纯形态提示；高度控制在 40~60px、宽度 100~320px |
+| **活跃度分布**（按天 / 周） | [Heatmap 热力图](./heatmap.md) | 一年或任意区间的密度分布 |
+
+### 选择时的三个判断
+
+1. **要读数还是看形态？** 需要坐标轴读数、悬浮明细、多系列对比，用 LineChart / BarChart / PieChart；只需要「大致在涨还是跌」，用 TrendChart。
+2. **是趋势还是构成？** 时间轴上比较用折线；类目间比较用柱状；占比用环形。别用饼图做趋势，也别用折线表达静态构成。
+3. **类目有多少？** 折线与柱状在 30+ 类目下仍然可读（x 轴标签会自动抽稀）；饼图超过 7 个分片就该换堆叠柱状，角度比长度更难分辨。
+
+
+### 五个组件的分工
+
+| 组件 | 数据模型 | 坐标轴 | 典型高度 |
+| --- | --- | --- | --- |
+| LineChart | `series[{ name, data }]` + `categories` | 类目轴 + 数值轴（支持负值） | 240 ~ 320 |
+| BarChart | `series[{ name, data }]` + `categories` | 类目轴 + 数值轴（0 基线） | 240 ~ 320 |
+| PieChart | `data[{ name, value }]` | 无 | 200 ~ 300 |
+| TrendChart | `dataset: number[]` | 无 | 40 ~ 60 |
+| Heatmap | `data[{ timestamp, value }]` | 无 | 按格子尺寸 |
+
+
+### 共同约定
+
+- **尺寸**：`height` 传数字按 px（默认 240 ~ 280），`width` 默认撑满父容器；容器尺寸变化时自动重算几何与标签抽稀。
+- **提示**：默认开启，整块画布只挂一个提示节点（不是每个数据点一个浮层），支持 `tooltip` 插槽完全自定义。
+- **图例**：`legend` 开启后点击项可临时隐藏对应系列 / 分片，并触发 `legend-change`；数值轴会按剩余可见系列重算。
+- **键盘与读屏**：画布可聚焦，方向键移动读数，Home / End 跳首尾，Esc 关闭；键盘导航时通过 `aria-live` 播报，`ariaLabel` 提供图像名称。
+- **缺测**：BarChart 与 PieChart 把 `null` / 负数按 0 处理（不画柱、不计入占比）；LineChart 默认在缺测处**断开**，可用 `connectNulls` 改为跨过连接。
+- **按需引入**：图表族共享一层样式，按需引入时需要同时引 `base.css` 与对应组件样式。
+
+
+### 组合示例
+
+同一个面板里组合折线与柱状：把数量放柱状、比率放折线，共用同一组 `categories`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { LineChart } from 'x-next';
+import { ref } from 'vue';
+
+const categories = ref(['周一', '周二', '周三', '周四', '周五', '周六', '周日']);
+const series = ref([
+  { name: '请求量', data: [820, 932, 901, 934, 1290, 1330, 1320] },
+  { name: '错误数', data: [120, 132, 101, 134, 90, 230, 210] },
+]);
+</script>
+<template>
+<LineChart
+    :categories="categories"
+    :series="series"
+    legend
+    area
+    :height="260"
+  />
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。

package/AI_USAGE/components/checkbox-api.md

@@ -0,0 +1,145 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Checkbox 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Checkbox API
+
+公开声明：`dist/components/form-checkbox/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; false &#124; true &#124; CheckboxValue[] | 否 | undefined |
+| defaultChecked | 默认是否选中，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| value | 选项值，在 CheckboxGroup 中使用 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| indeterminate | 是否为半选状态 | undefined &#124; false &#124; true | 否 | false |
+| size | 组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| uninjectGroupContext | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: boolean &#124; CheckboxValueList) => any |
+| change | 值变化时触发 | undefined &#124; (value: boolean &#124; CheckboxValueList, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 复选框文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| checkbox | 自定义复选框图形 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type CheckboxValue = string | number | boolean;
+
+type CheckboxValueList = CheckboxValue[];
+
+interface CheckboxOption {
+    /**
+     * @zh 文案
+     * @en label content
+     */
+    label?: RenderContent;
+    /**
+     * @zh 选项的 `value`
+     * @en The `value` of the option
+     */
+    value: CheckboxValue;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否为半选状态
+     * @en Whether it is half-selected
+     */
+    indeterminate?: boolean;
+}
+```
+
+
+## CheckboxGroup API
+
+公开声明：`dist/components/form-checkbox/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; CheckboxValue[] | 否 | undefined |
+| defaultValue | 默认值，非受控模式 | undefined &#124; CheckboxValue[] | 否 | [] |
+| max | 最多可选数量 | undefined &#124; number | 否 | 未声明 |
+| options | 选项数据 | undefined &#124; (CheckboxValue &#124; CheckboxOption)[] | 否 | 未声明 |
+| direction | 排列方向 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| size | 组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: CheckboxValueList) => any |
+| change | 值变化时触发 | undefined &#124; (value: CheckboxValueList, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 自定义复选框列表 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 自定义 options 文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| checkbox | 自定义复选框图形 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type CheckboxValue = string | number | boolean;
+
+type CheckboxValueList = CheckboxValue[];
+
+interface CheckboxOption {
+    /**
+     * @zh 文案
+     * @en label content
+     */
+    label?: RenderContent;
+    /**
+     * @zh 选项的 `value`
+     * @en The `value` of the option
+     */
+    value: CheckboxValue;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否为半选状态
+     * @en Whether it is half-selected
+     */
+    indeterminate?: boolean;
+}
+```
+
+
+返回 [Checkbox 用法](./checkbox.md)。