更新记录

0.6.3（2026-08-24） 下载此版本

Removed

• core: 移除 0.3.0 起标记废弃的过渡别名 packDisabledkey / pack-disabledkey，统一使用规范命名 packDisabledKey / pack-disabled-key。行为与默认值（true）不变，仍在使用旧拼写的工程改用新名即可。

Changed

• dcloud: 插件 ID 由 KieranYin9527-tree 改为 keryin-tree-view，从市场导入后的插件目录名随之变化。已装旧版的工程需删除 uni_modules/KieranYin9527-tree（CLI 工程为 src/uni_modules/KieranYin9527-tree）后再导入新版，并把显式的类型导入路径改指向新目录；npm 通道不受影响。

平台兼容性

uni-app(4.15)

其他

Uni Tree View（uni_modules 插件）

插件已按 uni_modules 规范导入，组件目录符合 easycom 约定。在项目保持 easycom 自动扫描开启时，模板里直接写 <uni-tree-view> 即可，不需要 import：

<template>
  <uni-tree-view :data="treeData" />
</template>

需要 TypeScript 类型时从插件目录导入：

// CLI 工程（插件在 src/uni_modules 下，`@` 指向 src）
import type { TreeDataItem, UniTreeViewExposed } from "@/uni_modules/keryin-tree-view";

如果 HBuilderX 可视化工程没有配置 @ 别名，应改用相对路径指向 uni_modules/keryin-tree-view；如果工程自行配置了别名，则以实际配置为准。

下面是与 npm 包共用的完整说明，其中「npm 方式」一节只适用于 npm 通道。

uni-tree-view

适用于 uni-app + Vue 3 的跨端树形列表/选择组件，一套代码运行在微信小程序、支付宝小程序和 H5。

📖 完整文档 · 在线演示 · 快速上手 · API 参考 · 常见问题

文档站双线部署，内容原则上保持一致：主入口为 GitHub Pages（上方链接）；访问较慢时可切换到 Netlify 镜像。

使用 AI Coding 工具时，可将 llms.txt 作为精简的文档导航入口。

项目状态： 当前处于 0.x 早期阶段。核心能力已有自动化测试，并完成 H5 交互验证及微信/支付宝小程序构建验证；但在 1.0.0 前公开 API 和边界行为仍可能调整，升级前请查阅 CHANGELOG。

特性

• 🌲 展开收起、单选/多选、父子联动、严格模式、禁用节点
• 🔍 关键词过滤、自定义匹配、命中高亮
• ⚡ 固定行高虚拟渲染，只渲染可视区域，适合大数据树
• 🔌 懒加载子节点，内置加载中、加载失败和重试状态
• 🎨 主题色、node-class 以及文本、图标、尾部内容和空状态插槽自由定制
• 📦 零运行时依赖，npm 与 DCloud 插件市场双通道分发

安装

pnpm add uni-tree-view

推荐使用 npm；也可以在 DCloud 插件市场 导入 Uni Tree View，插件按 uni_modules 规范发布，导入后位于 uni_modules/keryin-tree-view（CLI 工程为 src/uni_modules/keryin-tree-view）。两种方式的取舍见安装说明。

使用

npm 方式

通过 npm 安装后需要导入组件：

<template>
  <uni-tree-view
    v-model="checkedValue"
    selectable
    multiple
    :data="treeData"
    @check-change="handleCheckChange"
  />
</template>

<script setup>
import UniTreeView from "uni-tree-view";
import { ref } from "vue";

const checkedValue = ref([]);
const treeData = [
  {
    id: "building-a",
    label: "A 栋",
    children: [
      { id: "floor-a-1", label: "1 层" },
      { id: "floor-a-2", label: "2 层", disabled: true }
    ]
  }
];

function handleCheckChange({ keys }) {
  console.log("当前选中:", keys);
}
</script>

DCloud 插件市场方式

从插件市场导入到 uni_modules 后，在 easycom 保持自动扫描开启时，无需手动 import：

<template>
  <uni-tree-view
    v-model="checkedValue"
    selectable
    multiple
    :data="treeData"
    @check-change="handleCheckChange"
  />
</template>

<script setup>
import { ref } from "vue";

const checkedValue = ref([]);
const treeData = [
  {
    id: "building-a",
    label: "A 栋",
    children: [
      { id: "floor-a-1", label: "1 层" },
      { id: "floor-a-2", label: "2 层", disabled: true }
    ]
  }
];

function handleCheckChange({ keys }) {
  console.log("当前选中:", keys);
}
</script>

selectable 控制是否启用选择，multiple 控制单选/多选：

禁用节点默认锁定当前选中状态。全选、清空、父子联动、实例方法以及外部更新 v-model 时，都不会改变它；需要允许变更时传入 checked-disabled。

普通 class 作用于组件根容器；需要使用自己的类名定制每个节点行时，传入 node-class：

<uni-tree-view
  class="department-tree"
  node-class="department-tree-node"
  :data="treeData"
/>

tree-props 只负责数据字段映射，不包含样式配置。

完整的属性、事件、插槽和实例方法（Props / Events / Slots / Methods），以及懒加载与虚拟渲染示例，请见 文档站。

平台兼容性

点击反馈、内联图标和 scroll-view 虚拟滚动等实现说明，见 平台兼容性文档。

开发

pnpm install
pnpm play        # H5 playground
pnpm test        # 单元测试
pnpm build       # 构建组件包
pnpm docs        # 本地文档站

贡献前请阅读 CONTRIBUTING.md。

License

本项目使用 MIT 许可证，版权归 OFreshman 所有。再分发源码、构建产物或主要部分时，请保留版权声明和许可证全文；MIT 不要求在产品界面展示作者名。

使用或改造时的保留要求、推荐署名格式和第三方许可说明，见 许可证与署名说明。