ElementInternals

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2023年3月⁩.

* Some parts of this feature may have varying levels of support.

ElementInternals は Document Object Model のインターフェイスで、カスタム要素を HTML フォームに完全に参加させる方法をウェブ開発者に提供します。標準的な HTML フォーム要素を扱うのと同じように、これらの要素を扱うためのユーティリティを提供し、 Accessibility Object Model も要素で使えるようにします。

コンストラクター

このインターフェイスにはコンストラクターがありません。 ElementInternals オブジェクトは HTMLElement.attachInternals() を呼び出したときに返されます。

インスタンスプロパティ

ElementInternals.shadowRoot 読取専用: この要素に関連付けられた ShadowRoot オブジェクトを返します。
ElementInternals.form 読取専用: この要素に関連付けられた HTMLFormElement を返します。
ElementInternals.states 読取専用: この要素に関連付けられた CustomStateSet を返します。
ElementInternals.willValidate 読取専用: 論理値で、要素が制約検証の候補である送信可能要素である場合に true を返します。
ElementInternals.validity 読取専用: このオブジェクトは、制約検証に関して、その要素が取りうるさまざまな有効性の状態を表します。
ElementInternals.validationMessage 読取専用: 文字列で、この要素の検証メッセージが入ります。
ElementInternals.labels 読取専用: この要素に関連付けられているすべてのラベル要素の NodeList を返します。

ARIA から取り込まれたインスタンスプロパティ

ElementInternals インターフェイスには以下のプロパティもあります。

メモ: これらは、カスタム要素に既定のアクセシビリティ上の意味を定義できるようにするために取り込まれています。これらは作者が定義した属性によって上書きされる可能性がありますが、作者が属性を削除したり追加しなかったりした場合でも、既定の意味が保持されるようにします。詳しくは、 Accessibility Object Model explainer を参照してください。

ElementInternals.ariaAtomic: aria-atomic 属性を反映した文字列で、aria-relevant属性で定義された変更通知に基づいて、支援技術が変更された領域のすべてを提示するか、一部のみを提示するかを示します。
ElementInternals.ariaAutoComplete: aria-autocomplete 属性を反映した文字列で、テキスト入力が、コンボボックス、検索ボックス、またはテキストボックスに対するユーザーの意図する値の 1 つまたは複数の予測を表示するトリガーとなり得るかどうかを示し、予測が行われた場合にどのように表示されるかを指定します。
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 属性を反映した文字列で、テキストボックスが複数行の入力を受け付けるか、 1 行のみの入力を受け付けるかを示します。
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: フォーカスが composite ウィジェット、combobox、textbox、group、application のいずれかにある場合、現在アクティブな要素を表す要素です。 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");

// フォームに要素を追加して関連付ける
form.appendChild(element);

console.log(element.internals_.form);
// 予想される結果: <form><custom-checkbox></custom-checkbox></form>

仕様書

Specification
HTML # the-elementinternals-interface

ブラウザーの互換性

Help improve MDN

Learn how to contribute

This page was last modified on ⁨2025年6月19日⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content