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 上檢視此頁面 • 報告此內容的問題