lit-best-practices

Lit Web Components 最佳实践

构建 Lit Web Components 的最佳实践，针对 AI 辅助代码生成和审查进行了优化。

适用场景

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

• 编写新的 Lit Web Components
• 实现响应式属性和状态
• 审查代码中的性能或无障碍问题
• 重构现有 Lit 组件
• 优化渲染和更新周期

规则类别

类别	规则	重点
1. 组件结构	4 条规则	属性、状态、TypeScript
2. 渲染	5 条规则	模板、指令、派生状态
3. 样式	4 条规则	静态样式、主题、CSS parts
4. 事件	3 条规则	自定义事件、命名、清理
5. 生命周期	4 条规则	回调、时机、异步
6. 无障碍	4 条规则	ARIA、焦点、表单、ElementInternals
7. 性能	4 条规则	更新、缓存、延迟加载
8. 组合与数据	3 条规则	控制器、异步任务、上下文
9. 安全	1 条规则	不可信标记

优先级

优先级	描述	操作
CRITICAL	重大正确性或无障碍问题	立即修复
HIGH	对可维护性／性能有显著影响	在当前 PR 中处理
MEDIUM	违反最佳实践	修改相关代码时处理
LOW	风格偏好、微优化	重构时考虑

规则索引

1. 组件结构

• rules/1-1-use-decorators.md - 使用 TypeScript 装饰器（HIGH）
• rules/1-2-separate-state.md - 将公共属性与内部状态分开（HIGH）
• rules/1-3-reflect-sparingly.md - 谨慎反射属性（MEDIUM）
• rules/1-4-default-values.md - 始终提供默认值（HIGH）
• rules/1-5-standard-decorators.md - 标准装饰器需要 accessor（HIGH）

2. 渲染

• rules/2-1-pure-render.md - 保持 render() 纯粹（CRITICAL）
• rules/2-2-use-nothing.md - 空内容使用 nothing（MEDIUM）
• rules/2-3-use-repeat.md - 键控列表使用 repeat()（HIGH）
• rules/2-4-use-cache.md - 条件子树使用 cache()（MEDIUM）
• rules/2-5-derived-state.md - 在 willUpdate() 中计算派生状态（HIGH）
• rules/2-6-class-style-map.md - 使用 classMap 和 styleMap（MEDIUM）

3. 样式

• rules/3-1-static-styles.md - 始终使用静态样式（CRITICAL）
• rules/3-2-host-styling.md - 正确设置宿主元素的样式（HIGH）
• rules/3-3-css-custom-properties.md - 使用 CSS 自定义属性实现主题（MEDIUM）
• rules/3-4-css-parts.md - 使用 CSS parts 进行深层样式设置（MEDIUM）

4. 事件

• rules/4-1-composed-events.md - 分发组合事件（CRITICAL）
• rules/4-2-event-naming.md - 事件命名约定（MEDIUM）
• rules/4-3-cleanup-listeners.md - 清理事件监听器（HIGH）

5. 生命周期

• rules/5-1-super-call-order.md - 正确安排 super() 调用顺序（CRITICAL）
• rules/5-2-first-updated.md - DOM 操作使用 firstUpdated（HIGH）
• rules/5-3-will-update.md - 派生状态使用 willUpdate（HIGH）
• rules/5-4-update-complete.md - 使用 updateComplete 执行异步操作（MEDIUM）

6. 无障碍

• rules/6-1-delegates-focus.md - 交互式组件使用 delegatesFocus（HIGH）
• rules/6-2-aria-attributes.md - 自定义交互式组件使用 ARIA（CRITICAL）
• rules/6-3-form-associated.md - 与表单关联的自定义元素（HIGH）
• rules/6-4-element-internals.md - 通过 ElementInternals 提供语义信息（MEDIUM）

7. 性能

• rules/7-1-has-changed.md - 复杂类型使用自定义 hasChanged（HIGH）
• rules/7-2-batch-updates.md - 批量更新属性（MEDIUM）
• rules/7-3-lazy-loading.md - 延迟加载较重的依赖项（HIGH）
• rules/7-4-memoization.md - 对开销较大的计算进行记忆化（MEDIUM）

8. 组合与数据

• rules/8-1-reactive-controllers.md - 将共享逻辑提取到响应式控制器中（高）
• rules/8-2-async-task.md - 使用 Task 处理异步数据（高）
• rules/8-3-context.md - 使用 @lit/context 代替属性层层传递（中）

9. 安全

• rules/9-1-unsafe-html.md - 切勿将不可信数据传递给 unsafeHTML（严重）

快速参考

必要的导入

// Core
import { LitElement, html, css, nothing } from 'lit';
import { customElement, property, state, query } from 'lit/decorators.js';

// Common Directives
import { repeat } from 'lit/directives/repeat.js';
import { cache } from 'lit/directives/cache.js';
import { classMap } from 'lit/directives/class-map.js';
import { styleMap } from 'lit/directives/style-map.js';
import { until } from 'lit/directives/until.js';

// Official packages
import { Task } from '@lit/task';
import { createContext, provide, consume } from '@lit/context';

组件骨架

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = css`
    :host { display: block; }
    :host([hidden]) { display: none; }
  `;

  @property({ type: String }) value = '';
  @property({ type: Boolean, reflect: true }) disabled = false;
  @state() private _internal = '';

  render() {
    return html`<slot></slot>`;
  }
}

资源

• Lit 文档
• Open Web Components
• Lion Web Components
• web.dev 自定义元素最佳实践