n-tree 树形控件

平台兼容性

App-Android	App-iOS	App-Harmony	Web	微信小程序
✓	✓	✓	✓	✓

使用说明

树形数据的展示、展开收起与节点勾选。两种选择模式：

• 多选（multiple）：每行末尾有勾选盒，点击勾选盒切换选中；默认父子关联——父勾选子孙全选、子选满父变全选、部分选中父变半选；check-strictly 开启后勾选只作用于节点自身。行点击只切换展开收起。
• 单选（默认，multiple 为 false）：点击行即选中并切换展开，同一时刻只有一个选中节点，选中行有品牌浅底高亮；checkable 为 false 时点击行只展开不选中。

值绑定 v-model：多选为选中 key 数组，单选为单个 key（无选中为 null）。

<template>
	<n-tree
		v-model="keys"
		ref="treeRef"
		:list="list"
		:multiple="true"
	/>
</template>

<script setup lang="uts">
	import { ref } from "vue";
	import { type NTreeItem } from "@/uni_modules/new-ui/components/n-tree/props";

	const keys = ref<(string | number)[]>([]);
	const treeRef = ref<NTreeComponentPublicInstance | null>(null);

	const list: NTreeItem[] = [
		{
			id: "1",
			label: "华东",
			isExpand: true,
			children: [
				{ id: "1-1", label: "上海" },
				{ id: "1-2", label: "杭州" },
				{ id: "1-3", label: "南京", disabled: true }
			]
		},
		{
			id: "2",
			label: "华南",
			children: [
				{ id: "2-1", label: "广州" },
				{ id: "2-2", label: "深圳" }
			]
		}
	];
</script>

数据项只读：展开/选中状态由组件内部管理，传入后不会被改写；初始展开与选中通过数据项的 isExpand / isChecked 声明。

实例方法（ref 类型 NTreeComponentPublicInstance）：

treeRef.value!.setCheckedKeys(["1", "2-1"]);   // 批量选中（父子关联时子孙联动）
treeRef.value!.getCheckedKeys();               // 全部选中的 key
treeRef.value!.getHalfCheckedKeys();           // 半选（父）节点的 key
treeRef.value!.clearChecked();                 // 清空选中
treeRef.value!.setExpanded("1", true);         // 设置单个节点展开
treeRef.value!.setExpandedKeys(["1", "2"]);    // 批量展开
treeRef.value!.getExpandedKeys();              // 全部展开的 key
treeRef.value!.expandAll();                    // 展开所有（有子节点的项）
treeRef.value!.collapseAll();                  // 收起所有

API

属性

属性	类型	默认值	说明
list	NTreeItem[]	[]	树形数据，按层级嵌套；传入后组件只读，展开/选中状态不回写数据项
modelValue	(string | number)[] | string | number | null	null	绑定值：多选为选中 key 数组、单选为单个 key、null = 无选中；组件勾选变化后经 update:model-value 回写
icon	string	"caret-right"	收起态的展开箭头图标名（内置图标表内的名称）
expand-icon	string	"caret-down"	展开态的展开箭头图标名
checkable	boolean	true	是否可勾选：false 时无勾选盒，单选点击行即选中
check-strictly	boolean	false	父子不关联：勾选只作用于节点自身，祖先不重算、子孙不联动
multiple	boolean	false	多选：勾选盒点选、值为 key 数组；false 为单选（点行选中、值为单 key）
label-style	string	""	微调节点文字的行内样式，如 "font-size:15px;font-weight:600"
custom-class	string	""	挂到根节点的额外 class（需是组件样式表内已定义的类）
custom-style	string	""	根节点行内样式

数据项 NTreeItem：{ id, label, children?, disabled?, isExpand?, isChecked? }——id 同级需唯一；disabled 禁用节点（不可勾选/选中，仍可展开收起）；isExpand / isChecked 为初始态，之后的展开与选中状态由组件管理。

事件

事件	参数	说明
update:model-value	(string | number)[] | string | number | null	选中变化时触发：多选为数组、单选为单 key（无选中 null）；配合 :model-value 手动双向绑定
change	同上	与 update:model-value 同参同发，用于只需要监听不需要回写的场景

插槽

无。

实例方法

方法	参数	返回	说明
clearChecked	—	void	清空全部选中（含半选态）
setChecked	key: string | number, flag: boolean	void	设置单个节点选中态；单选模式下自动清除其它选中
setCheckedKeys	keys: (string | number)[]	void	批量选中；父子关联时子孙联动并重算祖先三态
getCheckedKeys	—	(string | number)[]	全部选中节点的 key（树序）
getHalfCheckedKeys	—	(string | number)[]	半选（部分选中的父）节点的 key
setExpanded	key: string | number, flag: boolean	void	设置单个节点展开态
setExpandedKeys	keys: (string | number)[]	void	批量展开
getExpandedKeys	—	(string | number)[]	全部展开节点的 key
expandAll	—	void	展开所有有子节点的项
collapseAll	—	void	收起所有

实现说明（参考做法对照）

机制	参考做法	本库做法	理由
组件形态	双组件：容器持有逻辑，行组件递归渲染自身，经父组件实例通信	单组件：树拍平为可见节点列表渲染，状态计算全部在容器内	行组件是内部实现件、非使用者 API（演示只使用容器）；扁平化省掉递归组件与父子通信链，渲染层级更可控
状态存储	展开选中状态直接写进数据项对象（isExpand/isChecked/isHalfChecked 字段被运行时改写）	内部状态表统一管理，数据项只读；初始值仍从数据项 isExpand/isChecked/disabled 读取	组件不应改写使用者的数据；半选本是派生态，落进数据对象属副作用
行交互时机	touchstart 同时触发展开与单选选中	展开与选中在 tap 触发；touchstart 只做按压高亮	滚动浏览长树时 touchstart 已触发属误触；tap 由系统区分点击与滚动，语义准确
外部值同步	绑定值与内部不一致时批量置选、只置不清（外部无法通过绑定值减少选中）	受控对齐：外部值变化后内部选中精确对齐（含清除多余选中）	绑定值是唯一事实源；追加语义会让外部无法取消选中
勾选视觉	三态图标字体（选中/半选/未选中三个图标名，可换）	纯 CSS 自绘 20px 盒（选中实底对勾 / 半选横线 / 未选中描边空心），与复选框族视觉一致	不引入图标字形依赖；三态几何与库内复选框同源令牌，视觉统一
展开箭头	实心箭头图标一对（收起朝右 / 展开朝下），图标名可配	caret-right / caret-down 同语义，icon / expand-icon 可配	库内置图标表对应族；配置能力与参考一致
行级样式透传	透传对象按区块（行/文字/勾选盒/各态图标）批量挂类名	废除；主题令牌 + custom-class/custom-style + label-style 文字微调	透传对象已废弃；文字是最高频的微调诉求，保留直达通道
禁用节点	拦选中不拦展开，视觉降透明	一致	展开是浏览行为，禁用语义只针对选择
空数据	不回写绑定值，零行渲染	一致	空树无行可画，回写空值反而打断初始装配