Transfer 穿梭框

用于在两个面板之间进行数据交互，支持单选/多选、分组折叠、搜索过滤、静态数据源 / 远程数据源等功能。

业务项目中请确保已引入组件库样式：

import '@whhx/ui/index.css'

基础用法（options 模式）

通过 options 传入静态选项列表，v-model 绑定选中值。

单选 / 多选

单选

选择人员

张三

李四

王五

赵六

钱七

孙八

已选中人员

值:

多选

选择人员

全选

张三

李四

王五

赵六

钱七

孙八

已选中人员

值:

<template>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">单选</p>
      <hx-transfer
        v-model="value1"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        height="320px"
      />
      <p class="demo-value">值: {{ value1 }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">多选</p>
      <hx-transfer
        v-model="value2"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        multiple
        height="320px"
      />
      <p class="demo-value">值: {{ value2 }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxTransfer } from "@whhx/ui"
import type { TransferOption } from "@whhx/ui"

const value1 = ref("")
const value2 = ref("")

const staticOptions: TransferOption[] = [
  { label: "张三", value: "1" },
  { label: "李四", value: "2" },
  { label: "王五", value: "3" },
  { label: "赵六", value: "4", disabled: true },
  { label: "钱七", value: "5" },
  { label: "孙八", value: "6" },
]
</script>

分组数据（options 模式）

当 options 传入分组格式数据时，左侧面板会按分组展示，支持展开/折叠分组。

分组数据，可折叠分组

分组数据（可折叠分组）

选择人员

折叠分组全选

▶研发部(3)

张三✓

李四

王五✓

▶产品部(2)

赵六

钱七

▶运营部(3)

孙八

周九

吴十

已选中人员

清空

张三×

王五×

值: 1,3

<template>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">分组数据（可折叠分组）</p>
      <hx-transfer
        v-model="value"
        :options="groupOptions"
        config-text="人员"
        title="选择人员"
        multiple
        height="360px"
      />
      <p class="demo-value">值: {{ value }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxTransfer } from "@whhx/ui"
import type { TransferGroup } from "@whhx/ui"

const value = ref("1,3")

const groupOptions: TransferGroup[] = [
  {
    label: "研发部",
    options: [
      { label: "张三", value: "1" },
      { label: "李四", value: "2" },
      { label: "王五", value: "3" },
    ],
  },
  {
    label: "产品部",
    options: [
      { label: "赵六", value: "4" },
      { label: "钱七", value: "5" },
    ],
  },
  {
    label: "运营部",
    options: [
      { label: "孙八", value: "6" },
      { label: "周九", value: "7" },
      { label: "吴十", value: "8" },
    ],
  },
]
</script>

多选值类型

通过 multiple 开启多选。modelValueType 控制多选时 emit 的值类型：

• modelValueType="string"（默认）：emit 逗号拼接字符串，如 "1,2,3"，适合直接提交给后端
• modelValueType="array"：emit 字符串数组，如 ["1","2","3"]，适合前端做进一步处理

多选时 modelValueType 两种模式对比

多选（modelValueType="string"，默认）

选择人员

全选

张三

李四

王五

赵六

已选中人员

typeof: string，JSON: ""

多选（modelValueType="array"）

选择人员

全选

张三

李四

王五

赵六

已选中人员

Array.isArray: true，JSON: []

<template>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">多选（modelValueType="string"，默认）</p>
      <hx-transfer
        v-model="value1"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        multiple
        height="320px"
      />
      <p class="demo-value">typeof: {{ typeof value1 }}，JSON: {{ JSON.stringify(value1) }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">多选（modelValueType="array"）</p>
      <hx-transfer
        v-model="value2"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        multiple
        model-value-type="array"
        height="320px"
      />
      <p class="demo-value">Array.isArray: {{ Array.isArray(value2) }}，JSON: {{ JSON.stringify(value2) }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxTransfer } from "@whhx/ui"
import type { TransferOption } from "@whhx/ui"

const value1 = ref("")
const value2 = ref<string[]>([])

const staticOptions: TransferOption[] = [
  { label: "张三", value: "1" },
  { label: "李四", value: "2" },
  { label: "王五", value: "3" },
  { label: "赵六", value: "4" },
]
</script>

远程数据（remote 模式）

传入 remote 配置自动请求远端接口获取 options，支持 GET/POST、参数映射、响应数据映射。

静态数据 / 远程请求 / 多选

<template>
  <ClientOnly>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">静态数据（单选）</p>
      <hx-transfer
        v-model="value1"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        height="320px"
      />
      <p class="demo-value">值: {{ value1 }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">静态数据（多选）</p>
      <hx-transfer
        v-model="value2"
        :options="staticOptions"
        config-text="人员"
        title="选择人员"
        multiple
        height="320px"
      />
      <p class="demo-value">值: {{ value2 }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">remote（单选）</p>
      <hx-transfer
        v-model="value3"
        :remote="remoteConfig"
        config-text="人员"
        title="选择人员"
        height="320px"
      />
      <p class="demo-value">值: {{ value3 }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">remote 分组（多选）</p>
      <hx-transfer
        v-model="value4"
        :remote="groupRemoteConfig"
        config-text="人员"
        title="选择人员"
        multiple
        height="320px"
      />
      <p class="demo-value">值: {{ value4 }}</p>
    </div>
  </div>
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxTransfer } from "@whhx/ui"
import type { TransferOption, TransferRemoteConfig } from "@whhx/ui"

const value1 = ref("")
const value2 = ref("")
const value3 = ref("")
const value4 = ref("")

const staticOptions: TransferOption[] = [
  { label: "张三", value: "1" },
  { label: "李四", value: "2" },
  { label: "王五", value: "3" },
]

const remoteConfig: TransferRemoteConfig = {
  url: "/api/options/select",
}

const groupRemoteConfig: TransferRemoteConfig = {
  url: "/api/options/select-group",
}
</script>

API

Props

参数	说明	类型	默认值
v-model	绑定值（单选始终为字符串，多选取决于 modelValueType）	string | string[]	''
modelValueType	多选时 emit 的值类型，"string" 为逗号拼接字符串，"array" 为数组	'string' | 'array'	'string'
options	静态选项列表（优先级低于 remote，支持单层或分组格式）	TransferOption[] | TransferGroup[]	-
remote	远程数据获取配置	TransferRemoteConfig	-
title	左侧面板标题，默认 configText + '列表'	string	-
leftWidth	左侧面板宽度	string	'300px'
configText	自定义文案，默认 '人员'	string	'人员'
placeholder	搜索框占位文本	string	''
multiple	是否多选，默认单选	boolean	false
height	整体高度（同时控制左右两侧）	string	'400px'
labelKey	选项 label 字段名	string	'label'
valueKey	选项 value 字段名	string	'value'

TransferOption

interface TransferOption {
  label: string
  value: string | number
  disabled?: boolean
}

TransferGroup

interface TransferGroup {
  label: string             // 分组名称（渲染为分组标题）
  options: TransferOption[] // 分组下的选项列表
}

TransferRemoteConfig

继承自 RemoteConfig，分组数据的分组名称固定使用 label，选项列表固定使用 options，与 Select 保持一致。

参数	说明	类型	默认值
url	请求地址	string	-
method	请求方法	'get' | 'post'	'get'
params	URL query 参数	Record<string, any>	-
body	请求体参数（POST）	Record<string, any>	-
labelKey	响应中 label 字段名	string	'label'
valueKey	响应中 value 字段名	string	'value'