企业官网建设流程全解析

• UI组件
• 前端

CheckList 是 ng-zorro-antd（Angular UI 组件库）中用于梳理强制顺序流程的特色组件。本文以 CheckList 官方文档 为主体，结合组件源码、演示用例与多语言文案，系统讲解其核心 API、数据模型、进度计算原理、悬浮按钮与面板渲染机制，以及隐藏清单的持久化实践，帮助你快速将该组件落地到复杂的业务场景中。

何时使用

如果当前页面的业务逻辑过于复杂，且带有较为强制的顺序流控制，那么 CheckList 可以帮助你简化流程。典型场景包括：

• 多步骤强制流程：例如开通服务必须依次完成「填写资料 → 实名认证 → 绑定银行卡 → 激活」，前一步未完成时后一步不可操作；
• 复杂业务页面的指引：在信息密集的管理后台中，用清单引导用户按正确顺序完成任务，避免遗漏关键步骤；
• 操作进度可视化：实时展示当前处于第几步、已完成几步、剩余几步，让用户对整体进度心中有数。

从组件定位看，nz-check-list由一个悬浮按钮触发 Popover 面板，面板内以步骤列表 + 进度条的形式呈现任务流，未完成的步骤数量会以角标数字展示在悬浮按钮上，形成完整的「触发 → 展示 → 交互 → 隐藏」闭环。

nz-check-list 组件 API

(nzHide)的回调值为是否不再显示清单。你可以在回调中存储数据到LocalStorage中，以避免再次显示清单。

输入与输出在源码中的对应实现

上述 API 在 check-list.component.ts 中通过 Angular 17+ 的新式input()/output()信号 API 声明：

• nzItems = input<NzItemProps[]>([])：默认空数组，面板步骤即由此渲染；
• nzVisible = input(false)：默认false，清单初始不展示；
• nzIndex = input(1)：默认从第 1 步开始，作为计算进度百分比的关键输入；
• nzProgress = input(true)：默认展示进度条；
• 三个渲染模板nzTriggerRender、nzTitle、nzFooter均接受TemplateRef<void> | string，且默认值为null，未提供时组件会回退到内置文案（详见下文「内置多语言文案」）；
• nzHide是只读的output<boolean>()，仅在用户确认「不再需要操作清单」时触发。

面板的开关状态由linkedSignal(this.nzVisible)（check-list.component.ts）管理：外部传入的nzVisible变化会同步到内部visible信号，用户点击开关又会通过visible.set($event)回写，实现「受控 + 内部联动」的双向状态模型。

未完成角标的计算原理

悬浮按钮上显示的数字角标来自unfinished计算属性（check-list.component.ts）：

protected unfinished = computed(() => { this.visible(); return this.nzItems().filter(item => !item?.checked).length; });

它统计所有checked !== true的步骤数量，并通过DecimalPipe（模板中number: '1.0-0'）格式化为整数显示；同时读取visible()保证面板展开时角标数据仍能随勾选状态实时刷新。角标只在「面板隐藏且有未完成任务」时渲染（check-list.component.ts）。

Interfaces：NzItemProps

key为清单元素的唯一标识，如果不填写，则默认使用description作为 key。

接口定义位于 typings.ts，与文档略有差异的细节是：源码中description为必填字段（无?），checked、onClick、key为可选字段。key的缺省回退逻辑体现在面板渲染的track表达式中（check-list-content.component.ts）：

@for (item of items(); track item.key || item.description) { ... }

即未提供key时以description作为循环跟踪标识。实践建议：当同一描述可能重复出现时，务必为每项指定唯一key，否则 Angular 的track机制可能导致列表更新异常。

进度条百分比的计算逻辑

进度由内部progressPercent计算属性得出（check-list-content.component.ts）：

protected 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）由三层组成：

1. 悬浮按钮（nz-check-list-button）：本质是一个带ant-btn ant-btn-primary ant-check-list-button样式的按钮容器（check-list-button.component.ts），内部通过ng-content投影内容；
2. Popover 触发器：按钮上挂载nz-popover指令，配置nzPopoverTrigger="click"、nzPopoverPlacement="topRight"、[nzPopoverOverlayClickable]="false"，点击按钮右上弹出面板；
3. 面板内容（nz-check-list-content）：渲染标题、进度条、步骤列表与底部区域。

按钮默认内容为内置图标 + 文案：

<nz-icon nzType="check-circle" nzTheme="outline" class="ant-check-list-icon" /> <div class="ant-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）：

• 每行由序号/对勾圆形图标 + 描述文字组成；
• itemHighlight（index() === $index + 1）标记当前所在步骤，高亮显示；
• 仅当「当前步骤且有onClick」时，渲染右侧的箭头图标，点击触发item.onClick?.(item)——这正是「强制顺序流控制」的入口：只有轮到当前步骤，用户才能执行该步并推进nzIndex。

内置多语言文案（i18n）

面板中的所有默认文案均来自 i18n 的CheckList语言包。接口定义在 nz-i18n.interface.ts，共 8 个字段；以简体中文为例（zh_CN.ts）：

组件通过NzI18nService监听语言变更并同步渲染（check-list.component.ts）：

locale = toSignal<NzCheckListI18nInterface>( this.i18n.localeChange.pipe(map(() => this.i18n.getLocaleData('CheckList'))), { requireSync: true } );

仓库已内置 ar_EG、en_US、es_ES、fa_IR、ko_KR 等多语言包，切换语言后清单文案会自动跟随，无需额外配置。

快速上手：基础用法示例

引入模块后即可使用（demo 见 basic.ts）：

import { 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; } } ]; }

运行效果：悬浮按钮右上弹出步骤面板，nzIndex=2时进度为(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，即可实现「用户勾选『以后不再需要操作清单』后，下次进入页面不再弹出」。

关键注意事项

1. nzIndex默认值为 1：基础用法中若不传，进度从第 1 步起算；custom demo 中将其初始化为 0 并在模板中|| 0兜底，进度计算会钳制为 0%（Math.max(index - 1, 0)）；
2. key与description：key缺省时回退为description，重复描述务必显式指定唯一key；
3. onClick只在高亮步骤触发：非当前步骤即使定义了onClick也不会渲染箭头，这是「强制顺序流控制」的核心语义；
4. TemplateRef<void> | string输入：字符串直接渲染文本，模板可通过ng-template自定义富内容（如带图标的提示）；
5. 样式类前缀ant-check-list-*：如需深度定制，可基于 style/index.less 与 style/entry.less 中的类名覆盖样式；
6. 模块导入：使用NzCheckListModule（check-list.module.ts），其内部依赖NzPopoverModule、NzIconModule、NzOutletModule、NzProgressModule、NzCheckboxModule、NzButtonModule等，均由组件自身引入，业务侧只需导入NzCheckListModule即可。

• UI组件
• 前端