@yeepay/custom-antdv-v1-lib

Custom Ant Design Vue Library

一个基于 Ant Design Vue 1.7.8 和 Vue 2.6.14 的自定义组件库，提供高性能的虚拟滚动选择组件。

特性

• 🎯 基于 Ant Design Vue 1.7.8
• 🚀 集成 vue-virtual-scroller 实现高性能虚拟滚动
• 🔍 内置搜索功能，支持实时过滤
• ⌨️ 支持键盘导航（上下箭头、回车键）
• 🎨 完全兼容 Ant Design Vue 的样式和交互
• 📦 支持 npm 包发布
• 🔧 TypeScript 支持
• 🧪 Jest 测试支持

安装

npm install @yeepay/custom-antdv-lib vue-virtual-scroller

使用

全局注册

import Vue from 'vue';
import CustomAntdvLib from '@yeepay/custom-antdv-lib';
import 'ant-design-vue/dist/antd.css';
import 'vue-virtual-scroller/dist/vue-virtual-scroller.css';

Vue.use(CustomAntdvLib);

按需引入

import { VirtualSelect } from '@yeepay/custom-antdv-lib';
import 'ant-design-vue/dist/antd.css';
import 'vue-virtual-scroller/dist/vue-virtual-scroller.css';

export default {
  components: {
    VirtualSelect
  }
}

基础用法

<template>
  <div>
    <!-- 基础选择框 -->
    <VirtualSelect 
      :options="options"
      v-model="selectedValue"
      placeholder="请选择"
      style="width: 200px"
    />

    <!-- 自定义标签和值字段 -->
    <VirtualSelect 
      :options="customOptions"
      labelKey="name"
      valueKey="id"
      v-model="selectedId"
      placeholder="请选择用户"
      style="width: 250px"
    />

    <!-- 启用搜索功能 -->
    <VirtualSelect 
      :options="largeOptions"
      :showSearch="true"
      v-model="selectedValue"
      placeholder="搜索并选择"
      style="width: 300px"
    />

    <!-- 自定义下拉列表高度 -->
    <VirtualSelect 
      :options="options"
      :virtualScrollHeight="400"
      v-model="selectedValue"
      placeholder="自定义高度"
      style="width: 200px"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      selectedValue: '',
      selectedId: '',
      options: [
        { key: '1', value: '选项 1' },
        { key: '2', value: '选项 2' },
        { key: '3', value: '选项 3' },
        // ... 更多选项
      ],
      customOptions: [
        { id: 1, name: '张三' },
        { id: 2, name: '李四' },
        { id: 3, name: '王五' },
      ],
      largeOptions: Array.from({ length: 1000 }, (_, i) => ({
        key: String(i + 1),
        value: `选项 ${i + 1}`
      }))
    }
  }
}
</script>

组件

VirtualSelect

基于 Ant Design Vue 的 Select 组件封装，集成虚拟滚动功能，适用于大量数据的场景。

Props

参数	说明	类型	默认值
options	选项数据数组	Array	[]
value	当前选中的值	String/Number/Array	''
disabled	是否禁用	Boolean	false
placeholder	占位符文本	String	'请选择'
labelKey	选项标签字段名	String	'value'
valueKey	选项值字段名	String	'key'
itemSize	每个选项的高度（px）	Number	36
showSearch	是否启用搜索功能	Boolean	false
virtualScrollHeight	虚拟滚动容器高度（px）	Number	300

Events

事件名	说明	回调参数
input	值变化时触发	(value: String/Number/Array)
change	选择变化时触发	(value: String/Number/Array)
select	选择选项时触发	(item: Object)
search	搜索时触发	(value: String)

Methods

方法名	说明	参数
focus	获取焦点	-
blur	失去焦点	-

透传属性

支持所有 Ant Design Vue Select 组件的属性，包括但不限于：

• size - 选择框大小（large/default/small）
• loading - 加载中状态
• allowClear - 是否支持清除
• dropdownMatchSelectWidth - 下拉菜单和选择器同宽
• getPopupContainer - 菜单渲染父节点
• 等等...

数据格式

组件支持灵活的数据格式，通过 labelKey 和 valueKey 属性来指定字段映射：

// 默认格式
const options = [
  { key: '1', value: '选项 1' },
  { key: '2', value: '选项 2' }
];

// 自定义格式
const customOptions = [
  { id: 1, name: '张三' },
  { id: 2, name: '李四' }
];

// 使用自定义格式
<VirtualSelect 
  :options="customOptions"
  labelKey="name"
  valueKey="id"
/>

虚拟滚动

组件集成了 vue-virtual-scroller，能够高效处理大量数据：

• 性能优化：只渲染可见区域的选项
• 内存友好：大量数据时不会影响页面性能
• 流畅滚动：支持平滑的滚动体验
• 键盘导航：支持上下箭头键导航

虚拟滚动配置

<VirtualSelect 
  :options="largeOptions"
  :virtualScrollHeight="400"  <!-- 设置容器高度 -->
  :itemSize="36"              <!-- 设置每个选项高度 -->
  :showSearch="true"          <!-- 启用搜索 -->
/>

搜索功能

启用搜索功能后，用户可以实时过滤选项：

<VirtualSelect 
  :options="options"
  :showSearch="true"
  @search="handleSearch"
/>

搜索功能特点：

• 实时过滤，无需额外配置
• 支持中文和英文搜索
• 不区分大小写
• 支持部分匹配

键盘导航

组件支持完整的键盘导航功能：

• ↑/↓ - 上下导航选项
• Enter - 选择当前高亮选项
• Esc - 关闭下拉菜单

开发

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

本地开发调试

启动 Vue CLI 开发服务器进行组件调试：

npm run serve

这将在 http://localhost:8080 启动开发服务器，您可以在浏览器中查看和调试组件。

测试

npm run test

代码检查

npm run lint

项目结构

custom-antdv-lib/
├── src/
│   ├── components/
│   │   └── CustomSelect.vue          # 虚拟滚动选择组件
│   └── index.ts                      # 主入口文件
├── examples/                         # Vue CLI 示例项目
├── dist/                             # 构建输出目录
├── package.json
├── rollup.config.js
└── README.md

依赖

• Vue: 2.6.14
• Ant Design Vue: ^1.7.8
• vue-virtual-scroller: ^1.1.2

发布

npm publish

许可证

MIT