更新记录

1.0.0（2026-08-12）

uni-app大数据虚拟滚动选择器，支持搜索、多选、树形、懒加载和动态高度。

平台兼容性

uni-app(3.8.1)

uni-app x(3.8.1)

Virtual Select Pro

面向大数据量场景的高性能虚拟滚动选择器，适用于长分类、组织架构、城市列表、商品类目和远程搜索场景。

发布信息

插件 ID 长度为 18 个字符，未使用 uni 等保留前缀，适合直接提交插件市场。

特性

• 虚拟窗口渲染：只保留可视行和缓冲行，数据量增加不会等比例增加视图节点。
• 固定高度与动态高度：动态模式使用 uni.createSelectorQuery() 测量已渲染行，并通过前缀和与二分定位。
• 搜索能力：支持本地关键字、拼音全拼、首字母搜索，也可通过 remoteSearch 接入异步远程搜索。
• 选择模式：支持单选、多选、复选框、树形展开和懒加载。
• 跨端实现：Vue 3 Composition API + TypeScript，无第三方依赖，无直接 DOM 操作。
• 主题定制：支持 CSS Variables 覆盖主题色、行高、字号、边框和选中态。

安装与使用

通过插件市场导入后，组件位于：

uni_modules/virtual-select-pro/components/v-virtual-select/v-virtual-select.vue

手动导入示例：

<script setup lang="ts">
import { ref } from 'vue'
import VVirtualSelect from '@/uni_modules/virtual-select-pro/components/v-virtual-select/v-virtual-select.vue'

const selected = ref<number | null>(null)
const options = [
  { value: 1, label: '北京业务分类', pinyin: 'beijingyewufenlei', spell: 'bjywfl' }
]
</script>

<template>
  <v-virtual-select v-model="selected" :options="options" searchable :height="420" />
</template>

如果你的项目已配置 easycom，也可以按项目规范自动引入。

数据结构

默认字段为 value、label、children。业务字段不同可通过 valueKey、labelKey、childrenKey 指定。

type SelectOption = {
  value: string | number
  label: string
  pinyin?: string
  spell?: string
  disabled?: boolean
  hasChildren?: boolean
  children?: SelectOption[]
}

组件不内置中文转拼音字典，以控制包体积。建议服务端或数据构建阶段预写 pinyin、spell 字段。

Props

Events

Slots

实例方法

主题变量

<v-virtual-select
  :theme="{
    '--vvs-primary': '#7c3aed',
    '--vvs-selected': '#f2ebff',
    '--vvs-row-height': '48px',
    '--vvs-font-size': '15px'
  }"
/>

可用变量：--vvs-primary、--vvs-text、--vvs-muted、--vvs-border、--vvs-hover、--vvs-selected、--vvs-row-height、--vvs-font-size。

性能参考

测试配置：10,000 条扁平数据，行高 48px，容器高度 420px，buffer=8，默认行模板。结果会受设备、运行模式和业务插槽复杂度影响。

推荐：固定高度列表优先保持 dynamicHeight=false。仅在确实存在不等高内容时启用动态高度，并避免在 item 插槽内放置深层递归组件或复杂同步计算。

跨端兼容

动态高度测量使用 uni.createSelectorQuery()，未使用 window、document 或直接 DOM API。Vue 2 项目不支持本组件，请使用 Vue 3 项目模板。

使用约束

• 树形数据的 value 建议全局唯一。
• 异步 remoteSearch 应返回数组，组件会用请求序号避免慢请求覆盖新结果。
• 懒加载节点需设置 hasChildren: true 并提供 lazyLoad。
• height 应为正数或可解析的 px 值。