ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

ng-zorro-antd Steps 步骤条基本用法实战:从 `<nz-steps>` 到状态驱动的步骤导航

ng-zorro-antd Steps 步骤条基本用法实战:从 `<nz-steps>` 到状态驱动的步骤导航 UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本文基于 ng-zorro-antd 仓库中 Steps 组件的官方文档与源码components/steps/doc/index.zh-CN.md、components/steps/steps.component.ts、components/steps/step.component.ts编写。核心围绕官方 基本用法Basic示例展开用最简单的方式搭建一条步骤条并在此基础上完整覆盖nz-steps/nz-step全部 API 参数、状态自动推导机制与源码级实现原理。读完本文你将能够在 Angular 项目中独立实现基本步骤条、竖直步骤条、可点击步骤条、带进度步骤条等常用场景并理解其底层状态流转逻辑。基本用法三步搭起一条步骤条官方 基本用法示例simple.mdzh-CN 标题为基本用法en-US 为 Basic描述的是最简单的步骤条——即nz-steps容器 若干nz-step子项的经典组合。完整示例代码如下见 simple.tsimport { Component } from angular/core; import { NzStepsModule } from ng-zorro-antd/steps; Component({ selector: nz-demo-steps-simple, imports: [NzStepsModule], template: nz-steps [nzCurrent]1 nz-step nzTitleFinished nzDescriptionThis is a description. / nz-step nzTitleIn Progress nzSubtitleLeft 00:00:08 nzDescriptionThis is a description. / nz-step nzTitleWaiting nzDescriptionThis is a description. / /nz-steps }) export class NzDemoStepsSimpleComponent {}需要重点理解三个要点NzStepsModule是唯一需要导入的模块。组件级导入方式下只需在组件的imports数组中加入NzStepsModule即可steps.module.ts 同时导出NzStepsComponent与NzStepComponent且二者均以独立 Component 形式存在支持 standalone 导入。[nzCurrent]1从 0 开始记数表示第 2 个步骤索引为 1是进行中状态索引小于 1 的步骤自动变为finish已完成索引大于 1 的步骤自动变为wait等待。nzTitle、nzSubtitle、nzDescription均可选它们既支持字符串也支持TemplateRef模板详见下文nz-stepAPI。nz-steps容器本身只渲染ng-content /见 steps.component.ts真正的状态计算与外观渲染由父组件向下派发、子组件各自完成——这也是理解 Steps 组件架构的关键父组件通过ContentChildren(NzStepComponent)收集所有子步骤然后在生命周期钩子中统一向子步骤注入方向、大小、状态、索引等上下文详见下文状态自动推导一节。组件的父子分工nz-steps与nz-stepAPI 结构上nz-steps是整体步骤条nz-step是其中每一个步骤官方文档 index.zh-CN.md 明确划分为两个 API 小节nz-steps nz-step nzTitle第一步 / nz-step nzTitle第二步 / nz-step nzTitle第三步 / /nz-steps从源码结构看nz-steps上几乎所有的输入属性nzCurrent、nzStatus、nzSize、nzDirection、nzStartIndex、nzProgressDot最终都会被广播到每个nz-step上steps.component.ts 的updateChildrenSteps()而nz-step则通过自己的 host classant-steps-item-wait / process / finish / error等见 step.component.ts渲染出对应状态的外观。因此凡是在nz-steps上设置的全局属性都不需要在每个nz-step上重复设置而nz-step自身的nzStatus、nzIcon等属性则用于覆盖默认行为。nz-stepsAPI 完整参数说明官方文档提供的nz-steps参数表必须完整继承并结合源码补充默认值与取值细节摘自 index.zh-CN.md 与 steps.component.ts参数说明类型默认值[nzType]步骤条类型有default和navigation两种default \| navigationdefault[nzCurrent]指定当前步骤从 0 开始记数。在子nz-step元素中可以通过nzStatus属性覆盖状态number0[nzDirection]指定步骤条方向支持水平horizontal和竖直verticalvertical \| horizontalhorizontal[nzLabelPlacement]指定标签放置位置默认水平放图标右侧可选vertical放图标下方vertical \| horizontalhorizontal[nzProgressDot]点状步骤条可设置为一个TemplateRef自定义圆点boolean \| TemplateRef{ $implicit: TemplateRefvoid, status: string, index: number }false[nzSize]指定大小支持普通default和迷你smallsmall \| defaultdefault[nzStatus]指定当前步骤的状态可选waitprocessfinisherrorwait \| process \| finish \| errorprocess[nzStartIndex]指定起始位置的序号number0(nzIndexChange)点击单个步骤时触发的事件number-源码层面的补充说明可在 steps.component.ts 中核对nzCurrent、nzDirection、nzType、nzSize、nzStartIndex、nzStatus均为Input()属性其中nzDirection的类型别名NzDirectionType与状态类型NzStatusTypewait | process | finish | error在该文件中直接定义导出。nzProgressDot的 setter 行为值得注意当传入的值是TemplateRef实例时组件不仅开启点状模式showProcessDot true还会将其保存为customProcessDotTemplate用于自定义圆点渲染传入布尔值时则通过toBoolean归一化。(nzIndexChange)与可点击的关系从源码看step.clickable由this.nzIndexChange.observers.length 0决定——只要订阅了nzIndexChange步骤条就自动变为可点击状态见 steps.component.ts。这与官方 可点击示例 的描述订阅(nzIndexChange)后Steps 变为可点击状态完全一致。nz-stepAPI 完整参数说明单个步骤的官方参数表摘自 index.zh-CN.md参数说明类型默认值[nzDescription]步骤的详情描述可选string \| TemplateRefvoid-[nzIcon]步骤图标的类型可选string \| string[] \| Setstring \| { [klass: string]: any; }|TemplateRefvoid-[nzStatus]指定状态。当不配置该属性时会使用nz-steps的nzCurrent来自动指定状态。可选waitprocessfinisherrorwait \| process \| finish \| errorwait[nzTitle]标题string \| TemplateRefvoid-[nzSubtitle]子标题string \| TemplateRefvoid-[nzDisabled]禁用点击booleanfalse[nzPercentage]当前状态为process的步骤所显示的进度条进度只对基本类型的nz-steps生效number-源码细节补充见 step.component.tsnzTitle/nzSubtitle/nzDescription均支持string | TemplateRefvoid在模板中通过*nzStringTemplateOutlet统一渲染——传入字符串直接显示传入模板则渲染模板内容这让详情描述携带富内容成为可能。nzStatus一旦被显式赋值isCustomStatus会被置为true此后父组件通过currentIndex计算出的自动状态将不再覆盖它见 step.component.ts。nzDisabled使用booleanAttribute变换即nzDisabled出现即视为true无需写[nzDisabled]true。nzIcon的类型是NgClassType字符串、数组、Set 或对象映射并兼容TemplateRef源码还保留了对旧版anticon前缀图标的兼容判断oldAPIIcon。状态自动推导nzCurrent如何驱动wait / process / finish / error官方文档提到在子nz-step元素中可以通过nzStatus属性覆盖状态、当不配置该属性时会使用nz-steps的nzCurrent来自动指定状态。其底层实现非常清晰父组件收集与派发ngAfterContentInit中订阅steps.changes并在ngOnChanges/ngOnInit中调用updateChildrenSteps()为每个子步骤设置index index nzStartIndex、currentIndex nzCurrent、outStatus nzStatus等steps.component.ts。子组件按索引计算状态nz-step的currentIndexsetter 中实现核心逻辑step.component.tsset currentIndex(current: number) { this._currentIndex current; if (!this.isCustomStatus) { this._status current this.index ? finish : current this.index ? this.outStatus || : wait; } }即索引小于nzCurrent的步骤 →finish等于 →outStatus默认process大于 →wait。这与基本用法示例中Finished / In Progress / Waiting三个步骤的呈现顺序完全吻合。外观由 host class 驱动nz-step根据nzStatus绑定ant-steps-item-wait / process / finish / error等 class并根据nzStatus分支渲染图标——finish渲染check图标、error渲染close图标、process/wait渲染序号index 1step.component.ts。从基本用法出发的四个高频变体在掌握基本用法后官方 demo 提供了可直接复用的进阶场景均在components/steps/demo/目录下1. 竖直方向步骤条vertical.md / vertical.ts只需在nz-steps上加nzDirectionvertical其余写法与基本用法一致nz-steps [nzCurrent]1 nzDirectionvertical nz-step nzTitleFinished nzDescriptionThis is a description. / nz-step nzTitleIn Progress nzDescriptionThis is a description. / nz-step nzTitleWaiting nzDescriptionThis is a description. / /nz-steps2. 起始序号start-index.md / start-index.ts通过nzStartIndex改变步骤条的起始序号典型场景是步骤从 3 开始计数。官方文档特别提醒nzCurrent也应加上对应的偏移——例如nzStartIndex3时nzCurrent同时设置为3才能让第 1 个步骤处于进行中状态nz-steps [nzCurrent]current [nzStartIndex]3 nzSizesmall nz-step nzTitleFinished / nz-step nzTitleIn Progress / nz-step nzTitleWaiting / /nz-steps注意nzStartIndex会通过updateChildrenSteps()以step.index index nzStartIndex的方式注入每个子步骤因此序号和状态判定都随之偏移。3. 可点击步骤条clickable.md / clickable.ts订阅(nzIndexChange)后 Steps 自动变为可点击状态事件回调拿到点击的步骤索引配合nzDisabled可禁用单个步骤的点击nz-steps [nzCurrent]index() (nzIndexChange)onIndexChange($event) nz-step nzTitleFinished [nzDisabled]disable nzDescriptionThis is a description. / nz-step nzTitleIn Progress nzDescriptionThis is a description. / nz-step nzTitleWaiting nzDescriptionThis is a description. / /nz-steps其点击事件的底层链路为nz-step在ngOnInit中通过fromEventOutsideAngular监听容器 click 事件过滤掉不可点击clickable为假、点击当前步骤或nzDisabled的情况后向clickOutsideAngular$发射索引step.component.ts父组件merge所有子步骤的事件流在nzIndexChange有订阅者时于 Angular zone 内重新触发nzIndexChange.emit(index)steps.component.ts。4. 带进度的步骤progress.md / progress.ts异步执行的任务可在处于process状态的步骤上显示圆形进度条给对应nz-step设置[nzPercentage]0–100 之间的数值仅对基本类型default的nz-steps生效。示例中用signal RxJStimer模拟了异步步骤的进度累加nz-steps [nzCurrent]current() for (step of steps(); track step.id) { nz-step [nzTitle]step.title [nzDescription]step.description [nzPercentage]step.async ? step.percentage : null / } /nz-steps从源码看showProgress的判定条件是nzPercentage ! null、未设置自定义图标nzIcon、nzStatus process且百分比在 0–100 区间内step.component.ts此时内部通过NzProgressModule的nz-progress圆形组件渲染进度小尺寸下圆环宽度为 32默认 40。样式体系与进一步探索Steps 组件的样式基于 Ant Design 的ant-steps命名空间包括ant-steps-horizontal、ant-steps-vertical、ant-steps-dot、ant-steps-small、ant-steps-navigation、ant-steps-rtl等修饰 class均由nz-steps的 host 绑定根据输入属性动态切换steps.component.ts具体样式定义位于 components/steps/style/ 目录。若需继续深入可在仓库中查看steps.spec.ts 中的测试用例覆盖状态推导、点击事件、进度展示等行为、public-api.ts 与 index.ts 了解模块导出结构以及组件其余 demo如 icon、error、nav、progress-dot、customized-progress-dot、small-size、step-next、vertical-small覆盖的更多使用场景。要点回顾基本用法只需nz-steps [nzCurrent]n包裹若干nz-step nzTitle...nzCurrent从 0 计数并自动推导各步骤的finish / process / wait状态nz-step的nzStatus可覆盖自动状态订阅(nzIndexChange)即可获得可点击能力nzDirection、nzStartIndex、nzPercentage分别解决方向、起始序号与异步进度展示问题——掌握这些即可覆盖多数业务中的步骤导航需求。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Agent-S3首个超越人类性能的计算机使用智能体终极指南Agent S3首个超越人类性能的计算机使用智能体终极指南 你是否曾经想过如果AI能够像人类一样操作电脑会是怎样的场景想象一下你只需要用自然语言说帮UI组件前端ng-zorro-antd Steps 组件竖直方向步骤条从 nzDirection 到样式与状态管理的完整指南ng zorro antd Steps 组件竖直方向步骤条从 nzDirection 到样式与状态管理的完整指南 本文以 ng zorro antd基于 AUI组件前端antd Steps 步骤切换实战基于 current 状态与按钮驱动多步流程antd Steps 步骤切换实战基于 current 状态与按钮驱动多步流程 导读 在 Ant Design 的 Steps 步骤条组件中步骤切换s前端UI组件设计系统上一篇3D特征匹配终极指南RANSAC与LMEDS算法深度对比下一篇终极指南Dio请求取消令牌的7个高级取消策略创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表