Web Components 表单组件怎么接入原生校验：ElementInternals 与错误状态同步

自定义元素一旦要进入真实表单，难点就不只是把输入框包进 Shadow DOM：它还得参与浏览器的必填校验、把值交给 FormData，并让错误状态能被用户和辅助技术读到。用 ElementInternals 连接这几件事，可以保留原生 form 的提交模型，而不用在外层重新复制一套校验器。

把自定义邮箱字段做成 form-associated custom element，再用 setFormValue() 写入表单值、用 setValidity() 同步错误状态，组件就能和原生输入控件走同一条校验链。

先把用户任务限定成一个邮箱字段

假设注册页需要一个带域名限制的邮箱字段。页面希望继续写成

这个边界很重要：组件只负责自己的值和约束，表单仍负责提交、重置和最终的 checkValidity()。如果组件把整张表单的业务规则都塞进来，复用很快会变成耦合。

ElementInternals 连接了哪三件事

组件内部有三个相互独立的动作。setFormValue 把当前值放进表单数据；setValidity 更新约束校验状态；formResetCallback 则在外部表单重置时恢复初始值。它们分别对应数据路径、错误状态和生命周期，不要用一个布尔变量代替。

组件实现：值、校验与提交分开写

下面的实现只做一件事：把 email-field 注册成可参与表单的自定义元素。name 由宿主元素属性提供，内部输入框变化时先更新值，再更新有效性。

class EmailField extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
    this.attachShadow({ mode: "open" }).innerHTML = `
      邮箱
        
      `;
    this.input = this.shadowRoot.querySelector("input");
    this.error = this.shadowRoot.querySelector(".error");
    this.input.addEventListener("input", () => this.syncValidity());
  }

  syncValidity() {
    const value = this.input.value.trim();
    this.internals.setFormValue(value);
    if (!value) {
      this.internals.setValidity(
        { valueMissing: true },
        "请输入邮箱",
        this.input
      );
      this.error.textContent = "请输入邮箱";
      this.error.hidden = false;
      this.input.setAttribute("aria-invalid", "true");
      return;
    }
    if (!this.input.checkValidity()) {
      this.internals.setValidity(
        { typeMismatch: true },
        "邮箱格式不正确",
        this.input
      );
      this.error.textContent = "邮箱格式不正确";
      this.error.hidden = false;
      this.input.setAttribute("aria-invalid", "true");
      return;
    }
    this.internals.setValidity({});
    this.error.hidden = true;
    this.input.removeAttribute("aria-invalid");
  }

  formResetCallback() {
    this.input.value = "";
    this.syncValidity();
  }
}

customElements.define("email-field", EmailField);

页面侧只需要正常提交：

  注册


signup.addEventListener("submit", (event) => {
  event.preventDefault();
  const data = new FormData(signup);
  console.log(data.get("accountEmail"));
});

错误状态要和可见提示同步

setValidity 的第一个参数是约束状态对象，第二个参数是浏览器可以使用的消息，第三个参数用来指向具体控件。清空状态必须传空对象 {}；如果继续保留 valueMissing，字段即使已经输入也会持续无效。

组件自己的提示文本也要同步切换。这里的真实节点是 setValidity、aria-invalid 和 .error：前者进入表单校验链，后两个让用户看到当前状态。

可访问性和交互细节别交给默认行为

错误时把焦点锚点传给 setValidity，浏览器或表单脚本才有机会把用户带回真正的输入控件。可见错误消息要在同一组件内保持稳定位置，避免错误出现时页面突然跳动。若要进一步关联说明，可给内部输入框设置 aria-describedby 指向 .error，并在正常状态隐藏消息而不是删除节点。

组件标签也不能只靠 placeholder。示例中的 label 是 Shadow DOM 内的可见名称；如果宿主页面还要提供外部标题，应明确约定属性和内部 label 的优先级，避免读屏器读到两个相似名称。

性能检查：只在值变化时重算约束

邮箱字段不需要监听整个表单，也不需要每次输入都触发网络请求。把同步动作收口到 input 事件，提交前让原生表单再做一次统一检查即可。复杂格式规则可以先用本地约束挡住，异步校验则另设 pending 状态，不要把异步结果硬塞进同步的 setValidity 判断。

调试时可以用 signup.checkValidity() 检查表单是否被该组件拦住，再用 new FormData(signup).get("accountEmail") 验证值是否真的进入提交数据。一个通过而另一个为空，通常说明校验状态和表单值写入走了不同路径。

浏览器边界与回退策略

项目需要先确认目标浏览器对 form-associated custom elements 和 ElementInternals 的支持情况。不要只判断自定义元素能不能注册；能显示组件，不代表它已经能参与原生表单。

如果目标环境不满足能力要求，最稳的回退是让组件暴露一个普通 light DOM 输入框，或者在页面初始化时选择原生 。回退路径也要复用同一套 name、错误消息和提交字段，避免桌面端与旧环境提交不同的数据。

常见问题

setFormValue 和 setValidity 能互相替代吗？

不能。前者写入表单提交值，后者更新约束校验状态。值为空不一定代表校验状态已经正确，状态有效也不保证提交字段存在。

为什么输入框看起来正常，form 仍然提交不了？

重点检查最后一次 setValidity 是否传入了空对象，以及是否在输入变化后再次调用了同步方法。遗留的 valueMissing 或 typeMismatch 都会让表单继续无效。

组件一定要使用 Shadow DOM 吗？

不一定。Shadow DOM 适合封装内部结构，但 form-associated 能力来自自定义元素与 ElementInternals 的组合。若项目需要统一样式或旧环境兼容，使用 light DOM 也可以。

收尾检查

交付前按四个结果检查：空值能被表单拦截；合法邮箱能出现在 FormData；错误消息和 aria-invalid 同步；重置表单后组件回到初始状态。四项都成立，说明数据、状态、可访问性和生命周期已经接上，而不是只把一个输入框包成了自定义标签。