ElementInternals

基线 2023

新可用

自 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 只读: 返回与此元素关联的所有标签元素的 NodeList。

包含自 ARIA 的实例属性

ElementInternals 接口还包括以下属性。

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

ElementInternals.ariaAtomic: 反映 aria-atomic 属性的字符串，该属性指示辅助技术是根据 aria-relevant 属性定义的更改通知呈现更改区域的所有部分还是仅呈现部分内容。
ElementInternals.ariaAutoComplete: 反映 aria-autocomplete 属性的字符串，该属性指示输入文本是否会触发显示一个或多个用户对组合框、搜索框或文本框的预期值的预测，并指定如果进行了预测，将如何呈现这些预测。
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.ariaKeyShortcuts: 反映 aria-keyshortcuts 属性的字符串，该属性指示作者为激活或将焦点赋予 ElementInternals 而实现的键盘快捷键。
ElementInternals.ariaLabel: 反映 aria-label 属性的字符串，该属性定义标记当前 ElementInternals 的字符串值。
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 的人类可读文本替代。

实例方法

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 标准 # the-elementinternals-interface

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。