更新记录

1.0.0（2026-05-26）

功能特性:

树结构展示
节点展开与收起
父子节点联动勾选
父节点半选状态显示
返回最终选中的叶子节点结果
支持通过 selectedKeys 做受控回显
支持通过 defaultExpandedKeys 控制默认展开状态

平台兼容性

uni-app x(5.0)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
√	-	5.0	-	-	-

check-tree 树形复选组件

check-tree 是一个适用于 uni-app x 的树形复选组件，支持树结构展示、节点展开收起、父子联动勾选、半选状态显示，并始终返回最终选中的叶子节点结果。

插件结构

插件目录：uni_modules/check-tree
组件目录：uni_modules/check-tree/components/check-tree/check-tree.uvue
示例页面：pages/index/index.uvue

本仓库采用“插件主体 + 根目录示例工程”的结构，便于直接发布到 DCloud 插件市场，也方便导入后立即运行示例页面。

功能特性

树结构展示
节点展开与收起
父子节点联动勾选
父节点半选状态显示
返回最终选中的叶子节点结果
支持通过 selectedKeys 做受控回显
支持通过 defaultExpandedKeys 控制默认展开状态

平台兼容性

当前版本按已完成验证情况声明以下平台：

uni-app x Web
uni-app x Android

其他平台暂未在本仓库内完成发布前验证，导入使用前建议自行补充测试。

引入方式

1. 使用 uni_modules 导入

将插件导入项目后，可直接使用组件名：

<check-tree :data="treeData" />

2. 当前示例工程中的 easycom 映射

当前示例工程已经在 pages.json 中配置 easycom：

{
  "easycom": {
    "autoscan": false,
    "custom": {
      "^check-tree$": "@/uni_modules/check-tree/components/check-tree/check-tree.uvue"
    }
  }
}

数据结构要求

组件接收的树节点必须包含以下字段：

type TreeNode = {
  key: string
  label: string
  children: TreeNode[] | null
}

字段说明：

key：节点唯一标识，必须全局唯一
label：节点显示文本
children：子节点数组；没有子节点时传 null

推荐始终显式传 children: null，不要传 undefined。

基础使用示例

<template>
  <view class="page-root">
    <check-tree
      :data="treeData"
      :selected-keys="selectedKeys"
      :default-expanded-keys="defaultExpandedKeys"
      @change="handleTreeChange"
      @update:selectedKeys="handleSelectedKeysChange"
    />
  </view>
</template>

<script setup lang="uts">
type DemoTreeNode = {
  key: string
  label: string
  children: DemoTreeNode[] | null
}

const treeData = ref([
  {
    key: 'dept-1',
    label: '一级部门',
    children: [
      {
        key: 'dept-1-1',
        label: '二级部门',
        children: [
          {
            key: 'dept-1-1-1',
            label: '三级部门A',
            children: null
          },
          {
            key: 'dept-1-1-2',
            label: '三级部门B',
            children: null
          }
        ]
      }
    ]
  }
] as DemoTreeNode[])

const selectedKeys = ref(['dept-1-1-1'] as string[])
const defaultExpandedKeys = ref(['dept-1', 'dept-1-1'] as string[])
const selectedLeafNodes = ref([] as UTSJSONObject[])

function handleTreeChange(nodes: UTSJSONObject[]) : void {
  const normalizedNodes = JSON.parse(JSON.stringify(nodes)) as UTSJSONObject[] | null
  selectedLeafNodes.value = normalizedNodes == null ? [] : normalizedNodes
}

function handleSelectedKeysChange(keys: string[]) : void {
  selectedKeys.value = keys
}
</script>

<style>
.page-root {
  flex: 1;
  flex-direction: column;
}
</style>

Props

`data`

树形数据源。

类型：TreeNode[]
默认值：[]
建议必传

说明：

组件内部会对传入数据做标准化处理，以适配 uni-app x 在不同平台上的对象类型差异
key 必须唯一，否则会影响节点勾选、展开和结果返回

`selectedKeys`

当前选中的节点 key 列表。

类型：string[]
默认值：[]

说明：

这是一个受控属性
组件实际保存的是叶子节点 key
如果传入的 key 对应的是非叶子节点，组件会自动过滤掉

`defaultExpandedKeys`

默认展开的节点 key 列表。

类型：string[]
默认值：[]

说明：

用于初始化展开状态
当外部更新该值时，组件会同步最新展开状态

`indentSize`

每一级节点的缩进宽度。

类型：number
默认值：18

说明：

单位是 px
该值越大，层级缩进越明显

Events

`change`

当勾选结果发生变化时触发。

<check-tree @change="handleTreeChange" />

返回值：

类型：TreeNode[]
内容：当前最终选中的全部叶子节点对象数组

`update:selectedKeys`

当勾选结果变化时，同步返回当前选中的叶子节点 key 数组。

<check-tree @update:selectedKeys="handleSelectedKeysChange" />

返回值：

类型：string[]
内容：当前选中的叶子节点 key 列表

Expose

组件通过 defineExpose 暴露了两个方法：

getSelectedLeafNodes()
setSelectedLeafKeys(keys: string[])

示例：

<template>
  <view class="page-root">
    <check-tree ref="treeRef" :data="treeData" />
  </view>
</template>

<script setup lang="uts">
const treeRef = ref(null)

function readSelectedNodes() : void {
  const instance = treeRef.value
  if (instance == null) {
    return
  }
  const nodes = instance.getSelectedLeafNodes()
  console.log(nodes)
}

function resetSelectedNodes() : void {
  const instance = treeRef.value
  if (instance == null) {
    return
  }
  instance.setSelectedLeafKeys(['dept-1-1-1'])
}
</script>

当前勾选规则

点击叶子节点：直接切换选中状态
点击父节点：会批量选中或取消该父节点下的全部叶子节点
父节点全部子叶子都选中：显示勾选态
父节点仅部分子叶子选中：显示半选态
父节点本身不会单独进入最终结果集合，最终返回结果永远是叶子节点

使用建议

传入节点结构时，字段类型保持稳定，不要混用数字和字符串 key
无子节点时使用 children: null
页面接收 change 返回值时，优先按 UTSJSONObject 方式读取字段
如果需要把返回值保存到页面状态，可先用 JSON.parse(JSON.stringify(nodes)) 做一次标准化

示例页面

当前仓库提供了完整演示页面：pages/index/index.uvue

可直接运行示例查看以下效果：

默认展开
默认选中
父子联动勾选
半选状态展示
结果列表回显