feikuai-element-plus-virtual-component

基于 Element Plus 的虚拟滚动级联选择器组件，支持大数据量下的高性能渲染。

特性

• 🚀 虚拟滚动 - 基于 vue-virtual-scroller 实现，支持大数据量流畅渲染
• 📦 按需加载 - 支持组件级别的按需导入，CSS 自动注入
• 🎨 样式内置 - 所有必要的 CSS 样式已内置打包，无需额外引入
• 💪 TypeScript 支持 - 完整的类型定义
• 🔧 API 兼容 - 与 Element Plus Cascader 组件 API 完全兼容

安装

# npm
npm install feikuai-element-plus-virtual-component

# pnpm
pnpm add feikuai-element-plus-virtual-component

# yarn
yarn add feikuai-element-plus-virtual-component

依赖要求

{
  "vue": ">=3.2.0",
  "element-plus": ">=2.4.0"
}

使用方式

全量导入

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import { ElCascaderV2 } from 'feikuai-element-plus-virtual-component'
import 'element-plus/dist/index.css'

const app = createApp(App)
app.use(ElementPlus)
app.component('ElCascaderV2', ElCascaderV2)

按需导入

<template>
  <el-cascader-v2
    v-model="value"
    :options="options"
    :props="cascaderProps"
    placeholder="请选择"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ElCascaderV2 } from 'feikuai-element-plus-virtual-component'

const value = ref([])
const options = ref([
  {
    value: '1',
    label: '选项1',
    children: [
      { value: '1-1', label: '选项1-1' },
      { value: '1-2', label: '选项1-2' },
    ],
  },
  // ... 更多选项
])

const cascaderProps = {
  multiple: true,
  checkStrictly: false,
}
</script>

单独导入组件

// 导入 Cascader 组件
import ElCascaderV2 from 'feikuai-element-plus-virtual-component/cascader'

// 导入 CascaderPanel 组件
import ElCascaderPanelV2 from 'feikuai-element-plus-virtual-component/cascader-panel'

API

Cascader Props

| 属性名 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | model-value / v-model | 选中项绑定值 | string \| number \| string[] \| number[] | — | | options | 可选项数据源 | CascaderOption[] | — | | props | 配置选项，详见下表 | CascaderProps | — | | size | 尺寸 | 'large' \| 'default' \| 'small' | — | | placeholder | 输入框占位文本 | string | '请选择' | | disabled | 是否禁用 | boolean | false | | clearable | 是否支持清空选项 | boolean | false | | show-all-levels | 输入框中是否显示选中值的完整路径 | boolean | true | | collapse-tags | 多选模式下是否折叠Tag | boolean | false | | max-collapse-tags | 需要显示的Tag的最大数量 | number | 1 | | collapse-tags-tooltip | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签 | boolean | false | | separator | 选项分隔符 | string | ' / ' | | filterable | 是否可搜索选项 | boolean | false | | filter-method | 自定义搜索逻辑 | (node: CascaderNode, keyword: string) => boolean | — | | debounce | 搜索关键词输入的去抖延迟，毫秒 | number | 300 | | before-filter | 筛选之前的钩子 | (value: string) => boolean \| Promise<any> | — | | popper-class | 自定义浮层类名 | string | — | | teleported | 是否将弹出框的 dom 插入到 body 元素 | boolean | true | | tag-type | 标签类型 | 'success' \| 'info' \| 'warning' \| 'danger' | 'info' | | validate-event | 输入时是否触发表单的校验 | boolean | true |

Cascader Props（配置选项）

| 属性名 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | expandTrigger | 次级菜单的展开方式 | 'click' \| 'hover' | 'click' | | multiple | 是否多选 | boolean | false | | checkStrictly | 是否严格的遵守父子节点不互相关联 | boolean | false | | emitPath | 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组 | boolean | true | | lazy | 是否动态加载子节点 | boolean | false | | lazyLoad | 加载动态数据的方法 | (node: CascaderNode, resolve: Resolve) => void | — | | value | 指定选项的值为选项对象的某个属性值 | string | 'value' | | label | 指定选项标签为选项对象的某个属性值 | string | 'label' | | children | 指定选项的子选项为选项对象的某个属性值 | string | 'children' | | disabled | 指定选项的禁用为选项对象的某个属性值 | string | 'disabled' | | leaf | 指定选项的叶子节点的标志位为选项对象的某个属性值 | string | 'leaf' |

Cascader Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | change | 当选中节点变化时触发 | (value: CascaderValue) | | expand-change | 当展开节点发生变化时触发 | (value: CascaderValue) | | visible-change | 下拉框出现/隐藏时触发 | (visible: boolean) | | remove-tag | 多选模式下移除Tag时触发 | (value: CascaderNode['valueByOption']) | | blur | 失去焦点时触发 | (event: FocusEvent) | | focus | 获得焦点时触发 | (event: FocusEvent) |

Cascader Slots

| 插槽名 | 说明 | 作用域 | | --- | --- | --- | | default | 自定义备选项的节点内容 | { node: CascaderNode, data: CascaderOption } | | empty | 无匹配选项时的内容 | — |

Cascader Exposes

| 名称 | 说明 | 类型 | | --- | --- | --- | | getCheckedNodes | 获取选中节点数组 | (leafOnly?: boolean) => CascaderNode[] | | cascaderPanelRef | cascader-panel 组件实例 | Ref<CascaderPanelInstance> | | togglePopperVisible | 切换下拉框显示/隐藏状态 | (visible?: boolean) => void |

构建

# 安装依赖
pnpm install

# 构建
pnpm build:npm

# 代码格式化
pnpm fmt

# 代码检查
pnpm lint

输出结构

dist/
├── index.js                  # 主入口
├── index.d.ts                # 类型定义
├── cascader/                 # Cascader 组件
│   ├── cascader.js
│   ├── cascader.vue.js
│   └── *.d.ts
├── cascader-panel/           # CascaderPanel 组件
│   ├── index.js
│   ├── menu.css              # 组件样式
│   └── *.d.ts
└── utils/                    # 工具函数

许可证

ISC

作者

sunshudong