Angular UI Patterns 实战指南用 Signals 与 defer 构建健壮的加载、错误与数据展示状态【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本文以 Agentic Awesome Skills 仓库中angular-ui-patterns技能的详细指南为主体系统讲解现代 Angular 应用中 UI 状态设计的高阶模式加载状态Loading、错误处理Error Handling、渐进式披露Progressive Disclosure基于defer、空状态Empty State、按钮与表单的异步状态以及配套的可访问性与检查清单。读完本文你将掌握一套面向 AI Agent 与 LLM 友好、可直接落地的 Angular UI 状态机设计方法并能在 angular-ui-patterns 详细指南 与同仓库的 angular-state-management 、angular 技能之间形成完整的实战闭环。一、技能定位与核心原则angular-ui-patterns是 Agentic Awesome Skills 中面向构建 UI 组件、处理异步数据、管理组件状态场景的专项技能。根据其 SKILL.md 的定义该技能在风险等级为 safe、来源为 self2026-02-27 收录专门解决以下问题Loading States骨架屏Skeleton与加载动画Spinner的选择决策树Error Handling错误边界层级与恢复策略Progressive Disclosure用defer实现按需渲染Data Display空、加载、错误三种数据展示状态Form Patterns表单提交状态与校验反馈Dialog/Modal Patterns对话框生命周期管理该技能的全部操作细节沉淀在 references/detailed-guide.md 中它是从SKILL.md抽取的聚焦加载参考文件——根技能定义激活条件、示例、安全约束与局限性本文即围绕这份指南展开。五条核心原则永不展示陈旧 UINever show stale UI——只有真正在加载时才显示加载状态始终暴露错误Always surface errors——用户必须知道何时失败乐观更新Optimistic updates——让界面感觉瞬时响应渐进式披露Progressive disclosure——用defer让内容按需出现优雅降级Graceful degradation——部分数据总比没有数据好。这五条原则与同仓库 angular 技能 中 Signals 取代 zone.js 变更检测、angular-state-management 的 Signal 状态分层一脉相承状态管理负责把数据与异步动作收敛到 StoreUI Patterns 负责把 Store 暴露出的loading/error/items三态正确地渲染出来。二、加载状态模式Loading State Patterns2.1 黄金法则仅在没有任何可展示数据时才显示加载指示器。这是全文最重要的一条规则。它直接对应本文开头的 Never show stale UI 原则也解释了为什么简单的if (loading())写法是反模式。Component({ template: if (error()) { app-error-state [error]error() (retry)load() / } else if (loading() !items().length) { app-skeleton-list / } else if (!items().length) { app-empty-state messageNo items found / } else { app-item-list [items]items() / } , }) export class ItemListComponent { private store inject(ItemStore); items this.store.items; loading this.store.loading; error this.store.error; }注意这里的判断顺序本身就是一张决策树有错误吗 → 是显示带重试按钮的错误状态 → 否继续 正在加载 且 没有数据 → 是显示加载指示器spinner/skeleton → 否继续 有数据吗 → 有且包含条目展示数据 → 有但为空显示空状态 → 没有显示加载兜底从源码结构看loading()与!items().length的组合是整个模式的精髓当用户重新拉取数据refetch时页面上已有旧数据此时闪烁加载动画会造成内容跳变而保持旧数据可见、静默更新才是更好的体验。组件通过inject(ItemStore)直接消费 angular-state-management 中定义的 Signal Storeitems、loading、error三个只读信号模板中的if/else if链式判断取代了旧版*ngIf的嵌套地狱。2.2 Skeleton 与 Spinner 的选择使用 Skeleton骨架屏当……使用 Spinner加载动画当……内容形状已知内容形状未知列表/卡片布局模态框中的操作页面首次加载按钮提交内容占位符行内操作Skeleton本质是内容的形状预览它告诉用户马上会有一张卡片/一行列表出现在这里因此适合列表页、卡片流、详情页首载Spinner只表达正在忙不透露内容形状因此适合按钮内、模态框动作、任何无法预测结果形态的行内操作。三、控制流模式Control Flow Patterns3.1if/else条件渲染Angular 内置控制流if支持局部变量别名as user配合 Signal 输入非常干净if (user(); as user) { spanWelcome, {{ user.name }}/span } else if (loading()) { app-spinner sizesmall / } else { a routerLink/loginSign In/a }if (user(); as user)在条件为真时将 Signal 解包值绑定到局部变量user避免在模板里重复调用user()登录态、加载态、未登录态三态一目了然。这与 angular 技能 中 Signal 输入input()/output()的写法完全兼容属于新一代模板语法v17 起内置无需导入CommonModule。3.2for搭配trackfor (item of items(); track item.id) { app-item-card [item]item (delete)remove(item.id) / } empty { app-empty-state iconinbox messageNo items yet actionLabelCreate Item (action)create() / }要点track item.id提供稳定的身份标识让 Angular 最小化 DOM 复用与重建等价于旧trackBy但语法更简洁且必填用于正确复用视图与状态empty块是列表的空状态兜底——每个列表/集合必须有空状态是本文的另一条硬性要求且它天然和for配对无需额外的*ngIf。3.3defer渐进式加载!-- 关键内容立即加载 -- app-header / app-hero-section / !-- 非关键内容延迟加载 -- defer (on viewport) { app-comments [postId]postId() / } placeholder { div classh-32 bg-gray-100 animate-pulse/div } loading (minimum 200ms) { app-spinner / } error { app-error-state messageFailed to load comments / }defer的四个子块构成了完整的渐进式披露生命周期主块延迟加载的内容本例中评论组件在进入视口时才渲染placeholder延迟期间立即显示的占位内容可配合 Tailwind 的animate-pulse做骨架效果loading (minimum 200ms)懒加载真正执行时的加载态minimum 200ms避免一闪而过的加载闪烁error懒加载失败时的错误兜底。在 angular 技能 中还能看到defer (hydrate on viewport)/(hydrate on interaction)等增量水合Incremental Hydration, v20写法以及on idle/on timer(ms)等触发条件表——SSR 场景下defer从懒渲染进一步升级为懒水合同一套心智模型可平滑迁移。四、错误处理模式Error Handling Patterns4.1 错误处理层级1. 行内错误字段级 → 表单校验错误 2. Toast 通知 → 可恢复错误用户可重试 3. 错误横幅Banner → 页面级错误数据仍部分可用 4. 全屏错误页 → 不可恢复需要用户操作选择策略的核心是错误的严重程度与可恢复性字段校验错误就地展示可重试的操作失败用 Toast 提示并允许重试页面级数据加载失败用横幅保留已展示部分完全不可恢复如整页崩溃才用全屏错误页。4.2 绝不静默吞掉错误CRITICAL永远不要把错误静默吞掉。// 正确 - 错误始终暴露给用户 Component({...}) export class CreateItemComponent { private store inject(ItemStore); private toast inject(ToastService); async create(data: CreateItemDto) { try { await this.store.create(data); this.toast.success(Item created successfully); this.router.navigate([/items]); } catch (error) { console.error(createItem failed:, error); this.toast.error(Failed to create item. Please try again.); } } } // 错误 - 错误被静默捕获 async create(data: CreateItemDto) { try { await this.store.create(data); } catch (error) { console.error(error); // 用户什么都看不到 } }注意正确版本的三层动作成功给正反馈toast.success→ 失败既打日志console.error 保留调试线索又给用户可读提示toast.error。这与 angular-state-management 中UserStore.loadUser的try/catch/finally结构一致catch 里把_error信号置为可读文案finally里复位_loading——Store 负责记录错误UI 负责把错误渲染出来。4.3 可复用错误状态组件Component({ selector: app-error-state, standalone: true, imports: [NgOptimizedImage], template: div classerror-state img ngSrc/assets/error-icon.svg width64 height64 alt / h3{{ title() }}/h3 p{{ message() }}/p if (retry.observed) { button (click)retry.emit() classbtn-primaryTry Again/button } /div , }) export class ErrorStateComponent { title input(Something went wrong); message input(An unexpected error occurred); retry outputvoid(); }两个值得学习的细节retry输出配合if (retry.observed)判断父组件是否绑定了(retry)事件——只有提供了重试回调时才渲染Try Again按钮组件可同时用于可重试与仅展示两种场景图片使用NgOptimizedImage的ngSrc并显式声明width/height避免布局偏移CLS与 angular 技能 中priority、loadinglazy、placeholderblur的图像优化建议相呼应。五、按钮状态模式Button State Patterns5.1 按钮加载态button (click)handleSubmit() [disabled]isSubmitting() || !form.valid classbtn-primary if (isSubmitting()) { app-spinner sizesmall classmr-2 / Saving... } else { Save Changes } /button按钮的禁用条件往往是复合的isSubmitting() || !form.valid——既防重复提交又阻止无效表单提交。5.2 异步操作期间必须禁用触发器CRITICAL异步操作期间始终禁用触发控件。// 正确 - 加载期间按钮被禁用 Component({ template: button [disabled]saving() (click)save() if (saving()) { app-spinner sizesm / Saving... } else { Save } /button }) export class SaveButtonComponent { saving signal(false); async save() { this.saving.set(true); try { await this.service.save(); } finally { this.saving.set(false); } } } // 错误 - 用户可以点击多次 button (click)save() {{ saving() ? Saving... : Save }} /button错误的版本只切换了文案而没有真正disabled用户依然可以连续点击触发多次请求。正确版本的关键是try/finally无论成功失败都必须在finally中复位saving信号否则按钮会永久卡在禁用态。六、空状态Empty States6.1 空状态是硬性要求每个列表/集合都必须有空状态且优先用for的empty块实现for (item of items(); track item.id) { app-item-card [item]item / } empty { app-empty-state iconfolder-open titleNo items yet descriptionCreate your first item to get started actionLabelCreate Item (action)openCreateDialog() / }6.2 上下文感知的空状态组件Component({ selector: app-empty-state, template: div classempty-state span classicon [class]icon()/span h3{{ title() }}/h3 p{{ description() }}/p if (actionLabel()) { button (click)action.emit() classbtn-primary {{ actionLabel() }} /button } /div , }) export class EmptyStateComponent { icon input(inbox); title input.requiredstring(); description input(); actionLabel inputstring | null(null); action outputvoid(); }组件设计要点title必填、icon/description有默认值、actionLabel默认为null——只有当父组件传入操作文案时才渲染 CTA 按钮与错误状态组件的retry.observed思路一致这让空状态既能纯展示也能引导下一步动作。七、表单模式Form Patterns表单是加载、校验、提交三态的集大成者。完整示例Component({ template: form [formGroup]form (ngSubmit)onSubmit() div classform-field label fornameName/label input idname formControlNamename [class.error]isFieldInvalid(name) / if (isFieldInvalid(name)) { span classerror-text {{ getFieldError(name) }} /span } /div div classform-field label foremailEmail/label input idemail typeemail formControlNameemail / if (isFieldInvalid(email)) { span classerror-text {{ getFieldError(email) }} /span } /div button typesubmit [disabled]form.invalid || submitting() if (submitting()) { app-spinner sizesm / Submitting... } else { Submit } /button /form , }) export class UserFormComponent { private fb inject(FormBuilder); submitting signal(false); form this.fb.group({ name: [, [Validators.required, Validators.minLength(2)]], email: [, [Validators.required, Validators.email]], }); isFieldInvalid(field: string): boolean { const control this.form.get(field); return control ? control.invalid control.touched : false; } getFieldError(field: string): string { const control this.form.get(field); if (control?.hasError(required)) return This field is required; if (control?.hasError(email)) return Invalid email format; if (control?.hasError(minlength)) return Too short; return ; } async onSubmit() { if (this.form.invalid) return; this.submitting.set(true); try { await this.service.submit(this.form.value); this.toast.success(Submitted successfully); } catch { this.toast.error(Submission failed); } finally { this.submitting.set(false); } } }要点拆解校验时机isFieldInvalid用control.invalid control.touched即只有用户触碰过才报错避免表单一渲染就满屏红字错误信息集中化getFieldError按hasError优先级返回人类可读文案模板只做展示提交保护form.invalid || submitting()双重门禁配合finally复位submitting行内错误 Toast 组合字段级错误行内展示对应错误层级第 1 层提交失败用 Toast第 2 层。八、对话框/模态框模式Dialog/Modal Patterns确认对话框是异步 UI 的经典场景——确认 → 等待关闭 → 决定是否继续执行需要把 Dialog 的关闭事件转成 Promise// dialog.service.ts Injectable({ providedIn: root }) export class DialogService { private dialog inject(Dialog); // CDK Dialog 或自定义 async confirm(options: { title: string; message: string; confirmText?: string; cancelText?: string; }): Promiseboolean { const dialogRef this.dialog.open(ConfirmDialogComponent, { data: options, }); return await firstValueFrom(dialogRef.closed) ?? false; } } // 使用 async deleteItem(item: Item) { const confirmed await this.dialog.confirm({ title: Delete Item, message: Are you sure you want to delete ${item.name}?, confirmText: Delete, }); if (confirmed) { await this.store.delete(item.id); } }firstValueFrom(dialogRef.closed)把对话框的关闭流收敛为一个Promiseboolean业务代码可以用await顺序化确认-删除流程彻底避免回调地狱。这里的store.delete同样可以配合乐观更新与失败回滚——angular-state-management 中的deleteProduct展示了先本地移除、失败后恢复 previousData的完整回滚范式。九、反模式速查Anti-Patterns主题错误写法正确写法加载状态if (loading())无脑显示 Spinnerrefetch 时闪烁if (loading() !items().length)只有无数据才显示错误处理catch (e) { console.log(e); }用户毫无感知console.errortoast.error错误必须可视化按钮状态只切文案不disabled可重复提交[disabled]loading() 加载中显示 Spinner这三组反模式本质是同一件事的三个侧面用户永远不该面对闪烁的旧数据、无声的失败、可重复触发的操作。十、UI 状态检查清单完成任何 UI 组件前逐项自检UI 状态错误状态已处理并向用户展示仅在无数据时显示加载状态集合类组件提供空状态empty块异步操作期间按钮已禁用按钮在适当时机显示加载指示器数据与变更所有异步操作都有错误处理所有用户操作都有反馈toast/视觉提示乐观更新失败时回滚可访问性A11y加载状态对屏幕阅读器播报错误信息与对应表单字段关联状态变更后的焦点管理十一、与其他技能的协同该技能在仓库内明确声明与三个技能联动angular-state-management用 Signal Storesignal()computed()或 NgRx SignalStore承载状态——UI 层只消费loading/error/items等只读信号angular应用现代模式Signals、Standalone、Zoneless、defer本指南中的input()/output()/inject()全部属于该技能覆盖的现代 APItesting-patterns对全部 UI 状态error/loading/empty/data编写测试。三者构成完整链路状态管理负责数据怎么来UI Patterns 负责状态怎么画测试负责画得对不对。调用时建议先阅读 angular-ui-patterns 的 SKILL.md 确认激活条件与安全边界再按需加载本指南对应章节端到端任务则应完整通读。结语从黄金法则无数据才显示加载到defer的渐进式披露从错误层级到乐观更新回滚angular-ui-patterns提供的不是零散技巧而是一套可判定的状态机设计规范。它要求开发者始终回答三个问题用户当前看到的是不是最新数据失败是否可见操作是否可重复触发当你把这三问内化为习惯再配合 Signal Store 的统一三态输出就能构建出既符合现代 AngularSignals 内置控制流 Standalone又对 AI Agent 友好的健壮界面——这也是本技能作为 Agentic Awesome Skills 中可被 LLM 直接检索、执行的高密度参考文档的价值所在。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
