前端自定义元素怎么接入原生表单校验：ElementInternals、setValidity 与降级边界

自定义元素一旦进入真实表单，难点就不再是把输入框画出来，而是让浏览器知道它有值、能校验、会出现在 FormData 里。ElementInternals 提供的正是这条接入通道：组件声明 formAssociated，通过 attachInternals() 获得内部接口，再用 setFormValue() 和 setValidity() 对接原生表单。

先看清自定义元素缺的那一段能力

普通的 div 可以响应点击，也可以在 Shadow DOM 里放一个输入框，但它本身不会自然出现在表单控件集合中。提交时，外层表单只认识真正的表单元素；如果组件没有主动把值同步出去，后端收到的字段就会悄悄缺失。

表单关联自定义元素解决的是三个边界：组件是否属于某个表单、它提交什么值、它是否通过约束校验。把这三件事拆开，代码会比在 submit 事件里临时查询 Shadow DOM 更稳定。

用 ElementInternals 做一个可提交控件

下面的示例用一个最小的 user-code 控件模拟邀请码输入。组件内部仍然使用原生 input，但对外表现为一个能被 FormData 读取的表单字段。

class UserCode extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
    this.input = document.createElement('input');
    this.input.type = 'text';
    this.input.maxLength = 8;
    this.append(this.input);
    this.input.addEventListener('input', () => this.sync());
  }

  connectedCallback() {
    this.sync();
  }

  sync() {
    const value = this.input.value.trim();
    this.internals.setFormValue(value);
    if (value.length 

外层只需要给组件设置 name，例如 。提交前调用 form.checkValidity()，浏览器就会把组件的有效性纳入判断；表单通过后，new FormData(form).get('inviteCode') 可以拿到同步进去的字符串。

setFormValue 和 setValidity 要各司其职

最容易混淆的是把“值为空”和“控件无效”写成同一个判断。setFormValue(value) 只告诉浏览器要提交什么；它不会自动推导必填、长度或格式规则。setValidity(flags, message, anchor) 才是声明约束失败的地方。

• 有错误标志时，message 应该是非空字符串；传入 anchor 能让浏览器把提示定位到内部输入框。
• 校验通过时传 setValidity({})，不要继续保留上一次的错误状态。
• 不要用 if (!value) 代替全部规则；长度、格式和服务端拒绝是不同的失败原因。

组件模式的反例：把兼容性藏在 Shadow DOM 里

如果目标浏览器没有 attachInternals，组件仍然可能把文字画出来，但表单提交和原生提示会失效。更糟的是，页面代码看起来仍然只使用 ，问题直到联调接口时才暴露。

降级边界应在组件注册前明确。能力足够时注册增强版；否则保留一个同名占位元素，并在旁边使用原生 input 或在模板层直接输出原生控件。不要在不支持时伪造一套“看起来像原生”的错误提示。

const canAssociateForm =
  'ElementInternals' in window &&
  'setFormValue' in ElementInternals.prototype &&
  'attachInternals' in HTMLElement.prototype;

if (canAssociateForm) {
  customElements.define('user-code', UserCode);
} else {
  document.querySelectorAll('user-code').forEach((host) => {
    const input = document.createElement('input');
    input.name = host.getAttribute('name') || 'userCode';
    input.required = true;
    host.replaceWith(input);
  });
}

验收表单行为，而不是只看组件外观

至少覆盖四个检查点：空值时 checkValidity() 返回 false；输入 6 个字符后错误状态清除；FormData 中出现正确的字段名；不支持 ElementInternals 时页面仍提交一个原生输入值。再补一次键盘操作，确认错误定位没有把焦点困在 Shadow DOM 外。

常见问题

只调用 setFormValue，为什么表单仍然能提交空值？

提交值和有效性是两条独立通道。空值仍可被设置为提交值，必须额外调用 setValidity({ valueMissing: true }, '请输入邀请码') 才会阻止提交。

setValidity({}) 为什么要在成功分支再次调用？

有效性状态不会因为输入变化自动清除。成功分支显式传空对象，才能清掉前一次的错误标志和提示。

自定义元素可以完全替代原生 input 吗？

在支持表单关联自定义元素的环境中可以承担字段职责，但降级方案仍应保留原生输入控件，尤其是登录、支付和关键业务表单。

小结

把自定义元素接入原生表单，关键不是增加一个漂亮的组件标签，而是补齐“声明关联、同步值、报告有效性、准备降级”四个契约。ElementInternals 让浏览器接手表单语义，组件只负责维护内部状态；这样写出来的 Web Component 才能和已有表单、校验提示及接口提交真正协作。