ng-zorro-antd CheckList 任务清单组件：从配置到源码的完整指南

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载CheckList 是 ng-zorro-antdAngular UI 组件库中用于梳理强制顺序流程的特色组件。本文以 CheckList 官方文档 为主体结合组件源码、演示用例与多语言文案系统讲解其核心 API、数据模型、进度计算原理、悬浮按钮与面板渲染机制以及隐藏清单的持久化实践帮助你快速将该组件落地到复杂的业务场景中。何时使用如果当前页面的业务逻辑过于复杂且带有较为强制的顺序流控制那么 CheckList 可以帮助你简化流程。典型场景包括多步骤强制流程例如开通服务必须依次完成「填写资料 → 实名认证 → 绑定银行卡 → 激活」前一步未完成时后一步不可操作复杂业务页面的指引在信息密集的管理后台中用清单引导用户按正确顺序完成任务避免遗漏关键步骤操作进度可视化实时展示当前处于第几步、已完成几步、剩余几步让用户对整体进度心中有数。从组件定位看nz-check-list由一个悬浮按钮触发 Popover 面板面板内以步骤列表 进度条的形式呈现任务流未完成的步骤数量会以角标数字展示在悬浮按钮上形成完整的「触发 → 展示 → 交互 → 隐藏」闭环。nz-check-list 组件 API参数说明类型默认值全局配置[nzItems]任务清单元素NzItemProps[][]-[nzVisible]显示任务清单booleanfalse-[nzIndex]当前所属位置number1-[nzProgress]显示任务进度booleantrue-[nzTriggerRender]清单悬浮按钮的渲染模板TemplateRefvoid \| string--[nzTitle]清单面板标题的渲染模板TemplateRefvoid \| string--[nzFooter]清单面板底部的渲染模板TemplateRefvoid \| string--(nzHide)隐藏清单的回调EventEmitterbooleanfalse-(nzHide)的回调值为是否不再显示清单。你可以在回调中存储数据到LocalStorage中以避免再次显示清单。输入与输出在源码中的对应实现上述 API 在 check-list.component.ts 中通过 Angular 17 的新式input()/output()信号 API 声明nzItems inputNzItemProps[]([])默认空数组面板步骤即由此渲染nzVisible input(false)默认false清单初始不展示nzIndex input(1)默认从第 1 步开始作为计算进度百分比的关键输入nzProgress input(true)默认展示进度条三个渲染模板nzTriggerRender、nzTitle、nzFooter均接受TemplateRefvoid | string且默认值为null未提供时组件会回退到内置文案详见下文「内置多语言文案」nzHide是只读的outputboolean()仅在用户确认「不再需要操作清单」时触发。面板的开关状态由linkedSignal(this.nzVisible)check-list.component.ts管理外部传入的nzVisible变化会同步到内部visible信号用户点击开关又会通过visible.set($event)回写实现「受控 内部联动」的双向状态模型。未完成角标的计算原理悬浮按钮上显示的数字角标来自unfinished计算属性check-list.component.tsprotected unfinished computed(() { this.visible(); return this.nzItems().filter(item !item?.checked).length; });它统计所有checked ! true的步骤数量并通过DecimalPipe模板中number: 1.0-0格式化为整数显示同时读取visible()保证面板展开时角标数据仍能随勾选状态实时刷新。角标只在「面板隐藏且有未完成任务」时渲染check-list.component.ts。InterfacesNzItemProps参数说明类型默认值key清单元素的唯一 keystring-description清单元素描述内容string-checked当前清单是否完成boolean-onClick点击步骤触发的方法(item: NzItemProps) void-key为清单元素的唯一标识如果不填写则默认使用description作为 key。接口定义位于 typings.ts与文档略有差异的细节是源码中description为必填字段无?checked、onClick、key为可选字段。key的缺省回退逻辑体现在面板渲染的track表达式中check-list-content.component.tsfor (item of items(); track item.key || item.description) { ... }即未提供key时以description作为循环跟踪标识。实践建议当同一描述可能重复出现时务必为每项指定唯一key否则 Angular 的track机制可能导致列表更新异常。进度条百分比的计算逻辑进度由内部progressPercent计算属性得出check-list-content.component.tsprotected progressPercent computed(() { const index Math.min(Math.max(this.index() - 1, 0), this.items().length); return (index / this.items().length) * 100; });计算规则以nzIndex为基准当前处于第 N 步时已完成 N-1 步进度 (N-1) / 总步数 × 100%使用Math.max(index - 1, 0)防止nzIndex为 0 或负数时出现负进度使用Math.min(..., items.length)防止nzIndex超过总步数时进度溢出 100%当进度为 100% 时面板头部切换为「完成态」展示成功图标与checkListFinish文案「你已成功完成任务清单」并给出「关闭」按钮check-list-content.component.ts。进度条本体复用nz-progress组件nz-progress [nzPercent]progressPercent() | number: 1.0-0外层进度条由nzProgress布尔值控制是否渲染check-list-content.component.ts。悬浮按钮与面板的整体结构nz-check-list的模板check-list.component.ts由三层组成悬浮按钮nz-check-list-button本质是一个带ant-btn ant-btn-primary ant-check-list-button样式的按钮容器check-list-button.component.ts内部通过ng-content投影内容Popover 触发器按钮上挂载nz-popover指令配置nzPopoverTriggerclick、nzPopoverPlacementtopRight、[nzPopoverOverlayClickable]false点击按钮右上弹出面板面板内容nz-check-list-content渲染标题、进度条、步骤列表与底部区域。按钮默认内容为内置图标 文案nz-icon nzTypecheck-circle nzThemeoutline classant-check-list-icon / div classant-check-list-description{{ locale().checkList }}/div当传入nzTriggerRender时通过*nzStringTemplateOutlet输出自定义字符串或模板覆盖默认按钮外观check-list.component.ts。面板内部的分支状态nz-check-list-content内部存在两个视图分支check-list-content.component.ts展开态默认显示标题nzTitle或默认文案checkList、可选进度条、步骤列表、底部nzFooter或默认文案checkListFooter「不需要操作指引」点击底部即收起面板收起确认态当面板收起时出现「你要关闭操作清单吗」确认框包含「确定」「取消」按钮以及「以后不再需要操作清单」复选框——勾选后点确定会通过hide.emit(checked)把true传给外部的nzHide事件check-list-content.component.ts外层组件据此可持久化「不再展示」。步骤行的关键交互check-list-content.component.ts每行由序号/对勾圆形图标 描述文字组成itemHighlightindex() $index 1标记当前所在步骤高亮显示仅当「当前步骤且有onClick」时渲染右侧的箭头图标点击触发item.onClick?.(item)——这正是「强制顺序流控制」的入口只有轮到当前步骤用户才能执行该步并推进nzIndex。内置多语言文案i18n面板中的所有默认文案均来自 i18n 的CheckList语言包。接口定义在 nz-i18n.interface.ts共 8 个字段以简体中文为例zh_CN.ts字段中文默认值checkList任务清单checkListFinish你已成功完成任务清单checkListClose关闭checkListFooter不需要操作指引checkListCheck你要关闭操作清单吗ok确定cancel取消checkListCheckOther以后不再需要操作清单组件通过NzI18nService监听语言变更并同步渲染check-list.component.tslocale toSignalNzCheckListI18nInterface( this.i18n.localeChange.pipe(map(() this.i18n.getLocaleData(CheckList))), { requireSync: true } );仓库已内置 ar_EG、en_US、es_ES、fa_IR、ko_KR 等多语言包切换语言后清单文案会自动跟随无需额外配置。快速上手基础用法示例引入模块后即可使用demo 见 basic.tsimport { Component } from angular/core; import { NzCheckListModule, NzItemProps } from ng-zorro-antd/check-list; Component({ selector: app-check-list-basic, imports: [NzCheckListModule], template: nz-check-list [nzItems]nzItems [nzIndex]index / }) export class CheckListBasicComponent { index 2; readonly nzItems: NzItemProps[] [ { description: step 1, checked: true, onClick: (item: NzItemProps) { this.index; item.checked true; } }, { description: step 2, onClick: (item: NzItemProps) { this.index; item.checked true; } }, { description: step 3, onClick: (item: NzItemProps) { this.index; item.checked true; } }, { description: step 4, onClick: (item: NzItemProps) { this.index; item.checked true; } } ]; }运行效果悬浮按钮右上弹出步骤面板nzIndex2时进度为(2-1)/4 25%第 2 步高亮并显示箭头点击箭头执行onClick同时index与checked同步更新驱动进度条与角标刷新。复杂场景自定义全部渲染入口完整参数配置示例见 custom.ts通过响应式表单动态控制nzVisible、nzProgress、nzIndex并将nzTriggerRender/nzTitle/nzFooter绑定为字符串输入组件内部通过*nzStringTemplateOutlet支持字符串与TemplateRef两种形态nz-check-list [nzItems]nzItems [nzVisible]form.controls.nzVisible.value [nzIndex]form.controls.nzIndex.value || 0 [nzProgress]form.controls.nzProgress.value [nzTriggerRender]form.controls.nzTriggerRender.value [nzTitle]form.controls.nzTitle.value [nzFooter]form.controls.nzFooter.value (nzHide)hideCancel($event) /表单初始值示例form this.fb.group({ nzProgress: true, nzVisible: false, nzIndex: 0, nzTriggerRender: Open List, nzTitle: Customize task lists, nzFooter: Custom Footer Name }); hideCancel(check: boolean): void { console.log(check); this.form.controls.nzVisible.setValue(false); }结合 nzHide 实现「不再提醒」持久化官方文档明确建议(nzHide)的回调值为是否不再显示清单可在回调中将数据写入LocalStorage避免重复展示。推荐实现方式hideCancel(neverShowAgain: boolean): void { if (neverShowAgain) { localStorage.setItem(check-list-dismissed, true); } this.form.controls.nzVisible.setValue(false); }初始化时读取initialVisible localStorage.getItem(check-list-dismissed) ! true;将initialVisible绑定到nzVisible即可实现「用户勾选『以后不再需要操作清单』后下次进入页面不再弹出」。关键注意事项nzIndex默认值为 1基础用法中若不传进度从第 1 步起算custom demo 中将其初始化为 0 并在模板中|| 0兜底进度计算会钳制为 0%Math.max(index - 1, 0)key与descriptionkey缺省时回退为description重复描述务必显式指定唯一keyonClick只在高亮步骤触发非当前步骤即使定义了onClick也不会渲染箭头这是「强制顺序流控制」的核心语义TemplateRefvoid | string输入字符串直接渲染文本模板可通过ng-template自定义富内容如带图标的提示样式类前缀ant-check-list-*如需深度定制可基于 style/index.less 与 style/entry.less 中的类名覆盖样式模块导入使用NzCheckListModulecheck-list.module.ts其内部依赖NzPopoverModule、NzIconModule、NzOutletModule、NzProgressModule、NzCheckboxModule、NzButtonModule等均由组件自身引入业务侧只需导入NzCheckListModule即可。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐NG-ZORRO/ng-zorro-antd 主题定制完全指南NG ZORRO/ng zorro antd 主题定制完全指南 前言 NG ZORROAnt Design of Angular作为企业级UI组件库提供了UI组件前端从源码到部署CrowdStrike CRT内部工作原理与自定义扩展终极指南从源码到部署CrowdStrike CRT内部工作原理与自定义扩展终极指南 CrowdStrike CRTCrowdStrike Reporting Too3分钟快速上手ng-zorro-antd完整安装配置指南3分钟快速上手ng zorro antd完整安装配置指南 ng zorro antd是阿里巴巴基于Ant Design打造的Angular企业级UI组件库为UI组件前端上一篇探索JWT认证新境界Nginx上的nginx-jwt下一篇字符串评分插件 - string_score 使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考