x-next 1.16.1 → 1.17.0

package/AI_USAGE.md

@@ -1,11 +1,11 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.16.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.17.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`82741ea6b533ff677d8fd71ad9c907c9d8ffe3f134b363bb1584668c30115b17`。
+来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`cb20ad6ab74abb988edda3dcdead384d76be5bf5f8d346414b20974fc2b6ac68`。
 
-覆盖 58 个组件族与 105 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
+覆盖 59 个组件族与 106 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。消费项目应在自己的指令中明确引用。
 
@@ -41,6 +41,7 @@
 | Steps | `Steps` | `<x-steps>` | `v-model:current` | `x-next/style/steps` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/steps) |
 | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | `x-next/style/tabs` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/tabs) |
 | TreeSelect | `TreeSelect`, `TreeSelectDropdown` | `<x-tree-select>` | `v-model`, `v-model:input-value`, `v-model:popup-visible`, `v-model:expanded-keys` | `x-next/style/tree-select` | `empty.css`, `form-checkbox.css`, `form-select.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/tree-select) |
+| Transfer | `Transfer` | `<x-transfer>` | `v-model`, `v-model:selected-keys` | `x-next/style/transfer` | `button.css`, `empty.css`, `form-checkbox.css`, `form-input.css`, `form-input-number.css`, `form-select.css`, `pagination.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/transfer) |
 | Empty | `Empty` | `<x-empty>` | 无 | `x-next/style/empty` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/empty) |
 | Upload | `Upload` | `<x-upload>` | `v-model:file-list` | `x-next/style/upload` | `image.css`, `progress.css`, `trigger.css`, `tooltip.css` | [组件文档](https://x-next.yjmf.com/components/upload) |
 | BarChart | `BarChart` | `<x-bar-chart>` | 无 | `x-next/style/bar-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
@@ -783,6 +784,40 @@ function resized(size: number) { current.value = 1; feedback.value = `每页 ${s
 </template>
 ```
 
+## Transfer
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/transfer)。`data` 是 `{ value: string | number, label: string, disabled?: boolean }[]`，可附加业务字段。`v-model` 是目标侧值数组；`v-model:selected-keys` 是两侧临时勾选数组，彼此独立。`defaultValue` / `defaultSelectedKeys` 只初始化非受控状态。数字与字符串值不同；重复数据值保留首项。目标模型中的未加载值不展示，移动其他项时仍保留。
+
+`showSearch=false`、`showSelectAll=true`、`simple=false`、`oneWay=false`、`loading=false`、`disabled=false`。搜索默认不区分大小写，`filterOption(input, item, type)` 适配业务字段。全选只处理当前搜索结果，分页时仅当前页，禁用项不参与；已勾选的搜索隐藏项仍可移动。`simple` 点击即移动；`oneWay` 只显示向右按钮，目标侧逐项移除，禁用项不可移除。加载阻止操作。`targetOrder='original'` 按源数据排序，`append` 按模型顺序。
+
+`change(values, type, movedValues)` 的 `type` 是目的侧 `'source' | 'target'`；`select(sourceSelected, targetSelected)` 报告两侧有效勾选；`search(input, type)`、`scroll(event, type)` 报告源/目标侧。受控模型必须回写；不回写时不提交界面状态。Form 只在移动时触发 change，搜索/临时勾选不触发字段校验。
+
+`pagination=true | { pageSize }` 默认每页 10，优先于 `virtualListProps`。`item` 自定义内容；`source` / `target` 替换列表，提供 `data`、`pageData`、`selectedKeys`、`disabled`、`onSelect(value, checked)`、`onSelectAll(values, checked)`、`onMove(values)`。回调统一校验同侧、存在性、禁用和加载。自定义列表自行实现空态、虚拟滚动及键盘语义；默认列表用 Tab/Space 和方向键/Home/End 操作。没有 readonly、远程分页、拖拽排序或字段映射 API。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Transfer } from 'x-next';
+import type { TransferItem, TransferValue, TransferType } from 'x-next';
+import 'x-next/style/transfer';
+const values = ref<TransferValue[]>(['audit']);
+const data: TransferItem[] = [
+  { value: 'read', label: '查看数据' },
+  { value: 'edit', label: '编辑数据' },
+  { value: 'audit', label: '审核数据' },
+  { value: 'admin', label: '管理配置', disabled: true },
+];
+const log = ref('');
+function changed(next: TransferValue[], type: TransferType, moved: TransferValue[]) {
+  log.value = `${type} ${moved.join(',')}；目标值 ${JSON.stringify(next)}`;
+}
+</script>
+<template>
+  <Transfer v-model="values" :data="data" show-search @change="changed" />
+  <p aria-live="polite">{{ log }}</p>
+</template>
+```
+
 ## TreeSelect
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/tree-select)。用于在层级数据中选择节点，`data` 是 `{ key, title, children }` 树。单选为标量、`multiple` 为数组、`treeCheckable` 勾选模式始终返回数组；`allowSearch` 默认多选 / 勾选开启、单选关闭，`checkedStrategy` 默认 `parent`。
@@ -9010,6 +9045,474 @@ const nativeAttrs1 = { "aria-label": "键盘选择地区" } satisfies HTMLAttrib
 - 与 Arco 的差异：`checkedStrategy` 默认 `parent`（Arco 默认 `all`），并在其基础上提供 `child`；值可为 `labelInValue` 对象且附带 `raw` 原始节点，属于 x-next 的扩展。
 
 
+## Transfer 扩展场景
+
+### 用途与选型
+
+在两列列表之间移动数据，用于权限分配、成员分组和资源授权。
+
+
+### 何时使用
+
+- 同时查看候选与已分配数据，进行批量分配或取消分配。
+- 选项包含较多业务信息，Select 展开空间不足。
+- 自定义列表可以接入表格或树；层级关联与列表键盘逻辑由业务组合实现。
+
+
+### 基础用法与移动事件
+
+先勾选，再点击方向按钮。`change` 的第二参数是移动目的侧，第三参数仅包含实际移动值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const basicValue = ref<TransferValue[]>(['audit']);
+  const basicData: TransferItem[] = [
+    { value: 'read', label: '查看数据' },
+    { value: 'edit', label: '编辑数据' },
+    { value: 'audit', label: '审核数据' },
+    { value: 'admin', label: '管理配置（不可分配）', disabled: true },
+  ];
+  const basicLog = ref('请勾选权限并移动');
+  function basicChange(value: TransferValue[], type: TransferType, moved: TransferValue[]) {
+    basicLog.value = `移至 ${type}：${moved.join(', ')}；当前值 ${JSON.stringify(value)}`;
+  }
+</script>
+<template>
+<Transfer
+    v-model="basicValue"
+    :data="basicData"
+    :title="['可分配权限', '已分配权限']"
+    @change="basicChange"
+  />
+  <p aria-live="polite">{{ basicLog }}</p>
+  <p>目标值：{{ basicValue }}</p>
+</template>
+```
+
+### 受控勾选与目标排序
+
+`v-model:selected-keys` 控制两侧临时勾选，与目标值独立。`target-order="append"` 以模型顺序展示目标项。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer, Button } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const checkedValue = ref<TransferValue[]>([2]);
+  const checkedKeys = ref<TransferValue[]>([1]);
+  const checkedData: TransferItem[] = Array.from({ length: 6 }, (_, index) => ({
+    value: index + 1,
+    label: `成员 ${index + 1}`,
+  }));
+  const checkedLog = ref('');
+  function checkedSelect(source: TransferValue[], target: TransferValue[]) {
+    checkedLog.value = `左侧 ${JSON.stringify(source)}；右侧 ${JSON.stringify(target)}`;
+  }
+</script>
+<template>
+<p
+    ><Button @click="checkedKeys = [1, 2, 3]">勾选成员 1 / 2 / 3</Button>
+    <Button @click="checkedKeys = []">取消所有勾选</Button></p
+  >
+  <Transfer
+    v-model="checkedValue"
+    v-model:selected-keys="checkedKeys"
+    :data="checkedData"
+    target-order="append"
+    @select="checkedSelect"
+  />
+  <p>目标：{{ checkedValue }}；勾选：{{ checkedKeys }}</p>
+  <p aria-live="polite">{{ checkedLog }}</p>
+</template>
+```
+
+### 搜索与过滤后的全选
+
+全选只作用于当前搜索结果，禁用项不参与；已勾选的隐藏项仍可以移动。自定义过滤可搜索附加业务字段。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const searchValue = ref<TransferValue[]>([]);
+  const searchData: TransferItem[] = [
+    { value: 'east-1', label: '杭州', region: '华东' },
+    { value: 'east-2', label: '上海', region: '华东' },
+    { value: 'north', label: '北京', region: '华北' },
+    { value: 'south', label: '深圳', region: '华南', disabled: true },
+  ];
+  const searchLog = ref('尝试搜索“华东”，然后全选');
+  function searchFilter(input: string, item: TransferItem) {
+    return `${item.label} ${String(item.region ?? '')}`.includes(input.trim());
+  }
+  function searchChanged(input: string, type: TransferType) {
+    searchLog.value = `${type} 搜索：${input || '已清空'}`;
+  }
+</script>
+<template>
+<Transfer
+    v-model="searchValue"
+    :data="searchData"
+    show-search
+    search-placeholder="搜索城市或大区"
+    :filter-option="searchFilter"
+    @search="searchChanged"
+  />
+  <p aria-live="polite">{{ searchLog }}</p>
+  <p>目标值：{{ searchValue }}</p>
+</template>
+```
+
+### 禁用、加载与错误状态
+
+加载时显示真实加载组件并阻止操作。单项禁用只影响该项；`error` 同时支持从 Form 继承。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer, Checkbox } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const stateValue = ref<TransferValue[]>([1]);
+  const stateDisabled = ref(false);
+  const stateLoading = ref(false);
+  const stateError = ref(false);
+  const stateData: TransferItem[] = [
+    { value: 1, label: '业务成员' },
+    { value: 2, label: '运维成员' },
+    { value: 3, label: '只读成员（禁用）', disabled: true },
+    { value: 4, label: '这是一个用于检查溢出省略和原生标题的超长成员名称' },
+  ];
+</script>
+<template>
+<p
+    ><Checkbox v-model="stateDisabled">禁用</Checkbox>
+    <Checkbox v-model="stateLoading">加载中</Checkbox>
+    <Checkbox v-model="stateError">错误</Checkbox></p
+  >
+  <Transfer
+    v-model="stateValue"
+    :data="stateData"
+    :disabled="stateDisabled"
+    :loading="stateLoading"
+    :error="stateError"
+    show-search
+  />
+</template>
+```
+
+### 单向分配与逐项移除
+
+只保留向右按钮，目标侧使用可通过键盘到达的移除按钮。已分配的禁用项不能移除。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const oneWayValue = ref<TransferValue[]>(['owner', 'viewer']);
+  const oneWayData: TransferItem[] = [
+    { value: 'owner', label: '固定负责人', disabled: true },
+    { value: 'viewer', label: '查看成员' },
+    { value: 'editor', label: '编辑成员' },
+  ];
+</script>
+<template>
+<Transfer v-model="oneWayValue" :data="oneWayData" one-way :operations="['分配']" />
+  <p>已分配：{{ oneWayValue }}</p>
+</template>
+```
+
+### 简单模式
+
+点击选项直接移动，也支持 Tab 与 Enter/Space。与 `one-way` 组合时，目标侧仍使用移除按钮。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const simpleValue = ref<TransferValue[]>(['b']);
+  const simpleData: TransferItem[] = [
+    { value: 'a', label: '开发组' },
+    { value: 'b', label: '产品组' },
+    { value: 'c', label: '测试组' },
+    { value: 'd', label: '归档组', disabled: true },
+  ];
+</script>
+<template>
+<Transfer v-model="simpleValue" :data="simpleData" simple />
+  <p>点击组名即可移动：{{ simpleValue }}</p>
+</template>
+```
+
+### 自定义选项、标题、图标和页脚
+
+item 仅替换内容，保留原生勾选交互。标题通过 `onSelectAllChange` 调用当前搜索结果/页内的全选。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer, Checkbox } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const slotValue = ref<TransferValue[]>([]);
+  const slotData: TransferItem[] = [
+    { value: 1, label: '林老师', role: '产品设计' },
+    { value: 2, label: '陈同学', role: '前端研发' },
+    { value: 3, label: '张同学', role: '质量保障' },
+  ];
+</script>
+<template>
+<Transfer
+    v-model="slotValue"
+    :data="slotData"
+    show-search
+    :title="['团队成员', '项目成员']"
+    :list-style="{ width: '260px' }"
+  >
+    <template #item="{ item }"
+      ><span>{{ item.label }} · {{ item.role }}</span></template
+    >
+    <template #source-title="{ title, checked, indeterminate, disabled, onSelectAllChange }">
+      <Checkbox
+        :model-value="checked"
+        :indeterminate="indeterminate"
+        :disabled="disabled"
+        @change="onSelectAllChange($event === true)"
+        >{{ title }}</Checkbox
+      >
+    </template>
+    <template #to-target-icon><span aria-hidden="true">→</span></template>
+    <template #to-source-icon><span aria-hidden="true">←</span></template>
+    <template #footer="{ type, data, selectedKeys }"
+      ><small
+        >{{ type === 'source' ? '可选' : '已选' }} {{ data.length }} 人，勾选
+        {{ selectedKeys.length }} 人</small
+      ></template
+    >
+  </Transfer>
+</template>
+```
+
+### 自定义列表
+
+source/target 替换列表内容。回调接入表格、树或业务卡片，保持共享移动规则。示例按钮支持键盘，并用 aria-pressed 表达勾选状态。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const customValue = ref<TransferValue[]>(['release']);
+  const customData: TransferItem[] = [
+    { value: 'design', label: '设计评审' },
+    { value: 'develop', label: '研发联调' },
+    { value: 'release', label: '上线验证' },
+    { value: 'archived', label: '已归档', disabled: true },
+  ];
+</script>
+<template>
+<Transfer v-model="customValue" :data="customData" show-search>
+    <template #source="{ pageData, selectedKeys, disabled, onSelect }">
+      <div style="padding: 12px; display: grid; gap: 8px">
+        <button
+          v-for="item in pageData"
+          :key="item.value"
+          type="button"
+          :disabled="disabled || item.disabled"
+          :aria-pressed="selectedKeys.includes(item.value)"
+          @click="onSelect(item.value, !selectedKeys.includes(item.value))"
+        >
+          {{ selectedKeys.includes(item.value) ? '✓ ' : '+ ' }}{{ item.label }}
+        </button>
+        <span v-if="!pageData.length">没有可选任务</span>
+      </div>
+    </template>
+    <template #target="{ pageData, selectedKeys, disabled, onSelect }">
+      <div style="padding: 12px; display: grid; gap: 8px">
+        <button
+          v-for="item in pageData"
+          :key="item.value"
+          type="button"
+          :disabled="disabled || item.disabled"
+          :aria-pressed="selectedKeys.includes(item.value)"
+          @click="onSelect(item.value, !selectedKeys.includes(item.value))"
+        >
+          {{ selectedKeys.includes(item.value) ? '✓ ' : '+ ' }}{{ item.label }}
+        </button>
+        <span v-if="!pageData.length">尚未分配任务</span>
+      </div>
+    </template>
+  </Transfer>
+  <p>当前项目任务：{{ customValue }}</p>
+</template>
+```
+
+### 分页
+
+两侧页码独立，全选仅当前页。搜索或每页条数变化后回到第一页，移动使页码超出范围时自动收敛。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const pagedValue = ref<TransferValue[]>([2, 4]);
+  const pagedData: TransferItem[] = Array.from({ length: 30 }, (_, index) => ({
+    value: index + 1,
+    label: `候选成员 ${index + 1}`,
+    disabled: index === 8,
+  }));
+</script>
+<template>
+<Transfer v-model="pagedValue" :data="pagedData" :pagination="{ pageSize: 5 }" show-search />
+  <p>已分配：{{ pagedValue }}</p>
+</template>
+```
+
+### 虚拟滚动
+
+大数据列表复用库内 VirtualList。分页优先于虚拟滚动；自定义列表自行决定渲染方式。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const virtualValue = ref<TransferValue[]>([100, 500]);
+  const virtualData: TransferItem[] = Array.from({ length: 1000 }, (_, index) => ({
+    value: index + 1,
+    label: `数据项 ${index + 1}`,
+  }));
+  const virtualLog = ref('尝试滚动列表或搜索数据项 999');
+  function virtualScroll(_event: Event, type: TransferType) {
+    virtualLog.value = `${type} 列表正在滚动`;
+  }
+</script>
+<template>
+<Transfer
+    v-model="virtualValue"
+    :data="virtualData"
+    show-search
+    :virtual-list-props="{
+      height: 240,
+      threshold: 30,
+      fixedSize: true,
+      estimatedSize: 36,
+      buffer: 5,
+    }"
+    @scroll="virtualScroll"
+  />
+  <p aria-live="polite">{{ virtualLog }}</p>
+  <p>目标值：{{ virtualValue }}</p>
+</template>
+```
+
+### Form 校验联动
+
+勾选和搜索不改变字段值；实际移动才触发 change 校验。标签/必填/错误说明绑定到整个组，内部控件不会重复注册。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+  import { Transfer, Button, FormItem, Form } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const transferFormRef = ref<FormInstance>();
+  const transferForm = reactive({ members: [] as TransferValue[] });
+  const transferRules: Record<string, FieldRule[]> = {
+    members: [{ type: 'array', required: true, minLength: 2, message: '请至少分配 2 个成员' }],
+  };
+  const transferFormData: TransferItem[] = [
+    { value: 'lin', label: '林老师' },
+    { value: 'chen', label: '陈同学' },
+    { value: 'zhang', label: '张同学' },
+  ];
+  const transferFormLog = ref('');
+  async function validateTransfer() {
+    transferFormLog.value = (await transferFormRef.value?.validate()) ? '请补齐成员' : '校验通过';
+  }
+</script>
+<template>
+<Form ref="transferFormRef" :model="transferForm" :rules="transferRules" layout="vertical">
+    <FormItem field="members" label="项目成员" required>
+      <Transfer v-model="transferForm.members" :data="transferFormData" show-search />
+    </FormItem>
+    <Button type="primary" @click="validateTransfer">校验成员</Button>
+    <Button @click="transferFormRef?.resetFields()">重置</Button>
+    <p aria-live="polite">{{ transferFormLog }}</p>
+  </Form>
+</template>
+```
+
+### 空态与异步数据
+
+模型中暂时没有对应数据的值会保留，数据到达后展示。空态插槽能区分源侧、目标侧和搜索条件。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const searchValue = ref<TransferValue[]>([]);
+
+  import { reactive, ref } from 'vue';
+  import { Transfer, Button } from 'x-next';
+  import type { TransferItem, TransferValue, TransferType, FormInstance, FieldRule } from 'x-next';
+  const emptyValue = ref<TransferValue[]>(['remote']);
+  const emptyData = ref<TransferItem[]>([]);
+  function loadTransferData() {
+    emptyData.value = [
+      { value: 'remote', label: '已分配的远程成员' },
+      { value: 'new', label: '新加载的候选成员' },
+    ];
+  }
+</script>
+<template>
+<p
+    ><Button @click="loadTransferData">加载模拟数据</Button>
+    <Button @click="emptyData = []">清空数据源</Button></p
+  >
+  <Transfer v-model="emptyValue" :data="emptyData" show-search>
+    <template #empty="{ type, searchValue }"
+      ><span>{{
+        searchValue ? '没有匹配的成员' : type === 'source' ? '暂无候选成员' : '暂无已加载成员'
+      }}</span></template
+    >
+  </Transfer>
+  <p>模型值保留：{{ emptyValue }}</p>
+</template>
+```
+
+### 键盘与行为边界
+
+- Tab 到达搜索、全选、选项和方向按钮；Space 勾选复选框，Enter/Space 激活方向/移除/简单模式按钮。
+- 默认列表支持 ↑ / ↓、Home / End 定位，跳过禁用项。自定义列表由业务实现键盘语义。
+- 勾选值与目标值分别受控；传入模型而不回写时保持原值。默认值只在创建时初始化。
+- `value` 必须全局唯一，数字 `1` 和字符串 `"1"` 不同。重复项保留首项，非法值不展示；不原地修改输入数组。
+- 默认搜索不区分大小写。全选仅当前搜索结果，分页时仅当前页；已勾选的搜索隐藏项仍参与移动。
+- 禁用项不能全选、移入或移除。缺失数据的目标值在移动其他项时保留。
+- `targetOrder="original"` 按数据源排序；`append` 按模型顺序，移入值追加在已有目标值之后。
+- `pagination` 优先于 `virtualListProps`。source/target 插槽接收过滤数据和当前页数据，自行实现虚拟渲染与键盘。
+- 数组控件没有 readonly 属性；只读展示可使用 disabled。字段映射、远程分页、拖拽排序需业务适配。
+
+
+### 数据类型
+
+组合参见 [Form 表单](./form.md)、[Checkbox 复选框](./checkbox.md)、[Table 表格](./table.md)、[TreeSelect 树选择器](./tree-select.md)。
+
+
 ## Empty 扩展场景
 
 ### 用途与选型
@@ -34619,6 +35122,163 @@ type Filters = Record<string, string[]>;
 ```
 
 
+## Transfer API
+
+公开声明：`dist/components/transfer/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| data | 数据源，value 唯一，支持附加字段 | undefined &#124; TransferItem[] | 否 | [] |
+| modelValue | 见场景用法与类型 | undefined &#124; TransferValue[] | 否 | undefined |
+| defaultValue | 非受控目标初始值 | undefined &#124; TransferValue[] | 否 | [] |
+| selectedKeys | 见场景用法与类型 | undefined &#124; TransferValue[] | 否 | undefined |
+| defaultSelectedKeys | 非受控勾选初始值 | undefined &#124; TransferValue[] | 否 | [] |
+| disabled | 禁用，继承 Form | undefined &#124; false &#124; true | 否 | false |
+| loading | 加载并阻止操作 | undefined &#124; false &#124; true | 否 | false |
+| error | 错误，继承 Form | undefined &#124; false &#124; true | 否 | false |
+| simple | 点击立即移动 | undefined &#124; false &#124; true | 否 | false |
+| oneWay | 单向分配，目标逐项移除 | undefined &#124; false &#124; true | 否 | false |
+| showSearch | 两侧搜索 | undefined &#124; false &#124; true | 否 | false |
+| showSelectAll | 显示全选；simple/oneWay 目标侧不显示 | undefined &#124; false &#124; true | 否 | true |
+| title | 两侧标题，缺项按语言包回退 | undefined &#124; string[] | 否 | 未声明 |
+| operations | 向右、向左操作文案 | undefined &#124; string[] | 否 | [] |
+| searchPlaceholder | 搜索占位 | undefined &#124; string | 否 | 未声明 |
+| filterOption | 非空搜索的过滤函数 | undefined &#124; (input: string, item: TransferItem, type: TransferType) => boolean | 否 | 未声明 |
+| targetOrder | 目标排序 | undefined &#124; "append" &#124; "original" | 否 | "original" |
+| listStyle | 面板样式，可设置 width 或组件 CSS token | undefined &#124; CSSProperties | 否 | 未声明 |
+| pagination | 分页，非法 pageSize 回退 10 | undefined &#124; false &#124; true &#124; TransferPagination | 否 | false |
+| virtualListProps | VirtualList 配置，默认高度 240 | undefined &#124; VirtualListProps | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 请求更新目标模型 | undefined &#124; (_values: TransferValue[]) => any |
+| update:selectedKeys | 请求更新临时勾选模型 | undefined &#124; (_values: TransferValue[]) => any |
+| change | 实际移动，type 为目的侧 | undefined &#124; (_values: TransferValue[], _type: TransferType, _movedValues: TransferValue[]) => any |
+| select | 临时勾选变化或移动清除勾选 | undefined &#124; (_sourceSelected: TransferValue[], _targetSelected: TransferValue[]) => any |
+| search | 输入/清空/隐藏搜索重置 | undefined &#124; (_value: string, _type: TransferType) => any |
+| scroll | 列表滚动 | undefined &#124; (_event: Event, _type: TransferType) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| item | 选项内容 | undefined &#124; (props: TransferItemSlotProps) => VNodeChild |
+| source | 见场景用法与类型 | undefined &#124; (props: TransferListSlotProps) => VNodeChild |
+| target | 见场景用法与类型 | undefined &#124; (props: TransferListSlotProps) => VNodeChild |
+| source-title | 见场景用法与类型 | undefined &#124; (props: TransferTitleSlotProps) => VNodeChild |
+| target-title | 见场景用法与类型 | undefined &#124; (props: TransferTitleSlotProps) => VNodeChild |
+| footer | 两侧页脚 | undefined &#124; (props: TransferListSlotProps) => VNodeChild |
+| empty | 默认列表空态，自定义列表自行处理 | undefined &#124; (props: { type: TransferType; searchValue: string; }) => VNodeChild |
+| to-target-icon | 见场景用法与类型 | undefined &#124; () => VNodeChild |
+| to-source-icon | 见场景用法与类型 | undefined &#124; () => VNodeChild |
+| source / target | 替换对应侧列表 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| source-title / target-title | 替换标题 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| to-target-icon / to-source-icon | 方向图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TransferValue = string | number;
+
+type TransferType = 'source' | 'target';
+
+interface TransferItem {
+    value: TransferValue;
+    label: string;
+    disabled?: boolean;
+    [key: string]: unknown;
+}
+
+interface TransferPagination {
+    /** 每页条数，默认 10 */
+    pageSize?: number;
+}
+
+interface TransferProps {
+    data?: TransferItem[];
+    modelValue?: TransferValue[];
+    defaultValue?: TransferValue[];
+    selectedKeys?: TransferValue[];
+    defaultSelectedKeys?: TransferValue[];
+    disabled?: boolean;
+    loading?: boolean;
+    error?: boolean;
+    simple?: boolean;
+    oneWay?: boolean;
+    showSearch?: boolean;
+    showSelectAll?: boolean;
+    title?: string[];
+    operations?: string[];
+    searchPlaceholder?: string;
+    filterOption?: (inputValue: string, item: TransferItem, type: TransferType) => boolean;
+    targetOrder?: 'original' | 'append';
+    listStyle?: CSSProperties;
+    pagination?: boolean | TransferPagination;
+    virtualListProps?: VirtualListProps;
+}
+
+interface TransferListSlotProps {
+    type: TransferType;
+    /** 搜索过滤后的全部数据 */
+    data: TransferItem[];
+    /** 当前页数据，未分页时等于 data */
+    pageData: TransferItem[];
+    /** 本侧有效勾选值，包含搜索隐藏项 */
+    selectedKeys: TransferValue[];
+    disabled: boolean;
+    onSelect: (value: TransferValue, checked: boolean) => void;
+    onSelectAll: (values: TransferValue[], checked: boolean) => void;
+    onMove: (values: TransferValue[]) => void;
+}
+
+interface TransferTitleSlotProps {
+    type: TransferType;
+    title: string;
+    countTotal: number;
+    countSelected: number;
+    searchValue: string;
+    checked: boolean;
+    indeterminate: boolean;
+    disabled: boolean;
+    onSelectAllChange: (checked: boolean) => void;
+}
+
+interface TransferItemSlotProps {
+    item: TransferItem;
+    type: TransferType;
+    selected: boolean;
+    disabled: boolean;
+}
+
+interface TransferSlots {
+    item?: (props: TransferItemSlotProps) => VNodeChild;
+    source?: (props: TransferListSlotProps) => VNodeChild;
+    target?: (props: TransferListSlotProps) => VNodeChild;
+    'source-title'?: (props: TransferTitleSlotProps) => VNodeChild;
+    'target-title'?: (props: TransferTitleSlotProps) => VNodeChild;
+    footer?: (props: TransferListSlotProps) => VNodeChild;
+    empty?: (props: {
+        type: TransferType;
+        searchValue: string;
+    }) => VNodeChild;
+    'to-target-icon'?: () => VNodeChild;
+    'to-source-icon'?: () => VNodeChild;
+}
+
+type TransferInstance = InstanceType<typeof Transfer>;
+```
+
+
 ## TreeSelect API
 
 公开声明：`dist/components/tree-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。