更强大的表单控件

通过合集保持井然有序 根据您的偏好保存内容并进行分类。

借助新的事件和自定义元素 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://mdn.org.cn/docs/Web/API/FormData
  formData.append('my-input', myInputValue);
});

使用我们在 Glitch 上的示例试用一下。请务必在 Chrome 77 或更高版本上运行它以查看 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);

输入验证

您的控件还可以通过调用 internals 对象上的 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 色轮。可提交的值将是以规范形式表示的所选颜色，例如 "#7fff00"。但是，要将控件恢复到特定状态，您还需要知道它处于哪种模式，因此状态可能类似于 "palette/#7fff00"。

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 的实际效果。

功能检测

您可以使用功能检测来确定 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 上提供。