ember-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ember.js Best Practices

Ember.js 最佳实践

Comprehensive performance optimization and accessibility guide for Ember.js applications. Contains 58 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation.

这是一份针对Ember.js应用的全面性能优化与可访问性指南。包含9个类别共58条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Ember components or routes
Implementing data fetching with WarpDrive
Reviewing code for performance issues
Refactoring existing Ember.js code
Optimizing bundle size or load times
Implementing accessibility features

参考本指南的场景：

编写新的Ember组件或路由
使用WarpDrive实现数据获取
评审代码以排查性能问题
重构现有Ember.js代码
优化包体积或加载时间
实现可访问性功能

Rule Categories by Priority

按优先级划分的规则类别


route-
bundle-
component-
a11y-
service-
template-
performance-
testing-
tooling-
advanced-

Priority	Category	Impact	Prefix
1	Route Loading and Data Fetching	CRITICAL	`route-`
2	Build and Bundle Optimization	CRITICAL	`bundle-`
3	Component and Reactivity	HIGH	`component-`
4	Accessibility Best Practices	HIGH	`a11y-`
5	Service and State Management	MEDIUM-HIGH	`service-`
6	Template Optimization	MEDIUM	`template-`
7	Performance Optimization	MEDIUM	`performance-`
8	Testing Best Practices	MEDIUM	`testing-`
9	Tooling and Configuration	MEDIUM	`tooling-`
10	Advanced Patterns	MEDIUM-HIGH	`advanced-`


route-
bundle-
component-
a11y-
service-
template-
performance-
testing-
tooling-
advanced-

优先级	类别	影响程度	前缀
1	路由加载与数据获取	关键	`route-`
2	构建与包优化	关键	`bundle-`
3	组件与响应式	高	`component-`
4	可访问性最佳实践	高	`a11y-`
5	服务与状态管理	中高	`service-`
6	模板优化	中	`template-`
7	性能优化	中	`performance-`
8	测试最佳实践	中	`testing-`
9	工具与配置	中	`tooling-`
10	高级模式	中高	`advanced-`

Quick Reference

快速参考

1. Route Loading and Data Fetching (CRITICAL)

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

```
route-parallel-model
```
- Use RSVP.hash() for parallel data loading
```
route-loading-substates
```
- Implement loading substates for better UX
```
route-lazy-routes
```
- Use route-based code splitting with Embroider
```
route-templates
```
- Use route templates with co-located syntax
```
route-model-caching
```
- Implement smart route model caching

```
route-parallel-model
```
- 使用RSVP.hash()实现并行数据加载
```
route-loading-substates
```
- 实现加载子状态以提升用户体验
```
route-lazy-routes
```
- 结合Embroider实现基于路由的代码分割
```
route-templates
```
- 使用带有协同定位语法的路由模板
```
route-model-caching
```
- 实现智能路由模型缓存

2. Build and Bundle Optimization (CRITICAL)

2. 构建与包优化（关键）

```
bundle-direct-imports
```
- Import directly, avoid entire namespaces
```
bundle-embroider-static
```
- Enable Embroider static mode for tree-shaking
```
bundle-lazy-dependencies
```
- Lazy load heavy dependencies

```
bundle-direct-imports
```
- 直接导入，避免导入整个命名空间
```
bundle-embroider-static
```
- 启用Embroider静态模式以实现摇树优化
```
bundle-lazy-dependencies
```
- 懒加载大型依赖

3. Component and Reactivity Optimization (HIGH)

3. 组件与响应式优化（高）

```
component-use-glimmer
```
- Use Glimmer components over classic components
```
component-cached-getters
```
- Use @cached for expensive computations
```
component-minimal-tracking
```
- Only track properties that affect rendering
```
component-tracked-toolbox
```
- Use tracked-built-ins for complex state
```
component-composition-patterns
```
- Use yield blocks and contextual components
```
component-reactive-chains
```
- Build reactive chains with dependent getters
```
component-class-fields
```
- Use class fields for component composition
```
component-controlled-forms
```
- Implement controlled form patterns
```
component-on-modifier
```
- Use {{on}} modifier for event handling
```
component-args-validation
```
- Validate component arguments
```
component-memory-leaks
```
- Prevent memory leaks in components
```
component-strict-mode
```
- Use strict mode and template-only components
```
component-avoid-classes-in-examples
```
- Avoid unnecessary classes in component examples
```
component-avoid-constructors
```
- Avoid constructors in Glimmer components
```
component-avoid-lifecycle-hooks
```
- Avoid legacy lifecycle hooks
```
component-file-conventions
```
- Follow proper file naming conventions
```
exports-named-only
```
- Use named exports only

```
component-use-glimmer
```
- 使用Glimmer组件替代传统组件
```
component-cached-getters
```
- 为耗时计算使用@cached装饰器
```
component-minimal-tracking
```
- 仅跟踪影响渲染的属性
```
component-tracked-toolbox
```
- 使用tracked-built-ins处理复杂状态
```
component-composition-patterns
```
- 使用yield块与上下文组件
```
component-reactive-chains
```
- 基于依赖getter构建响应式链
```
component-class-fields
```
- 使用类字段实现组件组合
```
component-controlled-forms
```
- 实现受控表单模式
```
component-on-modifier
```
- 使用{{on}}修饰符处理事件
```
component-args-validation
```
- 验证组件参数
```
component-memory-leaks
```
- 防止组件内存泄漏
```
component-strict-mode
```
- 使用严格模式与仅模板组件
```
component-avoid-classes-in-examples
```
- 组件示例中避免不必要的类
```
component-avoid-constructors
```
- Glimmer组件中避免使用构造函数
```
component-avoid-lifecycle-hooks
```
- 避免使用旧版生命周期钩子
```
component-file-conventions
```
- 遵循正确的文件命名规范
```
exports-named-only
```
- 仅使用命名导出

4. Accessibility Best Practices (HIGH)

4. 可访问性最佳实践（高）

```
a11y-automated-testing
```
- Use ember-a11y-testing for automated checks
```
a11y-semantic-html
```
- Use semantic HTML and proper ARIA attributes
```
a11y-keyboard-navigation
```
- Ensure full keyboard navigation support
```
a11y-form-labels
```
- Associate labels with inputs, announce errors
```
a11y-route-announcements
```
- Announce route transitions to screen readers

```
a11y-automated-testing
```
- 使用ember-a11y-testing进行自动化检查
```
a11y-semantic-html
```
- 使用语义化HTML与正确的ARIA属性
```
a11y-keyboard-navigation
```
- 确保支持完整的键盘导航
```
a11y-form-labels
```
- 关联标签与输入框，提示错误信息
```
a11y-route-announcements
```
- 向屏幕阅读器播报路由切换信息

5. Service and State Management (MEDIUM-HIGH)

5. 服务与状态管理（中高）

```
service-cache-responses
```
- Cache API responses in services
```
service-shared-state
```
- Use services for shared state
```
service-ember-data-optimization
```
- Optimize WarpDrive queries
```
service-owner-linkage
```
- Manage service owner and linkage patterns
```
service-data-requesting
```
- Implement robust data requesting patterns

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

6. Template Optimization (MEDIUM)

6. 模板优化（中）

```
template-let-helper
```
- Use {{#let}} to avoid recomputation
```
template-each-key
```
- Use {{#each}} with @key for efficient list updates
```
template-avoid-computation
```
- Move expensive work to cached getters
```
template-helper-imports
```
- Import helpers directly in templates
```
template-conditional-rendering
```
- Optimize conditional rendering
```
template-fn-helper
```
- Use {{fn}} helper for partial application
```
template-only-component-functions
```
- Use template-only components
```
helper-composition
```
- Compose helpers for reusable logic
```
helper-builtin-functions
```
- Use built-in helpers effectively
```
helper-plain-functions
```
- Write helpers as plain functions

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

7. Performance Optimization (MEDIUM)

7. 性能优化（中）

```
performance-on-modifier-vs-handlers
```
- Use {{on}} modifier instead of event handler properties

```
performance-on-modifier-vs-handlers
```
- 使用{{on}}修饰符替代事件处理属性

8. Testing Best Practices (MEDIUM)

8. 测试最佳实践（中）

```
testing-modern-patterns
```
- Use modern testing patterns
```
testing-qunit-dom-assertions
```
- Use qunit-dom for better test assertions
```
testing-test-waiters
```
- Use @ember/test-waiters for async testing
```
testing-render-patterns
```
- Use correct render patterns for components
```
testing-msw-setup
```
- Mock API requests with MSW
```
testing-library-dom-abstraction
```
- Use Testing Library patterns

```
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. Tooling and Configuration (MEDIUM)

9. 工具与配置（中）

```
vscode-setup-recommended
```
- VS Code extensions and MCP server setup

```
vscode-setup-recommended
```
- VS Code扩展与MCP服务器设置

10. Advanced Patterns (MEDIUM-HIGH)

10. 高级模式（中高）

```
advanced-modifiers
```
- Use modifiers for DOM side effects
```
advanced-helpers
```
- Extract reusable logic into helpers
```
advanced-tracked-built-ins
```
- Use reactive collections from @ember/reactive/collections
```
advanced-concurrency
```
- Use ember-concurrency for task management
```
advanced-data-loading-with-ember-concurrency
```
- Data loading patterns with ember-concurrency

```
advanced-modifiers
```
- 使用修饰符处理DOM副作用
```
advanced-helpers
```
- 将可复用逻辑提取到助手函数中
```
advanced-tracked-built-ins
```
- 使用@ember/reactive/collections中的响应式集合
```
advanced-concurrency
```
- 使用ember-concurrency进行任务管理
```
advanced-data-loading-with-ember-concurrency
```
- 结合ember-concurrency实现数据加载模式

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/route-parallel-model.md
rules/bundle-embroider-static.md
rules/a11y-automated-testing.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件以获取详细说明和代码示例：

rules/route-parallel-model.md
rules/bundle-embroider-static.md
rules/a11y-automated-testing.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外背景信息与参考资料

Accessibility with OSS Tools

借助开源工具实现可访问性

Ember has excellent accessibility support through community addons:

ember-a11y-testing - Automated accessibility testing in your test suite
ember-a11y - Route announcements and focus management
ember-focus-trap - Focus trapping for modals and dialogs
ember-page-title - Accessible page title management
Platform-native validation - Use browser's Constraint Validation API for accessible form validation

These tools, combined with native web platform features, provide comprehensive a11y support with minimal configuration.

Ember通过社区插件提供了出色的可访问性支持：

ember-a11y-testing - 在测试套件中实现自动化可访问性测试
ember-a11y - 路由播报与焦点管理
ember-focus-trap - 为模态框与对话框实现焦点捕获
ember-page-title - 可访问的页面标题管理
平台原生验证 - 使用浏览器的Constraint Validation API实现可访问的表单验证

这些工具结合原生Web平台特性，只需极少配置即可提供全面的可访问性支持。

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南，请查阅：

AGENTS.md