@bang666/vue-cascader

在 Element Plus Cascader 基础上扩展 全选 / 取消全选 能力的 Vue 3 组件库。

特性

• 与 el-cascader API 基本兼容，可视为增强版 Cascader
• 列菜单全选：多选模式下，每一列顶部可一键全选 / 取消全选当前列节点
• 搜索结果全选：开启 filterable 时，搜索面板支持全选 / 取消全选
• 支持普通滚动与虚拟滚动（virtual-scroll）两种列表模式
• 增量样式体积小（style.css 约 0.3KB，仅含全选相关样式）

环境要求

| 依赖 | 版本 | | ------------ | --------------------- | | vue | ^3.3.0 | | element-plus | ^2.0.0（建议 ^2.13+） |

安装

pnpm add @bang666/vue-cascader
# 或
npm install @bang666/vue-cascader

快速开始

引入样式

本包 style.css 只包含全选增量样式，Element Plus 基础样式需项目自行引入：

// main.ts
import "element-plus/dist/index.css"
import "@bang666/vue-cascader/style.css"

使用组件

局部引入（推荐）：

<script setup lang="ts">
    import { ref } from "vue"
    import { Cascader } from "@bang666/vue-cascader"

    const value = ref([])
    const options = [
        {
            id: 1,
            name: "Asia",
            children: [
                { id: 2, name: "China" },
                { id: 3, name: "Japan" },
            ],
        },
    ]
</script>

<template>
    <Cascader
        v-model="value"
        :options="options"
        :props="{
            multiple: true,
            selectAll: true,
            label: 'name',
            value: 'id',
            checkStrictly: true,
            emitPath: false,
        }"
        clearable
        filterable
    />
</template>

全局注册：

import { createApp } from "vue"
import ElementPlus from "element-plus"
import VueCascader from "@bang666/vue-cascader"

const app = createApp(App)
app.use(ElementPlus)
app.use(VueCascader) // 注册为 <Cascader>
app.mount("#app")

全选配置

全选开关通过 props 传入（与 Element Plus Cascader 的 props 配置对象一致）：

| 字段 | 类型 | 默认值 | 说明 | | ----------- | --------- | ------- | ------------------------------ | | selectAll | boolean | false | 是否启用全选 | | multiple | boolean | false | 须为 true 时列菜单全选才生效 | | wrapTags | boolean | true | 标签是否自动换行 |

其余 props / 事件与 el-cascader 文档 保持一致。

样式定制

通过 CSS 变量修改全选高亮颜色：

:root {
    --el-cascader-menu-selectedAll-text-color: #f89c9c;
}

相关 class：

| Class | 说明 | | ---------------------------------------------- | -------------- | | .el-cascader-node__label.is-checked-all | 列菜单全选项 | | .el-cascader__suggestion-item.is-checked-all | 搜索结果全选项 |

在 vue-pure-admin-main 中接入

本项目已在 vue-pure-admin-main 中验证，接入方式如下。

1. 安装依赖（package.json 已包含时可跳过）

pnpm add @bang666/vue-cascader

2. 全局引入样式（src/main.ts）

import "element-plus/dist/index.css"
import "@bang666/vue-cascader/style.css"

3. 页面中使用（示例：src/views/login/index.vue）

<script setup lang="ts">
    import { Cascader } from "@bang666/vue-cascader"
</script>

<template>
    <Cascader
        v-model="selected"
        :options="options"
        :props="{
            multiple: true,
            selectAll: true,
            label: 'name',
            value: 'id',
            checkStrictly: true,
            emitPath: false,
        }"
        collapse-tags
        collapse-tags-tooltip
        :max-collapse-tags="4"
        clearable
        filterable
    />
</template>

升级后若遇 Vite 解析报错，删除消费项目缓存后重启：

rm -rf node_modules/.vite
pnpm dev

注意事项

• 必须先引入 Element Plus 样式，再引入本包 style.css
• selectAll 仅在 multiple: true 时生效
• 本包将 EP 内部依赖 external 为 element-plus/es/.../index.mjs，请保持 element-plus 版本与项目一致
• 升级本包后若遇 import 解析失败，优先清 node_modules/.vite 缓存

打包与发布

维护者发版流程见 docs/build-and-publish.md。

License

MIT