本文详解如何为表单关联自定义元素（Form-Associated Custom Element, FACE）实现符合标准的约束验证（Constraint Validation API），重点解决“An invalid form control is not focusable”报错，确保 checkValidity()、reportValidity() 和表单提交时行为一致、可聚焦、可提示。

本文详解如何为表单关联自定义元素（form-associated custom element, face）实现符合标准的约束验证（constraint validation api），重点解决“an invalid form control is not focusable”报错，确保 `checkvalidity()`、`reportvalidity()` 和表单提交时行为一致、可聚焦、可提示。

在构建表单关联自定义元素（FACE）时，仅设置 static formAssociated = true 和调用 this.attachInternals() 是不够的。浏览器在执行表单验证（如 form.reportValidity() 或原生提交）时，会尝试将焦点移至首个无效控件——若该控件无法被聚焦（例如未显式指定验证锚点），就会抛出经典错误：

An invalid form control with name='foobar' is not focusable.

根本原因在于：浏览器需要明确知道「当验证失败时，应将焦点移至哪个内部 DOM 元素」。而 internals.setValidity() 的第三个参数（anchor）正是为此设计的验证锚点（validity anchor），它必须是一个可聚焦的、已挂载的 元素（或其它可聚焦元素），且该元素需满足 delegatesFocus: true 的 shadow root 配置。

以下是经过验证的、生产就绪的修复方案，涵盖核心要点与最佳实践：

✅ 正确设置验证锚点（关键！）

在调用 this.internals.setValidity() 时，必须传入具体的、可聚焦的子 元素作为第三个参数。例如：

// ✅ 正确：指定首个失效的 input 作为 anchor
const firstInvalidInput = this.shadowRoot.querySelector('input:not(:valid)');
if (firstInvalidInput) {
  this.internals.setValidity(
    { customError: true },
    '数据不合法，请检查姓名长度',
    firstInvalidInput // ← 必须是真实存在的、可聚焦的 HTMLElement
  );
} else {
  this.internals.setValidity({}); // 清除验证状态
}

⚠️ 注意：anchor 参数不可为 null、undefined 或未挂载节点；否则 Chrome/Safari 仍会报错。

✅ 完整可运行示例（精简优化版）

// name.js
class MyName extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
    const shadow = this.attachShadow({ mode: 'open', delegatesFocus: true });

    // 基础模板（移除冗余 hidden 类与延迟逻辑，避免验证时机错乱）
    shadow.innerHTML = `
      <style>
        :host { display: block; }
        input:invalid { border-color: #d32f2f; outline: 2px solid #f44336; }
        .error { color: #d32f2f; font-size: 0.875rem; margin-top: 4px; }
      </style>
      <div>
        <label>姓氏：<input type="text" name="lastname" minlength="2" required /></label>
        <label>名字：<input type="text" name="firstname" minlength="2" required /></label>
        <p class="error"></p>
      </div>
    `;
  }

  connectedCallback() {
    // 绑定输入事件并同步验证状态
    this.shadowRoot.querySelectorAll('input').forEach(input => {
      input.addEventListener('input', () => this.#updateValidity());
      input.addEventListener('blur', () => this.#updateValidity());
    });

    // 初始化值（若存在 value 属性）
    if (this.hasAttribute('value')) {
      try {
        const data = new FormData();
        const parsed = JSON.parse(this.getAttribute('value'));
        Object.entries(parsed).forEach(([k, v]) => data.set(k, v));
        this.value = data;
      } catch {}
    }
  }

  #updateValidity() {
    const inputs = this.shadowRoot.querySelectorAll('input');
    const invalidInput = [...inputs].find(el => !el.checkValidity());

    if (invalidInput) {
      const msg = invalidInput.validationMessage || '请输入有效内容';
      this.internals.setValidity(
        { customError: true },
        msg,
        invalidInput // ← 验证锚点：必须传入具体 input 元素
      );
      this.shadowRoot.querySelector('.error').textContent = msg;
    } else {
      this.internals.setValidity({});
      this.shadowRoot.querySelector('.error').textContent = '';
    }
  }

  // ✅ 暴露标准 API（供表单调用）
  get validity() { return this.internals.validity; }
  get validationMessage() { return this.internals.validationMessage; }
  get willValidate() { return this.internals.willValidate; }
  checkValidity() { return this.internals.checkValidity(); }
  reportValidity() { return this.internals.reportValidity(); }

  // ✅ 实现表单集成生命周期
  formResetCallback() {
    this.shadowRoot.querySelectorAll('input').forEach(i => i.value = '');
    this.#updateValidity();
  }

  formDisabledCallback(disabled) {
    this.shadowRoot.querySelectorAll('input').forEach(i => i.disabled = disabled);
  }

  // ✅ value getter/setter（返回 FormData 更语义化）
  get value() {
    const fd = new FormData();
    this.shadowRoot.querySelectorAll('input').forEach(input => {
      if (input.name) fd.set(input.name, input.value);
    });
    return fd;
  }

  set value(fd) {
    if (!(fd instanceof FormData)) return;
    this.shadowRoot.querySelectorAll('input').forEach(input => {
      if (input.name && fd.has(input.name)) {
        input.value = fd.get(input.name);
      }
    });
    this.internals.setFormValue(fd); // ← 同步表单值
    this.#updateValidity();
  }
}

customElements.define('my-name', MyName);

✅ HTML 使用示例

<form novalidate>
  <my-name name="user-name"></my-name>
  <button type="submit">提交</button>
</form>

<script>
  document.querySelector('form').addEventListener('submit', e => {
    e.preventDefault();
    const el = document.querySelector('my-name');
    if (el.reportValidity()) {
      console.log('验证通过，数据：', Object.fromEntries(el.value.entries()));
    }
  });
</script>

? 关键注意事项总结

• anchor 参数不可省略：setValidity(errors, message, anchor) 中 anchor 必须是当前已渲染、可聚焦（tabIndex >= 0 或原生可聚焦）、且属于该 shadow root 的 元素。
• 避免在 connectedCallback 中过早调用 setValidity：确保所有子 已挂载完成（推荐在 input/blur 事件中触发验证）。
• delegatesFocus: true 是前提：shadow root 创建时必须启用，否则内部 input 无法被 focus() 或浏览器自动聚焦。
• 不要覆盖 reportValidity() 方法体：直接代理 this.internals.reportValidity() 即可；自定义逻辑应在 #updateValidity() 中统一处理。
• formResetCallback 和 formDisabledCallback 必须实现：这是 FACE 规范强制要求，否则表单重置/禁用失效。
• 调试技巧：在 DevTools 中检查 el.internals 对象，观察 validity, validationMessage, willValidate 是否实时更新。

遵循以上模式，你的 FACE 将完全融入原生表单生态：支持 :valid/:invalid 伪类、form.checkValidity()、form.reportValidity()、无障碍焦点导航，以及无报错的原生提交流程。验证不再是个黑盒——而是可控、可测、可扩展的标准化能力。