ember-best-practices

Ember.js 最佳实践

Ember.js 应用的全面性能优化与无障碍指南。规则涵盖 10 个类别，并按影响排序，以指导自动化重构和代码生成。

适用场景

在以下情况下参考这些指南：

• 编写新的 Ember 组件或路由
• 使用 WarpDrive 实现数据获取
• 检查代码中的性能问题
• 重构现有 Ember.js 代码
• 优化打包体积或加载时间
• 实现无障碍功能

按优先级排列的规则类别

优先级	类别	影响	前缀
1	路由加载与数据获取	CRITICAL	route-
2	构建与打包优化	CRITICAL	bundle-
3	组件与响应性	HIGH	component-、exports-
4	无障碍最佳实践	HIGH	a11y-
5	服务与状态管理	MEDIUM-HIGH	service-
6	模板优化	MEDIUM	template-、helper-
7	性能优化	MEDIUM	performance-
8	测试最佳实践	MEDIUM	testing-
9	工具与配置	MEDIUM	vscode-
10	高级模式	MEDIUM-HIGH	advanced-

快速参考

1. 路由加载与数据获取（CRITICAL）

• route-parallel-model - 使用 RSVP.hash() 并行加载数据
• route-loading-substates - 实现加载子状态，提升用户体验
• route-lazy-routes - 使用 Embroider 按路由拆分代码
• route-templates - 使用带有就近语法的路由模板
• route-model-caching - 实现智能路由模型缓存

2. 构建与打包优化（CRITICAL）

• bundle-direct-imports - 直接导入，避免导入整个命名空间
• bundle-embroider-static - 启用 Embroider 静态模式以进行摇树优化
• bundle-lazy-dependencies - 延迟加载较大的依赖项

3. 组件与响应性优化（HIGH）

• component-use-glimmer - 优先使用 Glimmer 组件，而非经典组件
• component-cached-getters - 使用 @cached 缓存计算开销大的结果
• component-minimal-tracking - 仅跟踪会影响渲染的属性
• component-no-tracked-writes-in-render - 不要在渲染时更新跟踪状态
• component-tracked-toolbox - 对复杂状态使用跟踪集合
• component-composition-patterns - 使用 yield 块和上下文组件
• component-reactive-chains - 使用依赖 getter 构建响应式链
• component-class-fields - 使用类字段组合组件
• component-standalone-tracked - 将应用状态保存在类中，而非独立的 tracked() 值中
• component-controlled-forms - 实现受控表单模式
• component-on-modifier - 使用 {{on}} 修饰符处理事件
• component-args-validation - 验证组件参数
• component-signatures - 为组件、辅助函数和修饰符编写精确的签名
• component-memory-leaks - 防止组件发生内存泄漏
• component-strict-mode - 使用严格模式和仅模板组件
• component-avoid-classes-in-examples - 避免在组件示例中使用不必要的类
• component-avoid-constructors - 避免在 Glimmer 组件中使用构造函数
• component-avoid-lifecycle-hooks - 避免使用旧版生命周期钩子
• component-file-conventions - 遵循正确的文件命名约定
• exports-named-with-default-fallback - 优先使用命名导出，同时提供默认导出以供模板查找

4. 无障碍最佳实践（HIGH）

• a11y-automated-testing - 使用 ember-a11y-testing 执行自动化检查
• a11y-semantic-html - 使用语义化 HTML 和适当的 ARIA 属性
• a11y-keyboard-navigation - 确保全面支持键盘导航
• a11y-form-labels - 将标签与输入框关联，并播报错误
• a11y-route-announcements - 向屏幕阅读器播报路由切换

5. 服务与状态管理（MEDIUM-HIGH）

• service-cache-responses - 在服务中缓存 API 响应
• service-shared-state - 使用服务管理共享状态
• service-ember-data-optimization - 优化 WarpDrive 查询
• service-owner-linkage - 管理服务 owner 和关联模式
• service-data-requesting - 实现可靠的数据请求模式

6. 模板优化（中）

• template-let-helper - 使用 {{#let}} 避免重复计算
• template-each-key - 使用带 @key 的 {{#each}} 高效更新列表
• template-avoid-computation - 将开销较大的操作移至缓存 getter
• template-helper-imports - 在模板中直接导入 helper
• template-conditional-rendering - 优化条件渲染
• template-fn-helper - 使用 {{fn}} helper 进行部分应用
• template-only-component-functions - 使用仅模板组件
• helper-composition - 组合 helper 以实现可复用逻辑
• helper-builtin-functions - 高效使用内置 helper
• helper-plain-functions - 将 helper 编写为普通函数

7. 性能优化（中）

• performance-on-modifier-vs-handlers - 使用 {{on}} modifier 代替事件处理器属性

8. 测试最佳实践（中）

• testing-modern-patterns - 使用现代测试模式
• testing-qunit-dom-assertions - 使用 qunit-dom 改进测试断言
• testing-test-waiters - 使用 @ember/test-waiters 进行异步测试
• testing-render-patterns - 为组件使用正确的渲染模式
• testing-msw-setup - 使用 MSW 模拟 API 请求
• testing-library-dom-abstraction - 使用 Testing Library 模式

9. 工具与配置（中）

• vscode-setup-recommended - VS Code 扩展和 MCP 服务设置

10. 高级模式（中高）

• advanced-modifiers - 使用 modifier 处理 DOM 副作用
• advanced-modifier-reruns - 将开销较大的 modifier 设置与更新分开
• advanced-helpers - 将可复用逻辑提取到 helper 中
• advanced-tracked-built-ins - 使用来自 @ember/reactive/collections 的响应式集合
• advanced-concurrency - 使用 ember-concurrency 管理任务
• advanced-data-loading-with-ember-concurrency - 使用 ember-concurrency 实现数据加载模式

使用方法

快速参考中的每个条目都链接到 references/ 中对应的规则。编写或审查代码前，请阅读适用于当前任务的规则，而不是一次性加载所有规则。

每个规则文件都包含：

• 简要说明规则的重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 所依据的官方文档链接

使用开源工具提升无障碍性

Ember 通过社区插件提供出色的无障碍支持：

• ember-a11y-testing - 在测试套件中自动进行无障碍测试
• ember-a11y-refocus - 路由播报和焦点管理
• ember-focus-trap - 为模态框和对话框限制焦点
• ember-page-title - 管理无障碍页面标题
• 平台原生验证 - 使用浏览器的 Constraint Validation API 实现无障碍表单验证

这些工具与 Web 平台原生功能相结合，只需极少配置即可提供全面的无障碍支持。

完整编译文档

查看包含所有展开规则的完整指南：AGENTS.md