ElementInternals

Baseline 广泛可用 *

此功能已成熟，并可在许多设备和浏览器版本上运行。自 2023 年 3 月以来，它已在各种浏览器中可用。

* 此特性的某些部分可能存在不同级别的支持。

文档对象模型的 ElementInternals 接口为 Web 开发者提供了一种让自定义元素完全参与 HTML 表单的方式。它提供了与这些元素协同工作的实用工具，其方式与处理任何标准 HTML 表单元素相同，并且还向该元素公开了无障碍对象模型。

构造函数

此接口没有构造函数。在调用 HTMLElement.attachInternals() 时会返回一个 ElementInternals 对象。

实例属性

ElementInternals.shadowRoot 只读: 返回与此元素关联的 ShadowRoot 对象。
ElementInternals.form 只读: 返回与此元素关联的 HTMLFormElement。
ElementInternals.states 只读: 返回与此元素关联的 CustomStateSet。
ElementInternals.willValidate 只读: 一个布尔值，如果该元素是可提交元素，且是约束验证的候选者，则返回 true。
ElementInternals.validity 只读: 返回一个 ValidityState 对象，该对象表示元素在约束验证方面可能处于的不同有效性状态。
ElementInternals.validationMessage 只读: 一个包含此元素的验证消息的字符串。
ElementInternals.labels 只读: 返回与此元素关联的所有 label 元素的 NodeList。

ARIA 包含的实例属性

ElementInternals 接口还包含以下属性。

注意：包含这些属性是为了在自定义元素上定义默认的可访问性语义。这些属性可能会被作者定义的属性覆盖，但可确保在作者删除或完全未添加这些属性时，默认语义得以保留。更多信息请参阅无障碍对象模型说明。

ElementInternals.ariaAtomic: 一个字符串，反映 aria-atomic 属性，指示辅助技术是否会根据 aria-relevant 属性定义的更改通知，显示更改区域的全部或部分。
ElementInternals.ariaAutoComplete: 一个字符串，反映 aria-autocomplete 属性，指示输入文本是否会触发显示一个或多个用户对组合框、搜索框或文本框的预期值的预测，并指定如果进行预测，它们将如何呈现。
ElementInternals.ariaBrailleLabel: 一个字符串，反映 aria-braillelabel 属性，定义元素的盲文标签。
ElementInternals.ariaBrailleRoleDescription: 一个字符串，反映 aria-brailleroledescription 属性，定义元素的 ARIA 盲文角色描述。
ElementInternals.ariaBusy: 一个字符串，反映 aria-busy 属性，指示元素是否正在被修改，因为辅助技术可能希望等到修改完成才向用户公开它们。
ElementInternals.ariaChecked: 一个字符串，反映 aria-checked 属性，指示复选框、单选按钮以及其他具有选中状态的控件的当前“选中”状态。
ElementInternals.ariaColCount: 一个字符串，反映 aria-colcount 属性，定义表格、网格或树网格中的列数。
ElementInternals.ariaColIndex: 一个字符串，反映 aria-colindex 属性，定义元素相对于表格、网格或树网格中总列数的列索引或位置。
ElementInternals.ariaColIndexText: 一个字符串，反映 aria-colindextext 属性，定义 aria-colindex 的人类可读文本替代项。
ElementInternals.ariaColSpan: 一个字符串，反映 aria-colspan 属性，定义表格、网格或树网格中单元格或网格单元格所跨越的列数。
ElementInternals.ariaCurrent: 一个字符串，反映 aria-current 属性，指示容器或一组相关元素中代表当前项的元素。
ElementInternals.ariaDescription: 一个字符串，反映 aria-description 属性，定义描述或注释当前 ElementInternals 的字符串值。
ElementInternals.ariaDisabled: 一个字符串，反映 aria-disabled 属性，指示元素可见但已禁用，因此不可编辑或以其他方式操作。
ElementInternals.ariaExpanded: 一个字符串，反映 aria-expanded 属性，指示此元素拥有或控制的分组元素是展开还是折叠。
ElementInternals.ariaHasPopup: 一个字符串，反映 aria-haspopup 属性，指示可由 ElementInternals 触发的交互式弹出元素的可用性和类型，例如菜单或对话框。
ElementInternals.ariaHidden: 一个字符串，反映 aria-hidden 属性，指示元素是否暴露给辅助功能 API。
ElementInternals.ariaInvalid: 一个字符串，反映 aria-invalid 属性，指示输入的值不符合应用程序预期的格式。
ElementInternals.ariaKeyShortcuts: 一个字符串，反映 aria-keyshortcuts 属性，指示作者为激活或聚焦对象而实现的键盘快捷键。
ElementInternals.ariaLabel: 一个字符串，反映 aria-label 属性，定义标记当前对象的字符串值。
ElementInternals.ariaLevel: 一个字符串，反映 aria-level 属性，定义结构中元素的层次级别。
ElementInternals.ariaLive: 一个字符串，反映 aria-live 属性，指示元素将被更新，并描述用户代理、辅助技术和用户可以从活动区域预期的更新类型。
ElementInternals.ariaModal: 一个字符串，反映 aria-modal 属性，指示元素显示时是否为模态。
ElementInternals.ariaMultiline: 一个字符串，反映 aria-multiline 属性，指示文本框是否接受多行输入或只接受单行。
ElementInternals.ariaMultiSelectable: 一个字符串，反映 aria-multiselectable 属性，指示用户可以从当前可选择的后代中选择多个项目。
ElementInternals.ariaOrientation: 一个字符串，反映 aria-orientation 属性，指示元素的朝向是水平、垂直，还是未知/模糊。
ElementInternals.ariaPlaceholder: 一个字符串，反映 aria-placeholder 属性，定义一个简短的提示，旨在帮助用户在控件没有值时输入数据。
ElementInternals.ariaPosInSet: 一个字符串，反映 aria-posinset 属性，定义元素在当前列表项或树项集中的编号或位置。
ElementInternals.ariaPressed: 一个字符串，反映 aria-pressed 属性，指示切换按钮的当前“按下”状态。
ElementInternals.ariaReadOnly: 一个字符串，反映 aria-readonly 属性，指示元素不可编辑，但可以操作。
ElementInternals.ariaRelevant 非标准: 一个字符串，反映 aria-relevant 属性，指示当活动区域内的辅助功能树被修改时，用户代理将触发哪些通知。这用于描述 aria-live 区域中哪些更改是相关的，并且应该被宣布。
ElementInternals.ariaRequired: 一个字符串，反映 aria-required 属性，指示在提交表单之前，元素上需要用户输入。
ElementInternals.role: 一个包含 ARIA 角色的字符串。ARIA 角色的完整列表可以在 ARIA 技术页面上找到。
ElementInternals.ariaRoleDescription: 一个字符串，反映 aria-roledescription 属性，定义了一个人类可读的、作者本地化的元素角色描述。
ElementInternals.ariaRowCount: 一个字符串，反映 aria-rowcount 属性，定义表格、网格或树网格中的总行数。
ElementInternals.ariaRowIndex: 一个字符串，反映 aria-rowindex 属性，定义元素相对于表格、网格或树网格中总行数的行索引或位置。
ElementInternals.ariaRowIndexText: 一个字符串，反映 aria-rowindextext 属性，定义 aria-rowindex 的人类可读文本替代项。
ElementInternals.ariaRowSpan: 一个字符串，反映 aria-rowspan 属性，定义表格、网格或树网格中单元格或网格单元格所跨越的行数。
ElementInternals.ariaSelected: 一个字符串，反映 aria-selected 属性，指示具有选中状态的元素的当前“选中”状态。
ElementInternals.ariaSetSize: 一个字符串，反映 aria-setsize 属性，定义当前列表项或树项集中的项目数量。
ElementInternals.ariaSort: 一个字符串，反映 aria-sort 属性，指示表格或网格中的项目是按升序还是降序排序。
ElementInternals.ariaValueMax: 一个字符串，反映 aria-valueMax 属性，定义范围控件的最大允许值。
ElementInternals.ariaValueMin: 一个字符串，反映 aria-valueMin 属性，定义范围控件的最小允许值。
ElementInternals.ariaValueNow: 一个字符串，反映 aria-valueNow 属性，定义范围控件的当前值。
ElementInternals.ariaValueText: 一个字符串，反映 aria-valuetext 属性，定义范围控件的 aria-valuenow 的人类可读文本替代项。

从 ARIA 元素引用反射的实例属性

这些属性反映了相应属性中由 id 引用指定的元素，但有一些注意事项。更多信息请参阅《反射属性》指南中的反射元素引用。

ElementInternals.ariaActiveDescendantElement: 当焦点位于复合小部件、组合框、文本框、组或应用程序时，表示当前活动元素的元素。反映 aria-activedescendant 属性。
ElementInternals.ariaControlsElements: 一个元素数组，其内容或存在由其所应用的元素控制。反映 aria-controls 属性。
ElementInternals.ariaDescribedByElements: 一个元素数组，包含其所应用的元素的无障碍描述。反映 aria-describedby 属性。
ElementInternals.ariaDetailsElements: 一个元素数组，为所应用的元素提供无障碍详细信息。反映 aria-details 属性。
ElementInternals.ariaErrorMessageElements: 一个元素数组，为所应用的元素提供错误消息。反映 aria-errormessage 属性。
ElementInternals.ariaFlowToElements: 一个元素数组，用于标识内容备用阅读顺序中的下一个元素（或多个元素），在用户判断下覆盖一般默认阅读顺序。反映 aria-flowto 属性。
ElementInternals.ariaLabelledByElements: 一个元素数组，为所应用的元素提供无障碍名称。反映 aria-labelledby 属性。
ElementInternals.ariaOwnsElements: 一个元素数组，由其所应用的元素拥有。当 DOM 层次结构不能用于表示父元素与其子元素之间的关系时，这用于定义它们之间的视觉、功能或上下文关系。反映 aria-owns 属性。

实例方法

ElementInternals.setFormValue(): 设置元素的提交值和状态，并将其传达给用户代理。
ElementInternals.setValidity(): 设置元素的有效性。
ElementInternals.checkValidity(): 检查元素是否符合应用于它的任何约束验证规则。
ElementInternals.reportValidity(): 检查元素是否符合应用于它的任何约束验证规则，并向用户代理发送验证消息。

示例

以下示例演示如何使用 HTMLElement.attachInternals 创建自定义表单关联元素。

class CustomCheckbox extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals_ = this.attachInternals();
  }

  // …
}

window.customElements.define("custom-checkbox", CustomCheckbox);

let element = document.createElement("custom-checkbox");
let form = document.createElement("form");

// Append element to form to associate it
form.appendChild(element);

console.log(element.internals_.form);
// expected output: <form><custom-checkbox></custom-checkbox></form>

规范

规范
HTML # elementinternals 接口

浏览器兼容性

另见

更强大的表单控件 (web.dev, 2019)
使用 ElementInternals 创建自定义表单控件 (CSS-tricks, 2021)

帮助改进 MDN

了解如何贡献

此页面由 MDN 贡献者于 2025 年 5 月 2 日最后修改。

在 GitHub 上查看此页面 • 报告此内容的问题