UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本篇文章基于 NG-ZORROng-zorro-antd开源仓库中components/tree/demo/basic-controlled.ts与basic-controlled.md这一官方受控示例系统讲解nz-tree组件在受控模式下的核心用法如何通过nzCheckedKeys、nzExpandedKeys、nzSelectedKeys三个输入属性初始化勾选、展开、选中状态如何监听nzClick、nzExpandChange、nzCheckboxChange事件以及受控状态下数据同步与底层实现的原理。读者学完本文后可以独立写出可复制的树形结构受控场景如权限勾选、目录展开记忆、列表选中回显并能结合源码理解各状态之间的联动关系。一、示例概览一个受控的树长什么样官方示例位于 components/tree/demo/basic-controlled.ts对应说明文档 components/tree/demo/basic-controlled.mdzh-CN 标题为受控操作示例en-US 为 basic controlled example默认示例。受控的含义是树的关键状态勾选、展开、选中不再由组件内部自己记忆而是由外部通过输入属性传入、通过输出事件回传从而让开发者在父组件中拥有状态的绝对主导权。示例组件的模板如下源码nz-tree [nzData]nodes nzCheckable nzMultiple [nzCheckedKeys]defaultCheckedKeys [nzExpandedKeys]defaultExpandedKeys [nzSelectedKeys]defaultSelectedKeys (nzClick)nzEvent($event) (nzExpandChange)nzEvent($event) (nzCheckboxChange)nzEvent($event) /对应的组件类import { Component } from angular/core; import { NzFormatEmitEvent, NzTreeModule } from ng-zorro-antd/tree; Component({ selector: nz-demo-tree-basic-controlled, imports: [NzTreeModule], template: /* 见上方模板 */ }) export class NzDemoTreeBasicControlledComponent { defaultCheckedKeys [0-0-0]; defaultSelectedKeys [0-0-0]; defaultExpandedKeys [0-0, 0-0-0, 0-0-1]; readonly nodes [ /* 三层树形数据见下文 */ ]; nzEvent(event: NzFormatEmitEvent): void { console.log(event); } }关键点提炼nzCheckable开启节点前的复选框nzMultiple允许同时选中多个节点defaultCheckedKeys默认勾选0-0-0defaultSelectedKeys默认选中0-0-0defaultExpandedKeys默认展开0-0、0-0-0、0-0-1三个非叶子节点三个输出事件统一交给nzEvent在控制台打印NzFormatEmitEvent结构便于观察每次交互产生的完整数据。二、受控三件套checked / expanded / selected 的状态注入受控示例的核心是这三个字符串数组输入属性它们的完整定义与默认值如下来自组件 API 文档 components/tree/doc/index.en-US.md属性作用类型默认值[nzCheckedKeys]指定默认勾选的节点 key 列表string[][][nzExpandedKeys]指定默认展开的节点 key 列表string[][][nzSelectedKeys]指定默认选中的节点 key 列表string[][]注意示例中三者的取值defaultExpandedKeys只包含0-0、0-0-0、0-0-1三个非叶子节点叶节点如0-0-0-0、0-0-2不在其中——这是合理设计因为叶子节点没有可展开的子层级无需也不应出现在展开列表里测试用例也验证了这一点见下文源码验证。树数据nzData的结构受控状态都通过 key 引用节点因此nzData中的key必须全局唯一。示例数据为三层结构readonly nodes [ { title: 0-0, key: 0-0, expanded: true, // NzTreeNodeOptions 也支持在数据里直接声明状态 children: [ { title: 0-0-0, key: 0-0-0, children: [ { title: 0-0-0-0, key: 0-0-0-0, isLeaf: true }, { title: 0-0-0-1, key: 0-0-0-1, isLeaf: true }, { title: 0-0-0-2, key: 0-0-0-2, isLeaf: true } ] }, { title: 0-0-1, key: 0-0-1, children: [ { title: 0-0-1-0, key: 0-0-1-0, isLeaf: true }, { title: 0-0-1-1, key: 0-0-1-1, isLeaf: true }, { title: 0-0-1-2, key: 0-0-1-2, isLeaf: true } ] }, { title: 0-0-2, key: 0-0-2, isLeaf: true } ] }, { title: 0-1, key: 0-1, children: [ { title: 0-1-0-0, key: 0-1-0-0, isLeaf: true }, { title: 0-1-0-1, key: 0-1-0-1, isLeaf: true }, { title: 0-1-0-2, key: 0-1-0-2, isLeaf: true } ] }, { title: 0-2, key: 0-2, isLeaf: true } ];NzTreeNodeOptions的常用字段及默认值详见组件文档的 NzTreeNodeOptions props 表字段含义默认值title节点标题---key节点唯一标识必须唯一nullicon节点前图标配合nzShowIconnullchildren子节点数组[]isLeaf是否为叶子节点不可作为拖放目标falsechecked/selected/expanded数据中直接声明的勾选/选中/展开状态falseselectable节点是否可选truedisabled是否禁用节点falsedisableCheckbox是否禁用节点复选框false[key: string]索引签名允许携带任意自定义字段通过NzTreeNode.origin读取-示例中顶层节点0-0直接声明了expanded: true说明状态除了通过受控数组注入外也能在数据源里预置。三、底层原理状态如何从数组落到每一个节点受控数组并不是简单的过滤展示而是由 NzTreeComponent 在ngOnChanges中统一处理——每当任一输入属性变化都会调用renderTreePropertiestree.component.ts#L304-L364按固定顺序处理各类状态nzData变化 →handleNzData初始化整棵树nzCheckedKeys变化 →handleCheckedKeys→conductChecknzExpandedKeys/nzExpandAll变化 →handleExpandedKeys→conductExpandedKeysnzSelectedKeys变化 →handleSelectedKeys→conductSelectedKeys最后把结果扁平化flattenTreeData渲染到列表。这三个传导方法都在基类服务 nz-tree-base.service.ts 中实现勾选传导conductCheck(keys, checkStrictly)nz-tree-base.service.ts#L485-L509递归遍历所有节点把keys数组转成Set判断命中设置每个节点的isChecked与isHalfChecked最后调用refreshCheckState依据父子关系自动补齐全选与半选状态。nzCheckStrictly为true时则完全独立父子互不影响。展开传导conductExpandedKeys(keys)nz-tree-base.service.ts#L511-L526同样以Set判断命中调用setExpanded并维护展开节点列表。选中传导conductSelectedKeys(keys, isMulti)nz-tree-base.service.ts#L528-L549先清空所有节点的选中状态再按 key 命中设置isSelectedisMulti为false时命中第一个即停止递归保证单选语义。由此可以推断受控模式下展开/选中/勾选三者的状态读写都是围绕NzTreeNode实例nz-tree-base-node.ts进行的key 只是外部与内部之间的索引协议。一个必须知道的顺序约束先nzData后其他组件文档在 Note 一节明确强调请确保nzData先被设置否则其他属性不会生效。因为状态传导是按 key 对已构建的树做标记树都没建好标记自然无处安放。异步接口返回数据后需要重新赋值一次受控属性以触发渲染包括nzExpandAll、nzExpandedKeys、nzCheckedKeys、nzSelectedKeys、nzSearchValue。官方推荐的写法是this.nzExpandAll false; const nodes []; // 数据源 this.nzData [...nodes]; // 设置 nzData 之后若此前已使用过以下属性需要重新赋值以触发渲染 this.nzExpandedKeys [...this.nzExpandedKeys]; this.nzCheckedKeys [...this.nzCheckedKeys]; this.nzSelectedKeys [...this.nzSelectedKeys];四、事件回传受控闭环的另一半受控不能只进不出nz-tree通过输出事件把交互结果回传给业务层。示例中监听了三个最常用的事件全部携带统一的NzFormatEmitEvent结构事件触发时机携带的NzFormatEmitEvent关键字段(nzClick)点击节点标题eventName: click、node、selectedKeys、nodes(nzExpandChange)节点展开/收起eventName: expand、node、keys、nodes(nzCheckboxChange)点击复选框eventName: check、node、checkedKeys、keys、nodesNzFormatEmitEvent完整字段见 tree.component.ts#L249-L263 的输出声明与文档 API 表字段说明类型eventName事件名枚举click / dblclick / contextmenu / check / expand / search / dragstart / dragenter / dragover / dragleave / drop / dragend枚举node当前操作的节点如拖放目标节点NzTreeNodeevent原始MouseEvent或DragEventMouseEvent \| DragEventdragNode?拖拽中的节点拖拽事件时存在NzTreeNodeselectedKeys?选中的节点列表NzTreeNode[]checkedKeys?勾选的节点列表NzTreeNode[]matchedKeys?搜索命中的节点列表NzTreeNode[]keys?与事件相关的全部节点 key拖拽事件除外string[]nodes?与事件相关的全部节点拖拽事件除外NzTreeNode[]事件分发的实现集中在eventTriggerChangedtree.component.ts#L426-L486check事件会先调用setCheckedNodeList更新勾选列表非nzCheckStrictly模式下再执行conduct联动父子节点随后以formatEvent(check, node, event)重新包装事件并对外发出同时还会额外发出nzCheckedKeysChange方便使用者做双向绑定式同步。示例中nzEvent直接console.log(event)正是为了让你在浏览器控制台里直观观察每次点击、展开、勾选后回传的完整结构。五、源码验证测试如何锁定受控行为受控模式的正确性由 components/tree/tree.spec.ts 中的controlled测试套件锁定这些断言既印证了文档描述也可作为你调试受控场景的预期行为清单初始渲染nzExpandedKeys只展开0-0时界面上只显示 3 个节点0-0、0-1、0-2且每个节点都带复选框对应basic initial data/should initialize properly用例。展开联动把defaultExpandedKeys改为[0-1]后可见节点数变为 4getExpandedNodeList()长度为 1且叶节点不会被计入展开列表对应should expand the specified node based on nzExpandedKeys。全展开设置nzExpandAll后可见节点数变为 7展开列表长度为 4对应should expand all nodes while setting nzExpandAll。勾选联动勾选[0-0-0, 0-0-1]后0-0自动变为半选indeterminategetCheckedNodeList()为 2、getHalfCheckedNodeList()为 1对应should render checkbox state of nodes based on nzCheckedKeys。严格模式nzCheckStrictly为true时勾选同样的两个节点不再产生半选节点对应node check should not affect other nodes based on nzCheckStrictly。测试通过querySelectorAll(.ant-tree-checkbox-checked)、.ant-tree-checkbox-indeterminate等 DOM 断言说明受控状态最终是落到节点渲染上的验证了数组 → 节点状态 → 视图这条完整链路。六、受控状态读取组件实例方法除了通过事件回传也可以在组件视图初始化后通过ViewChild(NzTreeComponent)拿到组件实例调用其公开方法读取受控结果方法列表见组件文档 Methods 一节方法返回getTreeNodes()全部节点NzTreeNode[]getTreeNodeByKey(key)指定 key 的节点getCheckedNodeList()勾选节点合并父子getSelectedNodeList()选中节点getHalfCheckedNodeList()半选节点getExpandedNodeList()展开节点getMatchedNodeList()搜索命中的节点nzSearchValue非空时注意文档的提示若在ViewChild上使用这些方法应在ngAfterViewInit中调用因为视图初始化完成后组件实例才就绪。这些方法在NzTreeComponent上通过NzTreeBase暴露内部实现见 nz-tree-base.service.ts#L82-L105 等。七、从受控示例到真实业务场景基于上面的机制受控模式适合以下典型场景权限/角色勾选用nzCheckedKeys回显已有权限勾选变化通过nzCheckedKeysChange或nzCheckboxChange收集并提交目录展开记忆把nzExpandedKeys持久化如 localStorage刷新页面后原样恢复展开层级列表选中回显用nzSelectedKeys恢复上次选中项配合nzClick更新选中态异步加载后的状态恢复数据接口返回后再赋值nzExpandedKeys / nzCheckedKeys / nzSelectedKeys必须遵守先nzData后状态的顺序必要时对状态数组做一次浅拷贝以强制触发变更检测。补充两个官方文档明确给出的实用约定NzTreeNodeOptions支持携带任意自定义属性通过NzTreeNode.origin读取tree.component.ts#L117 处origin定义为用户提供的原始NzTreeNodeOptions设置nzData时优先使用NzTreeNodeOptions[]形式传入NzTreeNode[]将在下个大版本8.x被废弃。八、小结受控操作是nz-tree最重要的能力之一nzCheckedKeys、nzExpandedKeys、nzSelectedKeys三个数组输入负责注入状态nzClick、nzExpandChange、nzCheckboxChange等事件负责回传状态底层由 tree.component.ts 的renderTreeProperties与 nz-tree-base.service.ts 的conduct*系列方法完成数组 ↔ 节点状态 ↔ 视图的闭环。掌握本节示例basic-controlled.ts及其背后的传导逻辑你就能在任何需要记忆或回显树状态的业务中游刃有余。延伸阅读同一 demo 目录下还有 basic.md基础非受控用法、dynamic.md异步加载、search.md搜索高亮与nzSearchValue、draggable.md拖拽等示例受控思路可以与之组合使用完整 API 参考见 components/tree/doc/index.en-US.md。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd 受控 Checkbox 实战用 Angular Signal 实现组件联动ng zorro antd 受控 Checkbox 实战用 Angular Signal 实现组件联动 本文围绕 ng zorro antdAngularUI组件前端ng-zorro-antd 树穿梭框Tree Transfer实战指南用 nz-transfer 自定义渲染 Tree 组件ng zorro antd 树穿梭框Tree Transfer实战指南用 nz transfer 自定义渲染 Tree 组件 导读 本文讲解 ng zorUI组件前端ng-zorro-antd Mention 组件的 disabled 与 readOnly 状态详解ng zorro antd Mention 组件的 disabled 与 readOnly 状态详解 nz mention Mention 提及是 ng zUI组件前端上一篇**探索知识的无限边界将Jupyter的魅力融入Obsidian笔记**下一篇AutoAnimate: 一键赋予网页动态之美创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
