更强大的表单控件

通过新的事件和自定义元素 API，您可以更轻松地参与表单。

许多开发者会构建自定义表单控件，以便提供未内置于浏览器的控件，或者自定义外观超出内置表单控件所能达到的范畴。

但是，您可能很难再现内置 HTML 表单控件的功能。设想一下当您将 <input> 元素添加到表单时，它会自动获得的一些功能：

• 输入内容会自动添加到表单的控件列表中。
• 输入的值会随表单自动提交。
• 输入内容参与表单验证。您可以使用 :valid 和 :invalid 伪类设置输入的样式。
• 当表单重置、表单重新加载或浏览器尝试自动填充表单条目时，系统会通知输入内容。

自定义表单控件通常具备以下几项功能。开发者可以解决 JavaScript 中的一些限制，例如向表单添加隐藏的 <input> 来参与表单提交。但是，其他功能是单靠 JavaScript 无法复制的。

两项新的 Web 功能可让您更轻松地构建自定义表单控件，并消除了当前自定义控件的限制：

• formdata 事件可让任意 JavaScript 对象参与表单提交，因此您无需使用隐藏的 <input> 即可添加表单数据。
• 通过与表单关联的自定义元素 API，自定义元素的行为方式更像是内置表单控件。

这两项功能可用于创建效果更好的新控件。

基于事件的 API

formdata 事件是一种低阶 API，可让任何 JavaScript 代码参与表单提交。该机制的运作方式如下：

1. 您将 formdata 事件监听器添加到要互动的表单。
2. 当用户点击提交按钮时，表单会触发 formdata 事件，其中包含一个 FormData 对象，用于保存提交的所有数据。
3. 每个 formdata 监听器都有机会在提交表单之前添加或修改数据。

以下是在 formdata 事件监听器中发送单个值的示例：

const form = document.querySelector('form');
// FormData event is sent on <form> submission, before transmission.
// The event has a formData property
form.addEventListener('formdata', ({formData}) => {
  // https://developer.mozilla.org/docs/Web/API/FormData
  formData.append('my-input', myInputValue);
});

使用我们在 Glitch 上的示例尝试一下。请务必在 Chrome 77 或更高版本上运行该 API，以查看 API 的实际效果。

浏览器兼容性

与表单关联的自定义元素

您可以对任何种类的组件使用基于事件的 API，但该 API 只允许您与提交流程进行互动。

除了提交之外，标准化表单控件参与表单生命周期的许多部分。与表单关联的自定义元素旨在弥合自定义 widget 和内置控件之间的差距。与表单关联的自定义元素与标准化表单元素的许多功能相匹配：

• 当您将与表单关联的自定义元素放置在 <form> 内时，它会自动与表单相关联，就像浏览器提供的控件一样。
• 您可以使用 <label> 元素为该元素加标签。
• 元素可以设置随表单自动提交的值。
• 该元素可以设置一个标记，用于表明它是否具有有效输入。如果其中一个表单控件包含无效输入内容，则无法提交表单。
• 元素可以为表单生命周期的各个部分（例如，当表单被停用或重置为默认状态时）提供回调。
• 此元素支持表单控件的标准 CSS 伪类，例如 :disabled 和 :invalid。

可以使用这么多功能！本文不会提及所有这些选项，但会介绍将自定义元素与表单集成所需的基本信息。

定义与表单关联的自定义元素

如需将自定义元素转换为与表单关联的自定义元素，您还需要执行一些额外的步骤：

• 将静态 formAssociated 属性添加到自定义元素类中。这会告知浏览器将相应元素视为表单控件。
• 对该元素调用 attachInternals() 方法，以获取表单控件的额外方法和属性，例如 setFormValue() 和 setValidity()。
• 添加表单控件支持的常用属性和方法，例如 name、value 和 validity。

下面介绍了这些项与基本自定义元素定义的关系：

// Form-associated custom elements must be autonomous custom elements--
// meaning they must extend HTMLElement, not one of its subclasses.
class MyCounter extends HTMLElement {

  // Identify the element as a form-associated custom element
  static formAssociated = true;

  constructor() {
    super();
    // Get access to the internal form control APIs
    this.internals_ = this.attachInternals();
    // internal value for this control
    this.value_ = 0;
  }

  // Form controls usually expose a "value" property
  get value() { return this.value_; }
  set value(v) { this.value_ = v; }

  // The following properties and methods aren't strictly required,
  // but browser-level form controls provide them. Providing them helps
  // ensure consistency with browser-provided controls.
  get form() { return this.internals_.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }
  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(); }

  …
}
customElements.define('my-counter', MyCounter);

注册后，您就可以在使用浏览器提供的表单控件的任何位置使用此元素了：

<form>
  <label>Number of bunnies: <my-counter></my-counter></label>
  <button type="submit">Submit</button>
</form>

设置值

attachInternals() 方法会返回一个 ElementInternals 对象，该对象可提供对表单控制 API 的访问权限。其中最基本的是 setFormValue() 方法，用于设置控件的当前值。

setFormValue() 方法可以采用以下三种类型的值之一：

• 字符串值。
• 一个 File 对象。
• 一个 FormData 对象。您可以使用 FormData 对象传递多个值（例如，信用卡输入控件可能会传递卡号、失效日期和验证码）。

如需设置简单值，请执行以下操作：

this.internals_.setFormValue(this.value_);

如需设置多个值，您可以执行如下操作：

// Use the control's name as the base name for submitted data
const n = this.getAttribute('name');
const entries = new FormData();
entries.append(n + '-first-name', this.firstName_);
entries.append(n + '-last-name', this.lastName_);
this.internals_.setFormValue(entries);

输入验证

您的控件还可以通过对内部对象调用 setValidity() 方法来参与表单验证。

// Assume this is called whenever the internal value is updated
onUpdateValue() {
  if (!this.matches(':disabled') && this.hasAttribute('required') &&
      this.value_ < 0) {
    this.internals_.setValidity({customError: true}, 'Value cannot be negative.');
  }
  else {
    this.internals_.setValidity({});
  }
  this.internals.setFormValue(this.value_);
}

您可以使用 :valid 和 :invalid 伪类设置与表单关联的自定义元素的样式，就像内置表单控件一样。

生命周期回调

与表单关联的自定义元素 API 包含一组与表单生命周期相关联的额外的生命周期回调。回调是可选的：仅当您的元素需要在生命周期的相应时间点执行某些操作时，才实现回调。

void formAssociatedCallback(form)

在浏览器将元素与表单元素关联，或取消元素与表单元素的关联时调用该方法。

void formDisabledCallback(disabled)

在元素的 disabled 状态发生变化后调用，原因可能是添加或移除了此元素的 disabled 属性；或者由于作为此元素的祖先实体 <fieldset> 上的 disabled 状态发生变化。disabled 参数表示元素的新停用状态。例如，停用元素时，可停用其 shadow DOM 中的元素。

void formResetCallback()

在表单重置后调用。元素应自行重置为某种默认状态。对于 <input> 元素，这通常涉及将 value 属性设置为与标记中设置的 value 属性匹配（如果是复选框，则将 checked 属性设置为与 checked 属性匹配）。

void formStateRestoreCallback(state, mode)

在以下两种情况下调用：

• 浏览器恢复元素状态时（例如，导航后或浏览器重启时）。在本例中，mode 参数为 "restore"。
• 当浏览器的输入辅助功能（例如表单自动填充）设置值时。在本例中，mode 参数为 "autocomplete"。

第一个参数的类型取决于 setFormValue() 方法的调用方式。如需了解详情，请参阅恢复表单状态。

正在恢复表单状态

在某些情况下（例如，在导航回页面或重新启动浏览器时），浏览器可能会尝试将表单恢复为用户离开时的状态。

对于与表单关联的自定义元素，恢复的状态来自您传递给 setFormValue() 方法的值。调用该方法时可使用单个值参数（如前面的示例所示），也可以使用两个参数：

this.internals_.setFormValue(value, state);

value 表示对照组的可提交值。可选的 state 参数是控件状态的内部表示方式，可能包含未发送到服务器的数据。state 形参的类型与 value 形参相同，可以是字符串、File 或 FormData 对象。

如果您无法仅根据值来恢复控件的状态，state 参数就非常有用。例如，假设您创建了一个具有多种模式的颜色选择器：调色板或 RGB 色轮。可提交的 value 将采用规范形式的选定颜色，例如 "#7fff00"。不过，要将控件恢复到特定状态，您还需要知道它处于哪种模式，因此状态可能类似于 "palette/#7fff00"。state

this.internals_.setFormValue(this.value_,
    this.mode_ + '/' + this.value_);

您的代码需要根据存储的状态值恢复其状态。

formStateRestoreCallback(state, mode) {
  if (mode == 'restore') {
    // expects a state parameter in the form 'controlMode/value'
    [controlMode, value] = state.split('/');
    this.mode_ = controlMode;
    this.value_ = value;
  }
  // Chrome currently doesn't handle autofill for form-associated
  // custom elements. In the autofill case, you might need to handle
  // a raw value.
}

对于较简单的控件（例如数字输入），该值可能足以将控件恢复到之前的状态。如果您在调用 setFormValue() 时省略 state，则系统会将值传递给 formStateRestoreCallback()。

formStateRestoreCallback(state, mode) {
  // Simple case, restore the saved value
  this.value_ = state;
}

可操作的示例

以下示例汇总了与表单关联的自定义元素的许多功能。请务必在 Chrome 77 或更高版本上运行该 API，以查看 API 的实际效果。

功能检测

您可以使用功能检测来确定 formdata 事件以及与表单关联的自定义元素是否可用。目前，这两个功能都未发布任何 polyfill。在这两种情况下，您都可以回退到添加隐藏的表单元素，以便将控件的值传播到表单。对于与表单关联的自定义元素，许多更高级的功能可能难以执行 polyfill 操作。

if ('FormDataEvent' in window) {
  // formdata event is supported
}

if ('ElementInternals' in window &&
    'setFormValue' in window.ElementInternals.prototype) {
  // Form-associated custom elements are supported
}

总结

formdata 事件以及与表单关联的自定义元素提供了用于创建自定义表单控件的新工具。

formdata 事件不会为您提供任何新功能，但为您提供一个接口，可让您将表单数据添加到提交流程，而无需创建隐藏的 <input> 元素。

与表单关联的自定义元素 API 提供了一组新功能，可让您创建像内置表单控件一样工作的自定义表单控件。

主打图片，创作者：Oudom Pravat 在 Unsplash 用户。