API 数据选择器组件

概述

ZqApiSelect 是一个通用的 API 数据选择器组件，通过调用后端 API 获取数据列表，支持分页加载、搜索过滤、单选和多选。

组件路径：web/apps/web-ele/src/components/zq-form/zq-api-selector/

组件名称：ZqApiSelect

功能特性

• 通过 API 动态加载数据
• 分页加载（触底加载更多）
• 搜索过滤
• 单选/多选模式
• 支持数据回显（通过 ID 加载）
• 自定义值字段和标签字段
• 额外信息显示

Props

属性	类型	默认值	说明
modelValue	string | string[]	-	选中的值
api	Function	必填	获取列表数据的 API 函数
apiByIds	Function	-	根据 ID 获取数据的 API 函数（用于回显）
multiple	boolean	false	是否多选
placeholder	string	'请选择'	占位符
disabled	boolean	false	是否禁用
clearable	boolean	true	是否可清除
filterable	boolean	true	是否可搜索
valueField	string	'id'	值字段名
labelField	string	'name'	标签字段名
extraField	string	-	额外信息字段名
dialogTitle	string	'请选择'	弹窗标题
dialogWidth	string	'45%'	弹窗宽度
pageSize	number	20	每页数量

API 函数签名

// 列表 API
interface ListApiParams {
  page: number;
  pageSize: number;
  keyword?: string;
}

interface ListApiResult {
  items: any[];
  total: number;
}

type ListApi = (params: ListApiParams) => Promise<ListApiResult>;

// 根据 ID 获取 API
type ApiByIds = (ids: string[]) => Promise<any[]>;

Events

事件	参数	说明
update:modelValue	string | string[]	值更新
change	string | string[]	选中值变化

Expose 方法

方法	参数	说明
openModal	-	打开选择弹窗

使用示例

基本用法

<template>
  <ZqApiSelect
    v-model="userId"
    :api="getUserList"
    :api-by-ids="getUsersByIds"
    value-field="id"
    label-field="name"
    placeholder="请选择用户"
  />
</template>

<script setup>
import { ref } from 'vue';
import { getUserListApi, getUsersByIdsApi } from '@/api/user';

const userId = ref('');

const getUserList = async (params) => {
  const result = await getUserListApi(params);
  return { items: result.data, total: result.total };
};

const getUsersByIds = async (ids) => {
  return await getUsersByIdsApi(ids);
};
</script>

多选模式

<template>
  <ZqApiSelect
    v-model="userIds"
    :api="getUserList"
    :api-by-ids="getUsersByIds"
    :multiple="true"
    dialog-title="选择用户"
  />
</template>

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

const userIds = ref([]);
</script>

显示额外信息

<template>
  <ZqApiSelect
    v-model="productId"
    :api="getProductList"
    value-field="id"
    label-field="name"
    extra-field="price"
    placeholder="请选择产品"
  />
</template>

与表单设计器集成

在表单设计器中，该组件作为 api-selector 类型的表单项使用：

{
  "type": "api-selector",
  "field": "user_id",
  "label": "用户",
  "props": {
    "apiUrl": "/api/users",
    "apiByIdsUrl": "/api/users/batch",
    "valueField": "id",
    "labelField": "name",
    "multiple": false,
    "pageSize": 20
  }
}

典型应用场景

• 用户选择：从用户列表中选择用户
• 产品选择：从产品列表中选择产品
• 数据关联：选择关联的数据记录
• 动态数据：需要从 API 动态加载的选择场景