借助新事件和自定义元素 API,参与表单变得更加容易。
许多开发者都会构建自定义表单控件,目的是提供浏览器中未内置的控件,或者自定义外观和风格,超越内置表单控件所能实现的效果。
不过,很难复制内置 HTML 表单控件的功能。请考虑在将 <input>
元素添加到表单后,该元素会自动获得的一些功能:
- 输入内容会自动添加到表单的控件列表中。
- 输入的值会随表单一起自动提交。
- 该输入会参与表单验证。您可以使用
:valid
和:invalid
伪类为输入设置样式。 - 当表单重置、重新加载或浏览器尝试自动填充表单条目时,系统会通知输入。
自定义表单控件通常只具备其中的少数几项功能。开发者可以绕过 JavaScript 的一些限制,例如向表单添加隐藏的 <input>
以参与表单提交。但有些功能无法仅使用 JavaScript 来实现。
两项新的 Web 功能让您可以更轻松地构建自定义表单控件,并消除了当前自定义控件的限制:
- 借助
formdata
事件,任意 JavaScript 对象都可以参与表单提交,因此您无需使用隐藏的<input>
即可添加表单数据。 - 借助与表单关联的自定义元素 API,自定义元素的行为更像内置表单控件。
这两项功能可用于创建效果更出色的新类型控件。
基于事件的 API
formdata
事件是一种低级 API,可让任何 JavaScript 代码参与表单提交。该机制的运作方式如下:
- 您需要向要与之互动的表单添加
formdata
事件监听器。 - 当用户点击“提交”按钮时,表单会触发
formdata
事件,其中包含一个FormData
对象,用于存储要提交的所有数据。 - 每个
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 与任何类型的组件搭配使用,但只能与提交流程互动。
除了提交之外,标准化表单控件还会参与表单生命周期的许多部分。表单关联的自定义元素旨在弥合自定义 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()
方法可以接受以下三种类型的值之一:
如需设置简单值,请执行以下操作:
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 上发布。