ElementInternals

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

ElementInternalsDocument 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.ariaBusy

aria-busy 属性を反映した文字列で、要素が変更されているかどうかを示すもので、支援技術はユーザーに公開する前に変更が完了するまで待ちたい場合があります。

ElementInternals.ariaChecked

aria-checked 属性を反映した文字列で、チェックボックス、ラジオボタン、その他のチェック状態を持つウィジェットの現在の「チェックされた」状態を示します。

ElementInternals.ariaColCount

aria-colcount 属性を反映した文字列で、テーブル、グリッド、ツリーグリッドの列数を定義します。

ElementInternals.ariaColIndex

aria-colindex 属性を反映した文字列で、テーブル、グリッド、ツリーグリッド内の列の総数に対する要素の列インデックスまたは位置を定義します。

ElementInternals.ariaColIndexText Experimental

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 属性を反映した文字列で、テキストボックスが複数行の入力を受け付けるか、 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 Non-standard

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 Experimental

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 で作成する方法を示しています。

js
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);
// expected output: <form><custom-checkbox></custom-checkbox></form>

仕様書

Specification
HTML Standard
# the-elementinternals-interface

ブラウザーの互換性

BCD tables only load in the browser

関連情報