更新记录

1.1.0（2026-09-26） 下载此版本

Changed

• Breaking: style: 组件样式与 indent 缩进单位由 rpx 改为 px。

Fixed

• playground: 示例页标签栏改用原生吸顶，修复支付宝真机切换不灵敏。
• style: 选中背景改为过渡背景色，减少下方节点抖动。

1.0.0（2026-09-15） 下载此版本

Added

• virtual: scrollToKey 返回定位指令提交语义。

Changed

• virtual: 无可滚动范围时不安排偏移测量。
• core: 可见节点保持响应式引用。
• virtual: 固定渲染窗口多覆盖一行，避免行内滚动重建窗口。
• virtual: 优化虚拟滚动定位与位置校正。
• core: 减少选中态计算与响应式依赖收集的开销。

Fixed

• test: 归一化 dev-docs 子进程环境变量大小写。
• build: 分发检查忽略 Finder 元数据。
• virtual: 适配支付宝小程序查询作用域。
• core: 已可见的命中节点仍登记自身匹配。
• virtual: 修正虚拟滚动位置校正。
• core: 虚拟模式定位后释放 scroll-top 指令值。
• core: 滚动停稳后校正虚拟列表的渲染窗口。
• core: 小程序端筛选后把夹紧的滚动位置写回 scroll-view。
• build: 修正 pnpm build 因引号问题导致的空运行。
• core: 修正虚拟列表在可见项减少后的滚动位置。

0.6.4（2026-08-27） 下载此版本

Changed

• dcloud: 重新发布插件市场版本，补充插件预览图并完善市场条目元数据。

平台兼容性

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 作为精简的文档导航入口。

版本与兼容性： 当前发布版本以 npm 和 CHANGELOG 为准。1.0.0 起按语义化版本维护公开 API；兼容性边界及最终组件体积的测量方式见版本兼容性与组件体积。H5 已有构建和交互验证，微信/支付宝目前主要是构建验证，不代表所有真机都已验证。

特性

• 🌲 展开收起、单选/多选、父子联动、严格模式、禁用节点
• 🔍 关键词过滤、自定义匹配、命中高亮
• ⚡ 固定行高虚拟渲染，只渲染可视区域，适合大数据树
• 🔌 懒加载子节点，内置加载中、加载失败和重试状态
• 🎨 主题色、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）。两种方式的取舍见安装说明。

插件市场迁移说明：插件市场自 0.6.3 起使用新的 插件条目（id=29379）。0.6.2 及更早版本可能来自旧条目，导入目录为 uni_modules/KieranYin9527-tree；如果本地仍有旧目录，请先删除，再导入 uni_modules/keryin-tree-view。npm 包不受影响。

使用

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 check:all   # 完整本地校验，不升版本、不发布
pnpm build       # 构建组件包
pnpm docs        # 本地文档站

提交前按变更范围选择检查，不需要每次提交都发布；需要完整校验时只运行一次 pnpm check:all。详细流程见 CONTRIBUTING.md。

License

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

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