x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/checkbox.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Checkbox AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Checkbox`；模型：v-model；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Checkbox, CheckboxGroup`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./checkbox-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-checkbox`（包含 base.css、form-checkbox.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
 
 `change(value, event)` 返回新值和原生 `Event`。默认插槽是文案，`checkbox` 插槽提供 `checked` / `disabled`。`id`、`name`、`required`、`form`、`tabindex`、`autofocus`、`autocomplete` 和 `aria-*` 传给原生复选框。
@@ -31,4 +33,364 @@ function changed(value: boolean | (string | number | boolean)[], event: Event) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/checkbox.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./checkbox-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于多选或开关式勾选，适合权限配置、批量选择、偏好设置等场景。
+
+
+### 何时使用
+
+- 需要在一组互不排斥的选项中选择多个值。
+- 需要展示全选、半选、最多可选等状态。
+- 需要以单个布尔值表达是否启用某项配置。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox } from 'x-next';
+import { ref } from 'vue';
+
+const checked = ref(false);
+</script>
+<template>
+<Checkbox v-model="checked">同意协议</Checkbox>
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+
+const checked = ref(true);
+const values = ref(['read']);
+const options = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+];
+</script>
+<template>
+<Checkbox v-model="checked" size="mini">mini</Checkbox>
+  <Checkbox v-model="checked" size="small">small</Checkbox>
+  <Checkbox v-model="checked" size="medium">medium</Checkbox>
+  <Checkbox v-model="checked" size="large">large</Checkbox>
+
+  <CheckboxGroup v-model="values" :options="options" size="mini" />
+  <CheckboxGroup v-model="values" :options="options" size="large" />
+</template>
+```
+
+### 禁用状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox } from 'x-next';
+import { ref } from 'vue';
+
+const checked = ref(true);
+</script>
+<template>
+<Checkbox disabled>禁用未选</Checkbox>
+  <Checkbox v-model="checked" disabled>禁用已选</Checkbox>
+</template>
+```
+
+### 半选状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, CheckboxGroup } from 'x-next';
+import { computed, ref } from 'vue';
+
+const values = ref(['read']);
+const permissions = ['read', 'write', 'publish'];
+const options = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+  { label: '发布', value: 'publish' },
+];
+const checkAll = computed({
+  get: () => permissions.every((value) => values.value.includes(value)),
+  set: (checked: boolean) => {
+    values.value = checked ? [...permissions] : [];
+  },
+});
+const isIndeterminate = computed(
+  () => values.value.length > 0 && values.value.length < permissions.length,
+);
+</script>
+<template>
+<Checkbox v-model="checkAll" :indeterminate="isIndeterminate">全选权限</Checkbox>
+  <CheckboxGroup v-model="values" :options="options" />
+</template>
+```
+
+### 复选框组
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+
+const values = ref(['read']);
+const options = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+  { label: '发布', value: 'publish' },
+];
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options" />
+</template>
+```
+
+### 纵向排列
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+
+const values = ref(['email']);
+const options = [
+  { label: '邮件', value: 'email' },
+  { label: '短信', value: 'sms', disabled: true },
+  { label: '站内信', value: 'notice' },
+];
+</script>
+<template>
+<CheckboxGroup v-model="values" direction="vertical" :options="options" />
+</template>
+```
+
+### 最多可选
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+
+const values = ref(['read']);
+const options = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+  { label: '发布', value: 'publish' },
+  { label: '删除', value: 'delete' },
+];
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options" :max="2" />
+</template>
+```
+
+### 自定义文案
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+const values = ref(['vue']);
+const options = [{ label: 'Vue', value: 'vue' }, { label: 'TypeScript', value: 'ts' }];
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options">
+    <template #label="{ data }">
+      <span>{{ data.label }}模块</span>
+    </template>
+  </CheckboxGroup>
+</template>
+```
+
+### 自定义复选框图形
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+const values = ref(['vue']);
+const options = [{ label: 'Vue', value: 'vue' }, { label: 'TypeScript', value: 'ts' }];
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options">
+    <template #checkbox="{ checked, disabled }">
+      <span :class="{ 'is-checked': checked, 'is-disabled': disabled }">
+        {{ checked ? '✓' : '' }}
+      </span>
+    </template>
+  </CheckboxGroup>
+</template>
+```
+
+### 布尔值选项
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+import { ref } from 'vue';
+
+const values = ref([true]);
+const options = [
+  { label: '启用', value: true },
+  { label: '停用', value: false },
+];
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options" />
+</template>
+```
+
+### 事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { CheckboxGroup } from 'x-next';
+const groupOptions = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+  { label: '发布', value: 'publish' },
+];
+
+import { ref } from 'vue';
+
+const values = ref(['read']);
+const handleChange = (value: Array<string | number | boolean>) => {
+  console.log(value);
+};
+const options = groupOptions;
+</script>
+<template>
+<CheckboxGroup v-model="values" :options="options" @change="handleChange" />
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, CheckboxGroup, Checkbox, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ features: [] as string[] });
+const formRules: Record<string, FieldRule[]> = {
+  features: [{ type: 'array', required: true, message: '至少选择一项功能' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="features" label="功能">
+      <CheckboxGroup v-model="formState.features">
+      <Checkbox value="report">报表</Checkbox>
+      <Checkbox value="alert">告警</Checkbox>
+    </CheckboxGroup>
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+### 原生表单属性
+
+`id`、`name`、`required`、`form`、`tabindex`、`autofocus`、`autocomplete` 和 `aria-*` 传给内部原生 checkbox input。`class`、`style`、`data-*` 等容器属性保留在外层 label；组件自行管理 `checked`、`disabled` 和 `aria-checked`。组件本身就是 label，不要再嵌套外层 label。
+
+下面的 Checkbox 位于表单外，通过 `form` 关联原生表单。未勾选时浏览器阻止提交；勾选后 `FormData` 能取得 `name` 对应的值。单纯传 `required` 不会创建 x-form 的校验规则。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Checkbox } from 'x-next';
+import 'x-next/dist/style.css';
+
+const agreement = ref(false);
+const result = ref('');
+function submit(event: Event) {
+  result.value = String(new FormData(event.currentTarget as HTMLFormElement).get('agreement'));
+}
+import type { InputHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "name": "agreement", "form": "agreement-form", "required": true } satisfies InputHTMLAttributes;
+</script>
+<template>
+<form id="agreement-form" @submit.prevent="submit">
+    <Button html-type="submit">提交</Button>
+  </form>
+  <Checkbox v-bind="nativeAttrs1" v-model="agreement"  value="accepted"  >同意协议</Checkbox>
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+### 键盘与可见焦点
+
+按 Tab 进入复选框，Space 勾选或取消。普通主题和系统高对比度模式都显示组件外框，已选、半选和自定义图形不会隐藏焦点。禁用项不进入 Tab 顺序。原生 input 保留有效透明点击盒，角色定位可以直接勾选，不需要 force。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Checkbox } from 'x-next';
+import 'x-next/style/form-checkbox';
+const checked = ref(true);
+const custom = ref(false);
+const defaultAttrs = { 'aria-label': '键盘默认复选框' };
+const customAttrs = { 'aria-label': '键盘自定义复选框' };
+</script>
+<template>
+<button type="button">从这里按 Tab</button>
+  <Checkbox v-model="checked" v-bind="defaultAttrs">默认图形，初始已选</Checkbox>
+  <Checkbox v-model="custom" v-bind="customAttrs">
+    <template #checkbox="{ checked: selected }">
+      <span class="custom-check" :class="{ selected }">{{ selected ? '✓' : '' }}</span>
+    </template>
+    自定义图形
+  </Checkbox>
+  <Checkbox disabled>禁用项跳过</Checkbox>
+  <p role="status">默认：{{ checked }}；自定义：{{ custom }}</p>
+</template>
+<style scoped>
+.custom-check { display: inline-flex; align-items: center; justify-content: center; width: 20px; height: 20px; border: 1px solid currentColor; }
+.selected { background: var(--x-color-primary-6); color: white; }
+</style>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./checkbox-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/color-picker-api.md

@@ -0,0 +1,52 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# ColorPicker 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## ColorPicker API
+
+公开声明：`dist/components/color-picker/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 颜色值，支持 hex / rgb / hsl | undefined &#124; string | 否 | undefined |
+| defaultValue | 非受控初值 | undefined &#124; string | 否 | undefined |
+| show | 面板是否可见（受控） | undefined &#124; false &#124; true | 否 | undefined |
+| defaultShow | 面板默认是否可见 | undefined &#124; false &#124; true | 否 | false |
+| modes | 可选的颜色格式 | undefined &#124; ColorFormat[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| showAlpha | 是否启用透明度 | undefined &#124; false &#124; true | 否 | true |
+| swatches | 预设色块 | undefined &#124; string[] | 否 | [] |
+| showConfirm | 是否展示确认按钮 | undefined &#124; false &#124; true | 否 | true |
+| showClear | 是否展示清除按钮 | undefined &#124; false &#124; true | 否 | true |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| size | 尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| popupContainer | 面板挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 颜色变化 | undefined &#124; (_value: string, _ev?: Event &#124; undefined) => any |
+| change | 颜色变化 | undefined &#124; (_value: string, _ev?: Event &#124; undefined) => any |
+| update:show | 面板显隐变化 | undefined &#124; (_visible: boolean) => any |
+| showChange | 面板显隐变化 | undefined &#124; (_visible: boolean) => any |
+| confirm | 点击确认按钮 | undefined &#124; (_value: string) => any |
+| clear | 点击清除按钮 | undefined &#124; () => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发器内的补充内容 | undefined &#124; () => unknown |
+| trigger | 自定义触发器，将 triggerAttrs 绑定到实际按钮 | undefined &#124; (props: { value: string; visible: boolean; triggerAttrs: ButtonHTMLAttributes & VNodeProps; }) => unknown |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [ColorPicker 用法](./color-picker.md)。

package/AI_USAGE/components/color-picker.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # ColorPicker AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`ColorPicker`；模型：v-model、v-model:show；已核对事件：change、showChange、clear、confirm。
+先读 [通用接入](../core.md)。公开导出：`ColorPicker`；主要模型：v-model、v-model:show。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./color-picker-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/color-picker`（包含 base.css、color-picker.css、button.css、form-input.css、form-input-number.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/color-picker)。`v-model` 输出 hex 字符串；`v-model:show` 控制面板。清除恢复显式 defaultValue，未提供则提交空字符串；change、clear、confirm 都通知 Form 的 change 通道。自定义触发器将 triggerAttrs 绑定到原生按钮，保留键盘、ARIA、禁用与焦点行为。
 
 ```vue
@@ -33,4 +35,210 @@ const pickerAttrs = { id: 'brand-color', 'aria-label': '品牌色' };
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/color-picker.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./color-picker-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于选择颜色值，支持 hex / rgb / hsl 三种格式与透明度。
+
+
+### 何时使用
+
+- 需要让用户从任意颜色中挑选一个（品牌色、标签色、图表配色）。
+- 需要精确输入颜色值（设计稿给定 hex，或按 rgb/hsl 通道微调）。
+- 提供预设色板时，可同时给出 `swatches` 让用户快速选择。
+
+
+### 基础用法
+
+`v-model` 绑定的是颜色字符串。点击色块展开面板，拖动取色区或色相条调整颜色。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#165dff');
+</script>
+<template>
+<ColorPicker v-model="value" />
+  <p role="status">{{ value }}</p>
+</template>
+```
+
+### 受控值与事件
+
+`change` 在颜色变化时触发，携带当前颜色字符串。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#00b42a');
+const changeLog = ref('等待操作');
+
+const handleChange = (value: string) => {
+  changeLog.value = `change: ${value}`;
+};
+</script>
+<template>
+<ColorPicker v-model="value" @change="handleChange" />
+  <p role="status">{{ changeLog }}</p>
+</template>
+```
+
+### 透明度
+
+默认开启透明度（`showAlpha`），面板会多出透明度条，输出值为 8 位 hex。关闭后会忽略 alpha。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#f53f3f80');
+</script>
+<template>
+<ColorPicker v-model="value" />
+  <ColorPicker :default-value="value" :show-alpha="false" />
+</template>
+```
+
+### 格式切换
+
+`modes` 决定面板中可切换的输入格式。只给 `hex` 时面板只显示一个文本输入框。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#ff7d00');
+</script>
+<template>
+<ColorPicker v-model="value" :modes="['hex']" />
+  <ColorPicker v-model="value" :modes="['hex', 'rgb']" />
+  <ColorPicker v-model="value" :modes="['hex', 'rgb', 'hsl']" />
+</template>
+```
+
+### 预设颜色
+
+`swatches` 提供预设色块，点击后取色区、滑轨与输入框会同步。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#722ed1');
+const swatches = ['#165dff', '#00b42a', '#ff7d00', '#f53f3f', '#722ed1'];
+</script>
+<template>
+<ColorPicker v-model="value" :swatches="swatches" />
+  <p role="status">{{ value }}</p>
+</template>
+```
+
+### 尺寸与禁用
+
+`size` 与表单控件一致；`disabled` 会禁用触发器与面板内所有交互。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#0fc6c2');
+</script>
+<template>
+<ColorPicker v-model="value" size="mini" />
+  <ColorPicker v-model="value" size="small" />
+  <ColorPicker v-model="value" size="medium" />
+  <ColorPicker v-model="value" size="large" />
+  <ColorPicker v-model="value" disabled />
+</template>
+```
+
+### 自定义触发器
+
+`trigger` 插槽可替换默认色块按钮；将 `triggerAttrs` 绑定到实际按钮，保留禁用、表单标签、面板关联、键盘打开与焦点归还。`default` 插槽内容会渲染在色块旁边。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ColorPicker } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('#165dff');
+</script>
+<template>
+<ColorPicker v-model="value">
+    <template #trigger="{ value, visible, triggerAttrs }">
+      <button v-bind="triggerAttrs">{{ visible ? '选择中' : value }}</button>
+    </template>
+  </ColorPicker>
+</template>
+```
+
+### 在 Form 中校验
+
+打开面板后点「清除」会将未配置 `defaultValue` 的字段设为空，并触发 change 校验；确认也会通知 Form。输入框编辑仅属于面板，不会抢占业务字段的标签关联。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, ColorPicker, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formRef = ref<FormInstance>();
+const formModel = reactive({ brandColor: '#165dff' });
+const swatches = ['#165dff', '#00b42a', '#ff7d00'];
+const result = ref('');
+const rules: Record<string, FieldRule[]> = {
+  brandColor: [{ required: true, message: '请选择品牌色' }],
+};
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  result.value = errors ? '校验失败' : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  result.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formModel" :rules="rules" layout="vertical">
+    <FormItem field="brandColor" label="品牌色" validate-trigger="change">
+      <ColorPicker v-model="formModel.brandColor" :swatches="swatches" />
+    </FormItem>
+  </Form>
+  <Button type="primary" size="small" @click="handleValidate">校验</Button>
+  <Button size="small" @click="handleReset">重置</Button>
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+### 交互说明
+
+- **值形态**：`v-model` 始终输出 hex 字符串（`showAlpha` 开启且存在透明度时为 8 位），便于持久化；面板内部允许按 rgb / hsl 输入后再换算。
+- **键盘操作**：默认触发按钮支持 Enter、Space、ArrowDown 打开并进入面板。取色区与两条滑轨都可聚焦，方向键微调（按住 Shift 步长更大）；`Esc` 关闭面板并把焦点还给触发器。
+- **颜色解析**：支持 `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`、`rgb()` / `rgba()`、`hsl()` / `hsla()`，逗号与空格语法均可。传空或非法值时面板回退到兜底色，不会崩溃。
+- **受控显隐**：传入 `show` 后组件不再自行改变显隐状态，需监听 `showChange` 更新。
+- **指针操作**：取色区与滑轨使用 PointerEvent 支持鼠标、触摸和笔；取消、窗口失焦、禁用或卸载会结束拖拽，并保留 MouseEvent 回退。触摸设备的实际手势体验仍需设备验收。
+- **清除语义**：设置了 `defaultValue` 时清除恢复该默认值；否则提交空字符串，触发器使用兜底色显示。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./color-picker-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。