UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文以 ng-zorro-antd基于 Ant Design 的企业级 Angular UI 组件库仓库中的 AI 编码规范文档.gemini/GEMINI.md为骨架系统梳理一套面向大规模 Web 应用开发的 TypeScript 与 Angular 现代工程规范涵盖严格类型、signal 状态管理、Standalone 组件、原生控制流、无障碍A11y与服务注入等核心主题。读完本文你将掌握可直接落地到 Angular 项目的编码约定并能在本仓库最新源码如 alert-marquee.component.ts、affix.component.ts中找到每一条规范的真实实现佐证从而理解规范如何约束真实代码。一、TypeScript 最佳实践用类型系统兜底规范要求 AI 编码助手以及任何开发者在 TypeScript 层面建立三层防线实践说明落地要点严格类型检查开启strict编译选项让null/undefined、隐式any等隐患在编译期暴露优先类型推断类型显而易见的场景不写冗余注解保持代码简洁减少不必要的类型噪音杜绝any不确定时用unknown兜底any会关闭类型检查unknown强制先收窄再使用从 package.json 可见ng-zorro-antd 当前基于 TypeScript ~6.0.3 构建组件库自身即依赖严格的编译配置来保证数十个组件的类型安全。在组件 API 层仓库进一步用input.requiredT()、booleanAttribute、numberAttribute等信号转换函数来收紧输入类型例如 alert-marquee.component.tsreadonly nzPauseOnHover input(false, { transform: booleanAttribute }); readonly nzSpeed input(50, { transform: numberAttribute });booleanAttribute/numberAttribute让属性绑定支持true/false或50这类字符串值同时保持类型面仍然是boolean/number——这正是严格类型 良好 DX兼得的典型写法。二、Angular 最佳实践面向 Angular v20 的现代化写法2.1 始终使用 Standalone而非 NgModule规范明确优先使用 Standalone 组件并且不要在装饰器里显式写standalone: true——在 Angular v20 中这已是默认值。从 package.json 可以看到本仓库使用angular/core ^22.1.0完全处于该约定生效的版本区间。仓库证据也印证了这一约束在 components 全量源码中搜索standalone: true唯一的命中是 select-search.component.ts 中模板里的[ngModelOptions]{ standalone: true }表单控件的 NgModelOptions 配置而非任何组件装饰器属性。也就是说整个组件库的新代码都没有在Component装饰器中手写该标志。2.2 用 signal 管理状态、用computed()派生状态状态管理是 Angular 现代化开发的核心变化。规范要求使用 signal 承载状态使用computed()表达派生状态而非手动同步赋值保持状态变换纯粹、可预测禁止调用 signal 的mutate一律使用set/update。alert-marquee.component.ts 是教科书式范例内部宽度用signal(0)保存动画时长与宿主 class 均由computed()从输入信号派生而来private readonly trackWidth signal(0); protected readonly animationDuration computed(() { const width this.trackWidth(); const speed this.nzSpeed(); return width 0 speed 0 ? width / speed : 20; }); protected readonly class computed(() ({ ant-alert-marquee: true, ant-alert-marquee-pause-on-hover: this.nzPauseOnHover() }));随后模板通过[style.animation-duration.s]animationDuration()、[class]class()消费这些派生信号没有任何手动订阅与同步逻辑既避免ExpressionChangedAfterItHasBeenCheckedError也让状态流向单向可追踪。2.3 特性路由懒加载对于按路由组织的功能模块规范要求实现懒加载。Angular Router 的标准做法是使用loadComponent/loadChildren按需加载独立路由组件库场景下文档站点的各组件示例页同样遵循按路由拆分、按需进入的加载模型。2.4 禁止HostBinding/HostListener改用host对象规范明确禁止在装饰器上使用HostBinding/HostListener宿主绑定必须放进Component/Directive装饰器的host对象中。全库搜索也印证唯一出现HostListener字样之处仅是 cascader.component.ts 中的一段源码注释。真实实现全部走host对象例如 alert-marquee.component.tshost: { [class]: class() }host对象的优势是声明集中、便于静态分析与 tree-shaking同时天然适配 signal 的computed()返回值是 v20 时代推荐的宿主绑定姿势。2.5 静态图片一律使用NgOptimizedImage规范要求所有静态图片使用NgOptimizedImage指令并特别注明该指令对内联 base64 图片无效。原因是NgOptimizedImage依赖浏览器原生loadinglazy、srcset尺寸协商与预连接fetchpriority等机制工作而 base64 data URI 不具备真实的可协商资源 URL也就无法受益于这些优化。实践建议静态图片统一放入资源目录通过ngSrc绑定真实 URL提供width/height或fill以避免布局偏移CLS避免将小图转成 base64 内联以免既丢失优化又膨胀包体。三、无障碍A11y硬性要求规范给出两条不可妥协的验收线必须通过所有 AXE 检查必须满足 WCAG AA 最低要求包括焦点管理focus management、色彩对比度color contrast与 ARIA 属性。这两条标准在本仓库中既是约束也是测试目标。以 alert-marquee.component.ts 为例跑马灯的第二条轨道被显式标记aria-hiddentrue——因为它是为动画无缝衔接而复制的视觉副本重复内容必须对辅助技术隐藏对应的单测 alert-marquee.spec.ts 直接断言了这一点it(should set aria-hiddentrue on the second track for accessibility, () { ... expect(tracks[1].getAttribute(aria-hidden)).toBe(true); });组件库的每个组件都配有针对性的 a11y 单测把通过 AXE、满足 WCAG AA从口号变成可持续执行的 CI 守门员。开发者在接入这些组件时也应保持键盘可达Tab 顺序、:focus-visible样式与足够对比度的主题色。四、组件设计规范小而专、信号化、声明式4.1 职责单一、保持小巧组件应足够小并聚焦单一职责。ng-zorro-antd 的实践是将复杂业务拆成多个细粒度组件/指令协同工作例如 alert 组件内部将跑马灯动画独立为NzAlertMarqueeComponent便于单独测试与复用。4.2 用input()/output()取代装饰器规范要求使用input()/output()函数而非Input()/Output()装饰器。仓库中新组件已全面采用这一写法除了上一节的input(默认值, { transform })还有必填输入的写法例如 check-list-content.component.tslocale input.requiredNzCheckListI18nInterface(); index input(0); progress input(true);信号化输入天然支持computed()派生与细粒度响应式更新输出则用output()声明事件。与此同时全库搜索显示Input(装饰器仍大量存在于既有组件中——这说明新代码遵循信号 API存量代码渐进迁移这是大型组件库务实的演进策略。4.3 小组件优先内联模板外部模板用相对路径模板简短的小组件优先使用template内联减少文件碎片、让组件自包含alert-marquee.component.ts 即为内联模板实例必须使用外部模板/样式时路径相对于组件 TS 文件书写避免因目录层级不同导致资源解析失败。4.4 用 Reactive Forms 取代模板驱动表单复杂表单一律优先 Reactive Forms模型驱动、可预测、易于单测与动态校验。模板驱动表单仅适合极简交互场景。4.5 不用ngClass/ngStyle改用 class / style 绑定ngClass/ngStyle会引入额外的指令层与对象合并开销且不利于静态分析。规范要求类切换用[class]、[class.foo]cond等 class 绑定样式切换用[style.prop]、[style.prop.px]等 style 绑定。仓库中的典型例子正是 alert 跑马灯宿主类名由computed()输出对象经[class]绑定动画时长经[style.animation-duration.s]绑定全程零ngClass/ngStyle。五、状态管理规范signal 的纪律状态管理小节与组件规范相互呼应可归纳为四条纪律纪律说明组件局部状态用 signal替代组件字段 ChangeDetectorRef手动刷新派生状态用computed()由源信号自动推导杜绝手工同步 bug状态变换保持纯粹、可预测变换函数不应有副作用便于测试与推理不调mutate用set/updatemutate就地修改绕过变更通知的语义约束破坏可预测性set用于整体替换update用于基于旧值计算新值二者都保证新引用 显式通知的语义与 Zone/信号变更检测模型完全兼容。六、模板规范保持简单、用原生控制流6.1 模板保持简单逻辑放组件类模板只做声明式渲染复杂逻辑格式化、过滤、分支计算一律前移到组件类常用computed()或普通方法保持模板可读、可测。6.2 用原生控制流替代结构型指令规范强制使用内置控制流语法if/for/switch取代*ngIf/*ngFor/*ngSwitch。原生控制流更轻量无包装元素、支持for的track性能优化与empty空态分支是 v17 的推荐方向。6.3 用 async pipe 消费 Observableasync管道负责订阅、变更检测与自动退订模板中不出现手动subscribeif (vm$ | async; as vm) { span{{ vm.title }}/span }6.4 不依赖全局对象模板中不写箭头函数不要假设全局对象如new Date()在模板中可用模板表达式应只依赖组件上下文日期等值应在组件类中注入或计算模板中不要写箭头函数Angular 模板表达式不支持箭头函数语法事件处理器应指向组件类方法。七、服务设计规范单职责 root 单例 函数式注入服务设计的三条原则同样能在仓库源码中找到大量实例单一职责一个服务只做一件事。例如 affix.component.ts 所在模块依赖的滚动、Zone、渲染、ResizeObserver 等服务各司其职providedIn: root声明单例让服务在应用根注入器上注册天然单例、tree-shakable无需在模块中手动 provider用inject()而非构造器注入函数式注入配合DestroyRef等新 API让依赖声明更扁平、更易在测试中覆盖。affix.component.ts 展示了连续inject()的典型形态private readonly scrollSrv inject(NzScrollService); private readonly ngZone inject(NgZone); private readonly platform inject(Platform); private readonly renderer inject(Renderer2); ... private readonly destroyRef inject(DestroyRef);组件/服务统一通过inject()获取依赖配合DestroyRef做资源清理如 alert-marquee.component.ts 中的inject(DestroyRef)既直观又与现代生命周期钩子体系一致。八、把这些规范接入你的开发流程上述规范本质上是仓库为 AI 编码助手Gemini配置的编码人格其载体正是本仓库根目录的 .gemini/GEMINI.md。与之一同落地的还有 .gemini/settings.json它通过 MCPModel Context Protocol把angular-cli与eslint两套工具暴露给 AI 助手{ mcpServers: { angular-cli: { command: npx, args: [-y, angular/cli, mcp] }, eslint: { command: npx, args: [eslint/mcplatest], env: {} } } }这意味着 AI 在生成代码时可以直接调用 Angular CLI 脚手架与 ESLint 做实时校验而.gemini/GEMINI.md则作为最上层的行为准则约束代码风格。对普通开发者而言这套组合完全可以移植到自己的项目中在项目根目录建立规范文档TypeScript / Angular / A11y / 状态 / 模板 / 服务六个板块作为团队与 AI 的共同契约通过 MCP 接入 CLI 与 lint 工具让规范可执行、可验证在 CI 中叠加 AXE / WCAG 检查与信号相关 lint 规则形成自动化守门员。九、实践自检清单写完全文将规范浓缩为可直接复用的 checklist开启 strict 模式代码零any不确定处用unknown新组件使用 Standalone不写standalone: true特性路由懒加载组件状态用signal派生状态用computed()不用mutate输入输出用input()/output()含input.required与 transform宿主绑定写在host对象禁用HostBinding/HostListener静态图片用NgOptimizedImage拒绝内联 base64模板只用if/for/switchObservable 走 async pipe无全局对象、无箭头函数不用ngClass/ngStyle改用 class / style 绑定服务单职责 providedIn: root一律inject()注入交付前通过 AXE 检查与 WCAG AA 验收这套规范并非空谈——在本仓库的 components/alert/alert-marquee.component.ts、components/check-list/check-list-content.component.ts 与 components/affix/affix.component.ts 等新代码中每一条都有真实、可追踪的实现样本可作为团队评审与 AI 编码质量验收的参照基线。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Kretes路由系统详解轻松实现复杂页面导航与API接口Kretes路由系统详解轻松实现复杂页面导航与API接口 Kretes是一个为TypeScript和Deno打造的编程环境其强大的路由系统让开发者能够轻松实Angular 项目 AI 编码规范指南guidelines.md深度解读从 Persona 到 Signal 最佳实践Angular 项目 AI 编码规范指南guidelines.md深度解读从 Persona 到 Signal 最佳实践 本指南围绕 Angular 仓库前端Web框架终极指南如何高效使用AI速查表提升机器学习编码规范终极指南如何高效使用AI速查表提升机器学习编码规范 cheatsheets ai 是一个专门为深度学习、机器学习和数据科学研究者设计的速查表集合项目它整理了人工智能机器学习深度学习数据科学文档上一篇Paper_Reading_List中的 salient object detection 论文全解析从经典模型到前沿技术下一篇Material Components Web List 组件完全指南安装、键盘导航、选择状态与无障碍实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考