属性、属性值与事件契约

HTML 属性是字符串序列化协议，JavaScript property 可以是对象、布尔值或函数。组件要定义单向输入和事件输出：外部设置 value，组件通过自定义事件通知用户操作，不要悄悄修改外部对象。

this.dispatchEvent(new CustomEvent('change', {
  detail: { value: nextValue },
  bubbles: true,
  composed: true,
}))

composed 决定事件是否穿过 Shadow DOM；事件 detail 应是稳定、最小的公开契约。表单关联要实现 ElementInternals 或明确说明组件不是原生表单控件，不能只给它一个看似像 input 的样式。

练习

设计一个 <quantity-input> 的 value、min、max 和 change 事件；输入非法值时不发出成功事件，并给出可观察错误。

核心机制与实现

自定义元素把生命周期、Shadow DOM、slot、属性与事件组成公开契约；跨边界时尤其要明确事件是否 composed、表单是否关联。

围绕“属性、属性值与事件契约”先写出输入 → 中间状态 → 可观察结果，再实现最小闭环。不要把事件监听、异步请求、DOM 读取或 store 写入混在一个函数里；每个副作用都要有创建、完成、取消和清理路径。

class QuantityInput extends HTMLElement {
  static formAssociated = true
  static observedAttributes = ['value']
  #internals = this.attachInternals()
  attributeChangedCallback() { this.#internals.setFormValue(this.getAttribute('value') ?? '') }
}
customElements.define('quantity-input', QuantityInput)

逐步运行：先只验证成功路径，再改变一个输入；记录时间顺序、对象身份、错误类型和最终可见状态。若环境不支持某个浏览器 API，要把静态协议验证和真实浏览器验证分开记录。

失败边界与变体

• 输入为空、重复、过期或非法时，不应静默覆盖有效状态。
• 组件卸载、路由离开、标签页关闭或请求取消时，资源必须停止写入。
• 跨文档、Shadow DOM、Worker、SSR 或多标签页会改变可见边界，不能沿用单页面直觉。
• 需要持久化时记录 schema 版本和迁移失败策略；需要全局状态时先证明局部状态不足。

可运行实验与练习

在真实浏览器测试定义前后升级、shadow 事件、焦点、表单提交和元素移除清理；Node 模拟只能验证纯逻辑，不能代替这些平台行为。

练习要求：实现一个最小版本，补一个失败测试，再给出一个替代方案及其适用条件。答案应包括实际输入序列、观察结果、修复原因和未覆盖的浏览器差异。

查看本节答案

下一步

完成练习后打开本章答案，再回到Web Components 课程总览。