更新记录

1.0.1（2026-10-17）

• 修复已知问题。

1.0.0（2026-10-17）

• uni-appx的树形组件，支持文件目录展示、单选多选、父子联动、展开折叠、手风琴模式、节点过滤及虚拟滚动，可自定义图标、连线、样式和数据字段，构建清晰流畅的层级数据交互界面。

平台兼容性

uni-app x(4.86)

umi-treeview-x

特别说明：

• 魔法上网35元/月，有需求的可以联系我(稳定，支持 Clash Verge)。
• 售卖CodeX账号，plus代充180元/月，有需求的可以联系我。
• 售卖Claude Code账号以及代充，有需求的可以联系我。
• vx: 781284440

默认外观和点击行为沿用官方文件树，通过 option 可配置图标、间距和选中背景；通过 show-checkbox 显示多选框，通过顶层 multiple 控制多选。

<umi-treeview-x node-key="id" :data="files" :default-expanded-keys="expanded" :option="{ height: 500 }" />

type TreeNode = {
  id?: string                // node-key 默认使用此字段；自定义字段须全树唯一且稳定
  label?: string             // 默认显示字段；使用 props.label 时可省略
  disabled?: boolean         // 默认禁用字段
  children?: TreeNode[]
}

Vue 和 UVue 均通过插件根目录导入类型：import type { TreeNode, TreeViewOption, TreeCheckState } from '@/uni_modules/umi-treeview-x'。根目录 index.ts / index.uts 提供公开类型入口，兼容付费加密插件，不要直接导入内部文件。更新树结构时替换根数组；传入的数据不会被组件原地修改。

<umi-treeview-x :data="files" empty-text="暂无目录" />

同时配置默认展开与默认勾选：

<umi-treeview-x
  node-key="id"
  :data="files"
  show-checkbox
  :multiple="true"
  :check-strictly="false"
  :default-expanded-keys="['workspace', 'design', 'development']"
  :default-checked-keys="['prototype', 'frontend']"
  :option="{ showIcon: true, highlight: false, height: 360 }"
/>

以上 key 应存在于 files 中；展开数组包含祖先路径。默认状态仅在初始化时读取，不触发交互事件。需要运行中修改时使用组件 ref 的展开或勾选方法。过滤属性的完整示例见「节点过滤」。

props 类型为 TreeProps（从 @/uni_modules/umi-treeview-x 导入），支持部分配置。替换配置对象或修改字段后重新解析节点；回调接收 (data: TreeNode, node: ManagedTreeNode)，data 为原始节点。

<umi-treeview-x
  :data="[{ id: 'root', name: '目录', items: [{ id: 'file', name: '文件', locked: true }] }]"
  :props="{ label: 'name', children: 'items', disabled: 'locked', class: 'custom-tree-row' }"
  show-checkbox
/>

自定义字段应在业务节点类型中声明；使用 class 定制内部行样式时，请在全局样式或允许穿透组件作用域的样式中定义对应类。叶节点由解析后的子节点数组自动判断。

option 支持部分传入，未设置的字段采用默认值；类型 TreeViewOption 从 @/uni_modules/umi-treeview-x 导入。

<umi-treeview-x node-key="id" :data="files" show-checkbox :multiple="true" :option="treeOption" />

可通过默认勾选值初始化，后续勾选由组件内部管理，通过 check 获取勾选结果：

<umi-treeview-x node-key="id" :data="files" show-checkbox :default-checked-keys="['design']" />

const treeOption = ref<TreeViewOption>({
  width: '100%',
  height: 500,
  rowHeight: 38,
  indent: 50,
  virtual: true,
  overscan: 6,
  showExpander: true,
  expandedIcon: '/static/tree/expanded.png',
  collapsedIcon: '/static/tree/collapsed.png',
  showIcon: true,
  icon: '/static/tree/folder.png',
  iconTextGap: 8,
  expanderContentGap: 6,
  highlight: true,
  highlightColor: '#2563eb',
  showLine: true,
  lineType: 'dashed'
})

隐藏某类图标后同时移除其宽度及相邻间距。修改 option 可实时生效；修改顶层 multiple 从多选切回单选时保留首个选中 ID，并通过 check-change 通知勾选状态变化；getSelectedNode() 返回首个选中节点。

连线采用 1px 灰色细线，默认虚线。竖线沿父节点展开器中心轴向下延伸，横线连接各子节点：普通子节点形成「├」分支，最后一个子节点形成「└」直角，竖线到此结束；折叠后同步收起。隐藏展开器时参考文本前图标，无图标时位于缩进区域中部。连线随树一起横向滚动，虚拟滚动仅绘制渲染范围内的线段。indent 为 0 时不绘制连线。

首页 pages/index/index 以双列卡片展示九种示例，点击进入 pages/example/example?id=0..8 详情页。详情页默认展示运行效果，支持切换代码视图和复制完整用法；代码同步当前复选框模式、连线样式，切换视图保留树状态。

九种示例：

目录树、紧凑型树和带连接线树采用浅蓝圆角背景和蓝色选中文字，仅高亮图标与文字区域；复选框示例仅显示勾选状态，不高亮文字或背景；check-strictly 为 false 时支持父子联动与半选，为 true 时独立勾选。首页通过 change 事件更新选择提示；切换示例时重新初始化选中状态，并按 default-expanded-keys 恢复初始展开状态，均支持展开全部、收起全部。

事件参数中的 data 是传入树的原始节点对象，node 是对应的内部 ManagedTreeNode（包含 key、node 原始数据、parent、children、depth、expanded、selected 等状态），component 是当前树组件实例。行由树组件直接渲染，没有独立的行组件实例。

初始默认勾选和默认展开不触发交互事件。勾选状态快照包含全部节点（包括折叠后代），半选节点不计入 checkedNodes/checkedKeys；check-strictly 为 true 或 multiple 为 false 时半选数组为空。check 只由复选框点击触发，配置变化可触发 check-change，不触发 check。复选框点击不触发 node-click 或 current-change；点击行更新当前节点，不改变复选框状态。

<umi-treeview-x
  node-key="id"
  :data="files"
  show-checkbox
  @node-click="onNodeClick"
  @check-change="onCheckChange"
  @check="onCheck"
  @current-change="onCurrentChange"
  @node-expand="onNodeExpand"
  @node-collapse="onNodeCollapse"
/>

import type { TreeNode, TreeCheckState } from '@/uni_modules/umi-treeview-x'

function onCheck(data: TreeNode, state: TreeCheckState) {
  console.log(data, state.checkedKeys, state.halfCheckedKeys)
}

组件 ref 提供 expandAll()、collapseAll()、expandNode(id)、collapseNode(id)、expandNodeBranch(id)、collapseNodeBranch(id)、expandNodesAtLevel(level) 和 getSelectedNode()。层级从 0 开始。

内部 ManagedTreeNode 对应上游 TreeNode，保存值、父子引用、层级及状态；TreeNodeManager 保存可见列表，通过插入/移除后代完成展开折叠；TreeViewAdapter 管理单选和公开操作。显式栈替代递归，以支持深层树。父子图留在响应式系统外，通过版本信号更新渲染列表。

首页采用浅灰背景、白色目录卡片和蓝色示例切换按钮，展示九种树示例入口，提供展开/收起操作及当前选择提示。顶部避让系统状态栏。横向滚动保留深层及长目录名的访问能力，文本宽度采用跨端估算值。

验证：npm run verify 检查类型、双入口、事件参数与勾选状态快照、当前节点变化、可见列表顺序、选择切换、分支操作、图标映射和一万层树；npm run build:web 使用本机 HBuilderX 构建；npm run verify:web 用 Playwright/Edge 检查首页九种示例、勾选与展开独立性、状态保留、紧凑行高、连线切换和运行时错误。默认 HBuilderX 路径 D:/office/HBuilderX，可用 HBUILDERX_HOME 覆盖。截图输出 unpackage/dist/treeview-directory.png、treeview-checkable.png、treeview-compact.png 和 treeview-lines.png。

scripts/convert-amr-icons.cjs 可从 unpackage/amr-source 中的官方 VectorDrawable XML 重新生成图标。构建使用 Vite 内置 esbuild 压缩，无需额外安装 terser。

本机已验证 Web。Android / iOS / HarmonyOS 原生编译、SVG 支持和系统动效尚待验证。源码及图标的上游版权声明见 LICENSE-AmrDeveloper.txt。

节点过滤

通过 filter-node-method 传入 (value: string, data: TreeNode, node: ManagedTreeNode) => boolean，调用组件 filter(value: string) 执行过滤。返回 false 的节点隐藏，但匹配节点的祖先保留，以展示完整路径；过滤时自动展示所有匹配路径，不修改原始展开与勾选状态。清空字符串取消过滤、恢复原展开状态；更新数据后沿用当前条件。非空过滤值必须配置回调。

<umi-treeview-x ref="tree" :data="directories" :filter-node-method="filterNode" />

function filterNode(value: string, data: TreeNode): boolean {
  return (data.label ?? '').indexOf(value) >= 0
}
// Vue: tree.value?.filter('设计')
// UVue: tree.value?.$callMethod('filter', '设计')
// 取消过滤：filter('')

对外方法

Vue 通过组件 ref 直接调用，UVue 通过 tree.value?.$callMethod('方法名', ...参数) 调用。key 使用 node-key 字段的字符串值；data 使用原始节点对象（也支持包含同一 key 的对象）。

勾选查询和设置方法仅在 show-checkbox 为 true 时生效。设置勾选遵循 multiple；setCheckedKeys / setCheckedNodes 默认遵循 check-strictly。程序设置勾选触发实际变化节点的 check-change，不触发仅用于用户点击的 check。设置当前节点触发 current-change，自动展开触发 node-expand；不触发 node-click。方法按各自用途返回结果，设置方法不返回节点数组。

// Vue
 tree.value?.setCheckedKeys(['prototype', 'frontend'])
 const checked = tree.value?.getCheckedNodes(false, true)
 tree.value?.setCurrentKey('frontend')
// UVue
 tree.value?.$callMethod('setCheckedKeys', ['prototype', 'frontend'])
 tree.value?.$callMethod('setCurrentKey', 'frontend', true)
 tree.value?.$callMethod('updateKeyChildren', 'design', [{ id: 'new', label: '新目录' }])