UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载穿梭框Transfer是双栏选择组件中表达力最强的选择控件之一但当默认的纯文本行无法满足需求——例如需要为每一行附加图标、状态标签、头像或富文本摘要时就必须借助nzRender模板实现行级自定义渲染。本文以 ng-zorro-antd 官方 Custom Item 示例为主线结合组件源码custom-item.ts、transfer.component.ts、transfer-list.component.ts讲解nzRender的用法、底层渲染机制与常见扩展场景。读完本文你将能够为 Transfer 的每一行数据渲染任意复杂内容并清楚它与nzRenderList整表自定义的本质区别。一、场景定位何时需要自定义渲染行数据官方文档 custom-item.md 对此场景的定义非常简洁自定义渲染每一个 Transfer Item可用于渲染复杂数据。默认情况下Transfer 每个列表项只渲染TransferItem.title这一行文本见 transfer-list.component.ts 中{{ item.title }}的默认分支。当业务数据包含图标、颜色、多字段信息时单靠title文本无法承载。此时通过nzRender传入一个TemplateRef即可完全接管每一行的内容呈现而复选框选中、搜索过滤、穿梭移动等交互逻辑全部保持不变。二、完整示例图标 标题组合的行渲染官方示例 custom-item.ts 在TransferItem基础上扩展了description与icon两个字段并通过ng-template定义行渲染模板。核心代码如下import { Component } from angular/core; import { NzIconModule } from ng-zorro-antd/icon; import { NzTransferModule, TransferItem } from ng-zorro-antd/transfer; Component({ selector: nz-demo-transfer-custom-item, imports: [NzIconModule, NzTransferModule], template: nz-transfer [nzDataSource]list [nzListStyle]{ width.px: 300, height.px: 300 } [nzRender]render (nzSelectChange)select($event) (nzChange)change($event) ng-template #render let-item nz-icon nzType{{ item.icon }} / {{ item.title }} /ng-template /nz-transfer }) export class NzDemoTransferCustomItemComponent { readonly list this.getData(); getData(): ArrayTransferItem { description: string; icon: string } { const ret: ArrayTransferItem { description: string; icon: string } []; for (let i 0; i 20; i) { ret.push({ key: i.toString(), title: content${i 1}, description: description of content${i 1}, direction: Math.random() * 2 1 ? right : undefined, icon: frown-o }); } return ret; } select(ret: {}): void { console.log(nzSelectChange, ret); } change(ret: {}): void { console.log(nzChange, ret); } }要点拆解nzRender绑定模板引用[nzRender]render把#render模板传给组件模板内通过let-item声明上下文变量item即当前行的TransferItem对象。模板内自由组合内容nz-icon nzType{{ item.icon }} /渲染图标{{ item.title }}渲染标题二者可任意组合成复杂布局。数据源扩展字段ArrayTransferItem { description: string; icon: string }表示在TransferItem基础上交叉扩展自定义字段这是 TypeScript 下最推荐的类型写法。随机方向分布direction: Math.random() * 2 1 ? right : undefined让约一半数据初始出现在右栏方便直接演示穿梭效果。三、底层机制nzRender在组件内部如何被消费理解nzRender的工作原理需要追踪两条调用链。3.1 输入声明与透传在 transfer.component.ts 中Input() nzRender: TemplateRefNzSafeAny | null null;nz-transfer组件接收模板后将其同时透传给左右两个nz-transfer-list子组件nz-transfer-list ... [render]nzRender ... / nz-transfer-list ... [render]nzRender ... /也就是说同一个模板会被左右两栏复用模板内部只需针对item编写逻辑无需区分方向。3.2 模板输出与上下文注入在 transfer-list.component.ts 中渲染发生在列表项li内部if (!render) { {{ item.title }} } else { ng-template [ngTemplateOutlet]render [ngTemplateOutletContext]{ $implicit: item } / }关键点$implicit: item模板上下文把当前项作为隐式变量注入这正是let-item语法能直接取到item的原因单选模式!oneWay下自定义模板被包裹在nz-checkbox标签内勾选交互仍由复选框接管模板只负责展示层单向模式oneWay下模板通过ngTemplateOutlet直接输出右侧行还会附带删除图标按钮见同文件deleteItem逻辑。由此可见nzRender是一种**「行内容插槽」**式的定制数据遍历、选中状态、禁用态样式、搜索过滤、穿梭移动全部由组件内部完成开发者只需定义「这一行长什么样」。四、数据结构基础TransferItem与自定义字段扩展自定义渲染必然涉及数据字段。官方在 interface.ts 中定义的TransferItem为export interface TransferItem { title: string; direction?: TransferDirection; // left | right disabled?: boolean; checked?: boolean; hide?: boolean; [key: string]: NzSafeAny; // 允许任意扩展字段 }注意最后的索引签名[key: string]: NzSafeAny接口本身允许携带任意附加字段因此在getData()中直接写入description、icon并不违反类型约束交叉类型写法只是为了让模板中的字段访问获得完整类型提示。各核心字段含义字段说明默认值title标题用于显示及搜索关键字判断-direction指定数据方向若为right则初始在右栏其他情况为左栏-disabled指定 checkbox 为不可用状态falsechecked指定 checkbox 为选中状态falsehide搜索过滤后是否隐藏组件内部维护falsedirection的左右分流逻辑在 transfer.component.ts 的splitDataSource()中实现遍历nzDataSourcedirection right的进rightDataSource其余进leftDataSource。五、nzRender与nzRenderList两种自定义的分工自定义渲染常与nzRenderList混淆二者的差异从源码输入声明即可看出参数类型作用范围说明[nzRender]TemplateRefvoid单个列表项定制每一行内容交互勾选、穿梭仍由组件负责[nzRenderList]ArrayTemplateRefvoid \| null整个列表完全接管列表渲染需自行处理勾选、全选等交互nzRenderList的模板上下文包含$implicit过滤后的数据、direction、disabled、onItemSelect、onItemSelectAll、stat等定义于 interface.ts 的RenderListContext这是「重写整列」的进阶能力而本文的nzRender是「只换行内容」的轻量定制。二者可同时使用当传入nzRenderList时列表体走renderList分支渲染未传入时才逐行应用nzRender。六、实战扩展把行渲染应用到真实业务基于nzRender的机制可以灵活演进出多种行形态示例数据只需扩展对应字段6.1 带状态标签的行在TransferItem上扩展status字段模板中按状态渲染nz-tag即可把「待审批 / 已通过 / 已驳回」等业务状态直观呈现到行内。6.2 富信息行头像 主标题 描述模板内组合nz-avatar与两行文本布局把description字段展示为次要信息适合用户列表、成员选择等场景——这也是官方advanced示例advanced.ts中{{ item.title }}-{{ item.description }}思路的强化版。6.3 与搜索、全选的配合行模板不影响搜索过滤默认过滤逻辑是item.title.includes(text)见 transfer-list.component.ts 的matchFilter也可通过[nzFilterOption]传入自定义匹配函数如同时匹配title与description。全选、Shift 连选源码中的onTriggerShiftDown与handleSelect等交互同样与自定义模板正交共存。七、API 速查与注意事项nzRender所属的nz-transfer完整 API 见官方文档 index.zh-CN.md 与 index.en-US.md。与本主题强相关的参数汇总如下参数说明类型默认值[nzDataSource]数据源direction: right的项渲染到右栏TransferItem[][][nzRender]每行数据渲染模板TemplateRefvoid-[nzRenderList]自定义渲染整个列表优先级更高ArrayTemplateRefvoid \| null[null, null][nzListStyle]两个穿梭框的自定义样式等同ngStyleobject-[nzFilterOption]自定义搜索过滤函数(inputValue: string, item: TransferItem) boolean-(nzSelectChange)选中项改变时的回调EventEmitterTransferSelectChange-(nzChange)选项在两栏之间转移时的回调EventEmitterTransferChange-实践注意事项模块导入使用nzRender的组件需在imports中同时引入NzTransferModule以及模板内用到的其它模块示例中为NzIconModule。模板上下文模板中只能访问item隐式$implicit及组件类的公开成员如需读取扩展字段应在数据源构造时一并写入。禁用态保持自定义模板不会绕过disabled与item.disabled的禁用逻辑见 transfer-list.component.ts 中ant-transfer-list-content-item-disabled类名绑定行内容的点击/勾选行为仍受组件管控。性能行模板基于fortrack item.key渲染见 transfer-list.component.ts自定义模板应避免在模板内执行高开销计算复杂派生值建议在数据源中预计算。八、小结nzRender是 ng-zorro-antd Transfer 组件提供的行级内容插槽组件负责数据分流、勾选、搜索、穿梭的全部交互开发者只需定义行的视觉呈现。从官方 custom-item 示例 出发配合TransferItem的任意字段扩展能力即可低成本构建图标行、状态行、富信息行等复杂数据源形态若需要更进一步控制整列的勾选与渲染逻辑则可升级到nzRenderList实现完全自定义的列表。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐如何玩转GeoLibre Notebook面板JupyterLite与JupyterLab双引擎完整指南如何玩转GeoLibre Notebook面板JupyterLite与JupyterLab双引擎完整指南 GeoLibre 是一个轻量级、云原生的地理信息系统UI组件前端Webnovel Writer 未来如何跑在 Gemini CLI 和 Codex 上多宿主适配 Spec 完整解读Webnovel Writer 未来如何跑在 Gemini CLI 和 Codex 上多宿主适配 Spec 完整解读 Webnovel Writer 是一套基UI组件前端Element UI 穿梭框el-transfer完整实战指南数据穿梭、搜索过滤与自定义渲染Element UI 穿梭框el transfer完整实战指南数据穿梭、搜索过滤与自定义渲染 穿梭框Transfer是 Element UIVue.前端UI组件设计系统上一篇datasource-proxy常见问题解答从入门到精通的避坑指南下一篇终极指南如何使用GRequests异步请求库实现高效网络爬虫创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
