更新记录

1.0.0（2026-10-14） 下载此版本

• 首次发布
• 底部弹窗承载树形下拉选择器，触发器点击展开面板，头部「取消 / 标题 / 确定」三段式布局
• 支持单选与多选（multiple），多选默认父子联动：勾选父节点自动勾选全部子节点，子节点全选则父节点自动勾选，存在部分勾选时父节点显示半选态横线
• 新增 check-strictly，打开后父子各选各的、互不影响
• 新增 searchable，可按文案搜索；搜索时自动展示命中节点及其祖先、子孙
• 新增 field-names，可自定义取值 / 文案 / 子节点字段名（默认 value / label / children，未命中时自动回退 id / key 与 label / name / title）
• 新增 show-path，单选回显完整路径（分隔符可用 path-separator 配置）
• 新增 only-leaf，单选时父节点仅可展开、只能选择叶子节点
• 新增 max-tag-count，多选回显超出数量时显示「已选 N 项」
• 新增 default-expand-all，关闭后默认折叠，打开面板时自动展开选中项所在分支
• 新增 theme-color 主题色，作用于选中文字、勾选框与「确定」按钮
• 多选面板底部实时显示已选数量，并提供「清空」
• 支持 v-model 双向绑定、change / open / cancel / confirm 事件、默认插槽自定义触发器、ref 调用 open() / closePanel()
• 不依赖任何第三方插件，纯 view / scroll-view 实现，兼容 vue2 / vue3 与各小程序平台

平台兼容性

uni-app(3.8.5)

qw24-tree-select 树形下拉选择器

一个开箱即用的 uni-app 树形下拉选择器：点击触发器从底部弹窗展开一棵可展开 / 收起的多层级树，支持单选与多选。多选默认父子联动（勾父带子、子全勾则父自动勾选、半选显示横线），也可切换为父子独立；另有搜索、自定义字段名、完整路径回显、只选叶子、主题色等能力。

平台兼容性

最低版本要求：HBuilderX 3.6.0（vue2 / vue3 项目均可），组件本身只依赖 scroll-view、插槽、计算属性等基础能力，无任何第三方依赖。

• HBuilderX 3.5.0+ 支持 pages_init.json，导入插件时会自动提示合并示例页路由，低于该版本需自己把示例页加到 pages.json；
• 该插件不支持 uni-app x（uvue），uni-app x 平台未声明支持。

安装

1. 在插件市场本插件详情页点击「使用 HBuilderX 导入插件」，选择你的项目；
2. 或把 qw24-tree-select 目录直接复制到项目的 uni_modules 目录下；
3. 示例页面 uni_modules/qw24-tree-select/pages/tree-select/tree-select.vue 可直接运行查看效果（首次导入时会提示合并页面路由）。

组件符合 easycom 规范，无需 import，直接使用标签 <qw24-tree-select> 即可。

如果标签不渲染、点击没有反应，说明编译期没有扫描到这个 easycom 组件（新拷贝进项目的 uni_modules 目录需要重新扫描一次），此时：

• 停止运行后重新运行项目，或重启 HBuilderX 后再运行；
• 也可以显式引入组件（组件无法解析时的兜底方案）：

import Qw24TreeSelect from '@/uni_modules/qw24-tree-select/components/qw24-tree-select/qw24-tree-select.vue';

export default {
    components: { Qw24TreeSelect }
};

基本用法

<template>
    <view>
        <qw24-tree-select v-model="value" :options="treeData" title="选择地区" @change="handleChange" />
    </view>
</template>

<script>
    export default {
        data() {
            return {
                value: null,
                treeData: [{
                    value: 'zhejiang',
                    label: '浙江',
                    children: [
                        { value: 'hangzhou', label: '杭州' },
                        { value: 'ningbo', label: '宁波' }
                    ]
                }]
            };
        },
        methods: {
            handleChange(e) {
                console.log(e.value, e.values, e.nodes, e.paths);
            }
        }
    };
</script>

v-model 的值：

• 单选（默认）：节点的 value（如 'hangzhou'），未选择为 null；
• 多选（multiple）：节点 value 组成的数组（如 ['hangzhou', 'ningbo']），未选择为 []。

vue2 项目同样使用 v-model，组件内部已兼容 value + input。

数据结构

默认字段为 value / label / children：

[{
    value: 'zhejiang',
    label: '浙江',
    children: [
        { value: 'hangzhou', label: '杭州', children: [{ value: 'xihu', label: '西湖' }] }
    ]
}]

• 取值字段未命中时自动回退 id、key；文案字段未命中时自动回退 label、name、title，一般无需配置；
• 字段完全不匹配时，用 field-names 指定：

<qw24-tree-select v-model="value" :options="orgData" multiple
    :field-names="{ value: 'id', label: 'name', children: 'children' }" />

• 层级不限，任意深度都会按缩进渲染；children 为空或不存在即视为叶子节点。

单选 / 多选

<!-- 单选：点选节点后点「确定」 -->
<qw24-tree-select v-model="value" :options="treeData" />

<!-- 单选：只允许选叶子节点，点父节点只展开 -->
<qw24-tree-select v-model="value" :options="treeData" only-leaf />

<!-- 多选：父子联动（默认） -->
<qw24-tree-select v-model="values" :options="treeData" multiple />

<!-- 多选：父子独立，各选各的 -->
<qw24-tree-select v-model="values" :options="treeData" multiple check-strictly />

多选交互说明（check-strictly 关闭时，即默认）：

• 勾选父节点 → 其全部子孙节点一并勾选；取消父节点 → 子孙一并取消；
• 子节点全部勾选 → 父节点自动勾选；只有部分勾选 → 父节点显示半选态（横线）；
• 打开面板时会依据传入的 v-model 自底向上补齐父节点状态。

搜索

<qw24-tree-select v-model="values" :options="treeData" multiple searchable search-placeholder="搜索名称" />

输入关键字后按文案模糊匹配（不区分大小写），命中的节点连同其祖先与子孙一并展示，方便定位层级。

回显

• 单选默认回显节点文案；show-path 打开后回显完整路径（如「浙江 / 杭州 / 西湖」），分隔符用 path-separator 配置；
• 多选回显各节点文案并用「、」拼接；数量超过 max-tag-count（默认 3）时显示「已选 N 项」，设为 0 则全部展示。

属性

事件

回调参数说明：

• value：单选为节点 value，多选为 value 数组；
• values / labels：均摊平为数组，便于统一处理；
• nodes：命中的完整节点对象（含 value / label / level / parentValue / path / children）；
• paths：每个节点的完整路径文案数组，如 [['浙江','杭州','西湖']]。

方法

通过 ref 调用：

Slots

<qw24-tree-select v-model="value" :options="treeData">
    <view class="my-trigger">所在地区：{{ value || '未选择' }}</view>
</qw24-tree-select>

说明

• 主题色通过 theme-color 配置（默认 #2979ff），作用于选中节点文字、勾选框（含半选态描边）、面板底部「清空」与「确定」按钮；支持 #RRGGBB 与 #RGB。
• 面板由「头部 + 搜索（可选）+ 树列表 + 多选底部栏（可选）」组成，树列表用 scroll-view 滚动，层级通过左侧缩进与展开箭头区分，箭头点击只负责展开 / 收起，不改变选择。
• 多选默认父子联动（check-strictly 为 false），联动结果会体现在 v-model 中；若业务上希望父子互不影响，传 check-strictly。
• 「取消」或点击遮罩关闭面板时不会修改 v-model，只有点「确定」才会提交；面板打开时会基于当前 v-model 重置待选状态。
• 组件不依赖任何第三方插件，样式可自行覆盖（类名前缀统一为 qts-）。