UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文围绕 ng-zorro-antd 的nz-qrcode二维码组件展开全面讲解其 API 参数、渲染原理canvas / svg 两种模式、状态管理与自定义渲染以及二维码容错等级与内容长度限制等关键细节。读完本文你将能够在 Angular 项目中快速集成可定制配色的二维码理解容错等级与扫描可靠性之间的关系并能结合源码掌握组件底层qrcodegen 编码、Path2D 绘制、Icon 挖空等的工作机制。一、何时使用nz-qrcode当业务场景需要将一段文本链接、凭证、字符串等转换生成二维码时即可使用nz-qrcode组件。典型场景包括将页面链接生成二维码供移动端扫码访问将订单号、激活码、票据凭证等文本编码为二维码在票据、卡片、详情页中展示带 Logo 与自定义配色的二维码。该组件自 v15.1.0 引入见 components/qr-code/doc/index.zh-CN.md 文档 front-matter 的tag: 15.1.0属于「数据展示」类型组件。在 v21.0.0 中增强了多项能力nzValue支持传入字符串数组、新增nzType渲染类型与nzBoostLevel自动提升纠错等级。二、快速上手基本用法最简单的用法只需绑定nzValue即可生成二维码对应官方 Demo basic.ts 与 basic.mdnz-qrcode nzValuehttps://ng.ant.design/ /使用前需要在模块中引入NzQRCodeModule定义于 qrcode.module.tsimport { NzQRCodeModule } from ng-zorro-antd/qr-code; NgModule({ imports: [NzQRCodeModule] }) export class AppModule {}nz-qrcode组件选择器由 qrcode.component.ts 声明selector: nz-qrcodeexportAs: nzQRCode默认渲染 160px、黑色前景、白色背景、带边框的 canvas 二维码。下载二维码配合原生 canvas API 可以轻松实现「下载为图片」官方 Demo download.ts 展示了完整做法import { Component, ViewChild, ElementRef } from angular/core; import { NzButtonModule } from ng-zorro-antd/button; import { NzQRCodeModule } from ng-zorro-antd/qr-code; Component({ selector: nz-demo-qr-code-download, imports: [NzButtonModule, NzQRCodeModule], template: div iddownload nz-qrcode nzValuehttps://ng.ant.design/ / a #download/a button nz-button nzTypeprimary (click)downloadImg()Download/button /div }) export class NzDemoQrCodeDownloadComponent { ViewChild(download, { static: false }) download!: ElementRef; downloadImg(): void { const canvas document.getElementById(download)?.querySelectorHTMLCanvasElement(canvas); if (canvas) { this.download.nativeElement.href canvas.toDataURL(image/png); this.download.nativeElement.download ng-zorro-antd; const event new MouseEvent(click); this.download.nativeElement.dispatchEvent(event); } } }三、API 参数全解组件对外暴露的参数、类型、默认值与版本信息如下表源自 index.zh-CN.md并结合 qrcode.component.ts 的 input 声明逐一核对参数说明类型默认值版本[nzValue]扫描后的文本string \| string[]-string[]: 21.0.0[nzType]渲染类型canvas \| svgcanvas21.0.0[nzColor]二维码颜色string#000000[nzBgColor]二维码背景颜色string#FFFFFF[nzSize]二维码大小number160[nzPadding]二维码填充number0[nzIcon]二维码中 icon 地址string-[nzIconSize]二维码中 icon 大小number40[nzBordered]是否有边框booleantrue[nzStatus]二维码状态active \| expired \| loading \| scannedactive[nzStatusRender]自定义状态渲染器TemplateRefvoid \| string-[nzLevel]二维码容错等级L \| M \| Q \| HM[nzBoostLevel]启用后自动提升纠错等级结果可能高于指定等级booleantrue21.0.0(nzRefresh)点击「点击刷新」的回调EventEmitterstring-源码中这些参数均以 Angular signal 形式声明qrcode.component.ts例如readonly nzValue inputstring | string[](); readonly nzType inputsvg | canvas(canvas); readonly nzColor inputstring(DEFAULT_FRONT_COLOR); // #000000 readonly nzBgColor inputstring(DEFAULT_BACKGROUND_COLOR); // #FFFFFF readonly nzSize inputnumber(160); readonly nzIcon inputstring(); readonly nzIconSize inputnumber(40); readonly nzBordered inputboolean(true); readonly nzStatus inputactive | expired | loading | scanned(active); readonly nzLevel inputErrorCorrectionLevel(M); readonly nzStatusRender inputTemplateRefvoid | string | null(null); readonly nzBoostLevel inputboolean(true); readonly nzPadding inputnumber(0); readonly nzRefresh outputstring();3.1 内容nzValue单文本与文本数组默认情况下传入单个字符串即可自 v21.0.0 起支持string[]组件会按数组顺序将每一段分别编码为 QR Segment 再统一生成见 qrcode-data.ts 中memoizedQrcode对Array.isArray(value)的分支处理通过QrSegment.makeSegments逐段构造。3.2 颜色与尺寸nzColor/nzBgColor分别控制前景色与背景色默认#000000/#FFFFFF常量定义于 utils.tsnzSize控制二维码边长px默认160nzPadding控制二维码内部的留白安全区宽度默认0。该值在 utils.ts 中经Math.max(Math.floor(marginSize), 0)归一化处理最终体现在模块矩阵四周的边距上见 qrcode-data.ts 中numCells cells.length mg * 2的计算。3.3 渲染类型nzTypecanvas 与 svg自 v21.0.0 起可选择渲染方式canvas默认由nz-qrcode-canvas子组件通过 2D Context 绘制。canvas 渲染在高分辨率屏幕上会读取window.devicePixelRatio并按该比例放大画布保证 Retina 屏下清晰见 qrcode-canvas.component.tssvg由nz-qrcode-svg子组件输出svg与path元素天然矢量、可无损缩放见 qrcode-svg.component.ts。注意canvas 模式依赖浏览器 DOM组件内部通过isPlatformBrowser判断平台qrcode.component.ts在 SSR服务端渲染环境下 canvas 不可用只有浏览器端才会渲染实际二维码图形。3.4 图标nzIcon与nzIconSize在二维码中央嵌入图片Logo/Iconnz-qrcode nzValuehttps://ng.ant.design/ nzIconhttps://ng.ant.design/assets/img/logo.svg [nzIconSize]48 /nzIcon为图片地址默认无nzIconSize默认40px源码中会将其换算为图像设置qrcode.component.ts嵌入图片时组件会做excavate挖空处理把图标覆盖区域内的码点清空为背景色避免图标遮挡导致无法识别见 utils.ts 的excavateModules与 typing.ts 中对excavate的注释图标区域默认居中支持透明度opacity默认 1与跨域属性crossOrigin默认anonymous详见 typing.ts 的ImageSettings接口。3.5 边框nzBordered默认true组件宿主元素在开启时添加ant-qrcode-borderclassqrcode.component.ts。测试用例中验证了关闭边框后 class 不再出现qrcode.component.spec.ts。四、状态管理与自定义渲染nzStatus控制二维码的四种状态默认active正常展示active正常显示二维码loading显示居中加载指示器nz-spinexpired显示「已过期」提示与「点击刷新」按钮内含 reload 图标点击后触发刷新逻辑scanned显示「已扫描」提示。以上状态文案由 i18n 国际化数据QRCode语言包经NzI18nService注入见 qrcode.component.ts提供文案随语言环境自动切换。对应的组件模板qrcode.component.tsif (!!nzStatusRender()) { div classant-qrcode-mask ng-container *nzStringTemplateOutletnzStatusRender(){{ nzStatusRender() }}/ng-container /div } else if (nzStatus() ! active) { div classant-qrcode-mask switch (nzStatus()) { case (loading) { nz-spin / } case (expired) { div p classant-qrcode-expired{{ locale().expired }}/p button nz-button nzTypelink (click)reloadQRCode() nz-icon nzTypereload nzThemeoutline / span{{ locale().refresh }}/span /button /div } case (scanned) { div p classant-qrcode-expired{{ locale().scanned }}/p /div } } /div }自定义状态渲染nzStatusRender当需要完全自定义状态层的显示内容时传入TemplateRefvoid或字符串即可覆盖上述内置遮罩例如nz-qrcode nzValuehttps://ng.ant.design/ nzStatusloading [nzStatusRender]statusTpl / ng-template #statusTpl加载中请稍候…/ng-template测试用例验证了传入自定义内容后.ant-qrcode-mask内会渲染该内容qrcode.component.spec.ts。刷新回调nzRefresh当用户点击「点击刷新」时即expired状态下组件内部先调用reloadQRCode()重新编码二维码再以refresh字符串触发(nzRefresh)输出事件qrcode.component.tsnz-qrcode nzValue... nzStatusexpired (nzRefresh)onRefresh($event) /五、容错等级Error Correction Level5.1 什么是容错等级容错等级容错率指二维码被部分遮挡后仍能被正常扫描的最大面积比例。等级越高可容忍的缺损越大但二维码的模块数尺寸通常也会相应增大。组件支持四个等级ErrorCorrectionLevel类型定义于 typing.ts等级可纠正错误比例默认L约 7%M约 15%✅默认Q约 25%H约 30%源码中等级通过ERROR_LEVEL_MAP映射到 qrcodegen 的纠错级别utils.tsexport const ERROR_LEVEL_MAP: ERROR_LEVEL_MAPPED_TYPE { L: Ecc.LOW, M: Ecc.MEDIUM, Q: Ecc.QUARTILE, H: Ecc.HIGH } as const;5.2 容错机制的物理含义需要说明的是并不是所有位置都可以缺损二维码**三个角上的定位方框Finder Pattern**直接影响初始定位一旦损坏将无法扫描中间零散的部分是内容编码区域可以容忍缺损容错率越高这部分可被遮挡的面积越大当内容编码携带的信息比较少如链接很短时设置不同的容错等级生成的图片模块数不会发生变化此时提升容错等级是「零成本」的增强扫描可靠性手段。5.3 自动提升纠错等级nzBoostLevel自 v21.0.0 起nzBoostLevel默认true允许编码器在不改变版本的情况下自动将实际纠错级别提升到高于nzLevel指定的级别。其实现位于 qrcode-data.ts 中qrcodegen.QrCode.encodeSegments的最后一个参数boostEcl由 qrcodegen.ts 提供的标准 QR 编码算法处理。实践建议绝大多数场景保持默认true即可让算法尽可能以更高的纠错级别输出从而提升扫码成功率。六、重要注意点6.1 内容长度上限二维码无法识别nzValue有一个保守上限738 或更少的字符。一旦超出该长度二维码模块密度将超出可识别范围导致扫码失败如果启用了更高的容错等级该上限还会进一步降低因为容错需要占用额外的纠错码位。因此在生成前应做好内容长度校验尤其当内容为动态数据如凭证字符串时。6.2 canvas 与 SSRcanvas 模式依赖真实 DOM 与 Canvas 2D API在 SSR/预渲染环境下不会输出图形如需服务端渲染场景下的二维码图片可优先考虑nzTypesvg或在前端交互阶段再渲染。6.3 图标嵌入的影响嵌入nzIcon会挖空中央区域的部分码点相当于人为制造缺损。若nzLevel过低如L级或内容较长中央挖空可能导致解码失败此时应适当提高容错等级如Q/H级。七、源码级实现原理7.1 编码流程组件渲染的数据流如下对应 qrcode-data.tsupdateQRCodeData()汇总nzValue、nzLevel、最小版本号、nzSize、nzBoostLevel、nzPadding与图标设置调用createQRCodeDataqrcode.component.tsmemoizedQrcode将文本或文本数组切分为QrSegment交给 qrcodegen 的QrCode.encodeSegments编码产出模块矩阵 cells二维布尔数组true为黑点getMarginSize计算安全区边距getImageSettings计算图标在矩阵中的坐标、宽高、挖空区域与透明度utils.ts渲染子组件拿到矩阵后绘制。7.2 canvas 绘制细节nz-qrcode-canvas.component.ts 的绘制要点高清适配按window.devicePixelRatio放大画布物理尺寸CSS 尺寸保持nzSize不变setupCanvasL85-L101性能优化优先使用Path2D一次性填充通过generatePath生成路径字符串在不支持 Path2D 的环境如部分旧浏览器回退为逐点fillRectrenderQRCodeL125-L137能力检测见 utils.ts图标异步加载监听img的load/error事件图片加载成功后再绘制并挖空相应码点加载失败则仅绘制纯二维码L139-L192。7.3 svg 绘制细节nz-qrcode-svg.component.ts 通过generatePath将模块矩阵转换为path d命令含背景矩形与前景码点shapeRenderingcrispEdges保证边缘锐利图标以image元素叠加并设置preserveAspectRationone与对应透明度。7.4 测试佐证组件测试 qrcode.component.spec.ts 覆盖了边框开关、尺寸变更nzSize设置后 canvas 宽度为 200px、渲染类型切换svg 输出svg节点、自定义状态渲染、以及expired/loading/scanned三种状态遮罩的结构断言nz-spin与div的切换。八、相关资源索引组件文档components/qr-code/doc/index.zh-CN.md主组件源码qrcode.component.tscanvas 渲染子组件qrcode-canvas.component.tssvg 渲染子组件qrcode-svg.component.ts数据生成与编码入口qrcode-data.ts工具函数与默认值utils.ts类型定义typing.ts测试用例qrcode.component.spec.ts官方 Demo基本用法 basic.ts、容错等级 error-level.ts、颜色 color.ts、背景 background.ts、图标 icon.ts、内边距 padding.ts、状态 status.ts、自定义状态 custom-status.ts、渲染类型 type.ts、下载 download.ts赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd 二维码组件为 QRCode 添加 iconLogo的完整实战指南ng zorro antd 二维码组件为 QRCode 添加 iconLogo的完整实战指南 导读 本篇技术指南围绕 ng zorro antd 的 QRUI组件前端ng-zorro-antd 二维码组件容错等级nzLevel完全指南L/M/Q/H 的选择、默认值与底层编码实现ng zorro antd 二维码组件容错等级nzLevel完全指南L/M/Q/H 的选择、默认值与底层编码实现 本篇技术指南聚焦于 ng zorro aUI组件前端ng-zorro-antd AutoComplete 组件完全指南API 详解、交互原理与源码剖析ng zorro antd AutoComplete 组件完全指南API 详解、交互原理与源码剖析 导读 AutoComplete自动完成是 ng zorUI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
