ElementInternals 怎样让自定义元素参与表单校验

自定义元素能显示自己的输入框，并不代表它已经进入原生表单流程。要让浏览器在提交时收集它的值、识别 required，还需要把组件声明成表单关联元素，再通过 ElementInternals 同步值和校验状态。本文用一个联系人字段说明最小实现。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals

核心分工是：setFormValue() 负责“提交什么”，setValidity() 负责“是否允许提交”。少了前者，值不会进入 FormData；少了后者，组件只是在界面上显示错误，表单本身仍可能认为它有效。

先让自定义元素进入表单体系

第一步是在类上声明 static formAssociated = true，然后在构造函数中调用 attachInternals()。这两个条件缺一不可：前者告诉浏览器该元素可以参与表单，后者拿到与表单、校验和可访问性相关的内部接口。

用 setFormValue 同步真正提交的值

组件内部可以使用 Shadow DOM 的原生 input，但这个 input 并不是表单的直接子控件。每次用户输入后，应把规范化后的字符串交给 setFormValue()。自定义元素本身还要带有 name 属性，浏览器才有字段名可写入 FormData。

class ContactField extends HTMLElement {
  // 声明这个自定义元素可以成为表单关联控件。
  static formAssociated = true;

  #internals;
  #input;

  constructor() {
    super();
    // 取得浏览器提供的提交与校验接口。
    this.#internals = this.attachInternals();
    const shadow = this.attachShadow({ mode: "open" });
    this.#input = document.createElement("input");
    this.#input.type = "text";
    this.#input.addEventListener("input", () => this.#sync());
    shadow.append(this.#input);
  }

  connectedCallback() {
    // 组件接入文档后先同步一次初始值和 required 状态。
    this.#sync();
  }

  #sync() {
    const value = this.#input.value.trim();
    // name 属性决定该值在 FormData 中对应的字段名。
    this.#internals.setFormValue(value);

    if (this.hasAttribute("required") && value === "") {
      // 非空错误必须同时给出有效的校验标志和提示文本。
      this.#internals.setValidity(
        { valueMissing: true },
        "请输入联系人"
      );
      return;
    }

    // 空对象表示清除旧错误，让控件恢复有效状态。
    this.#internals.setValidity({});
  }
}

customElements.define("contact-field", ContactField);

使用时可以把它放进普通表单：

  
  保存

提交值和校验状态要分开管理

setFormValue(value) 和 setValidity(flags, message) 是两条不同通道。前者影响提交数据，后者影响 checkValidity()、reportValidity() 以及表单的 invalid 处理。联系人为空时，示例设置 valueMissing 和提示语；用户补上内容后，必须用 setValidity({}) 清除旧状态。

如果只改变 Shadow DOM 中 input 的样式，表单不会自动知道它的值；如果只在组件里显示红色边框而不调用 setValidity()，提交按钮也不会得到原生校验阻止。把两条通道分别更新，问题就容易定位。

几个容易忽略的边界

• 先声明再调用。attachInternals()、setFormValue() 和 setValidity() 都依赖 formAssociated 能力，不能把普通自定义元素直接当成原生 input。
• 校验失败要有消息。当 flags 中有一项为 true 时，应同时传入非空提示；通过校验时传空对象即可。
• 空值处理要一致。示例在提交前调用 trim()，因此只输入空格也会被当成空值；如果业务允许空格，应改成自己的规范化规则。
• 不要把 name 写进内部 input 作为替代。真正负责提交的是自定义元素的 ElementInternals，内部 input 的 name 可能造成字段重复。

小结与相关问题

实现可校验的自定义表单控件，可以按“声明关联能力、取得 internals、同步 FormData 值、设置 ValidityState”四个动作组织。这样组件保留自己的 UI，又能和浏览器表单的提交、校验流程协作。

为什么自定义元素显示错误但表单仍能提交？

通常是只改了 Shadow DOM 的样式或文字，没有调用 setValidity()。界面提示和浏览器约束状态是两套机制。

什么时候需要 setFormValue 的第二个参数？

当组件需要同时提交一个用户可见值和一个内部状态值时，可以传入第二个 state 参数；单值控件使用一个字符串就足够。