UI イベント

1. はじめに

1.1. 概要

UI Eventsは主に2つの目的で設計されています。最初の目的は、event システムを設計することであり、これにより event listeners の登録を可能にし、イベントがツリー構造を通じて流れる仕組みを記述します。さらに、本仕様ではユーザーインターフェイス制御やドキュメントの変更通知のための標準的なイベントモジュールを提供し、これらの各イベントモジュールに関するコンテキスト情報も定義します。

UI Eventsの2つ目の目的は、現行のブラウザで使用されているイベントシステムの共通部分集合を提供することです。これは、既存のスクリプトやコンテンツの相互運用性を促進するためです。この目的が完全な後方互換性を持って達成されるとは期待されていませんが、可能な限りその達成を目指しています。

1.2. 適合性

このセクションは規範的です。

本仕様書内では、キーワード MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、および OPTIONAL は [RFC2119] で説明されている通りに解釈されます。

本仕様はDOM Level 3 Core仕様書 [DOM-Level-3-Core] の文脈で理解されるべきであり、DOM実装に関する一般的な考慮事項が適用されます。例えば、namespace URIs の扱いについては XML Namespaces で論じられています。 適合性 についての追加情報は、DOM Level 3 Core仕様書 [DOM-Level-3-Core] を参照してください。user agent は本仕様に適合するために他の仕様全体に適合する必要はありませんが、本仕様で言及されている他仕様の特定部分には必ず適合しなければなりません（例：適合するUI Events user agent は DOMString データ型を [WebIDL] で定義されている通りにサポートしなければなりませんが、UI Eventsに適合するだけで [WebIDL] で定義されているすべてのメソッドやデータ型をサポートする必要はありません）。

本仕様では、異なる user agent、仕様、コンテンツ著者向けに複数の適合クラスを定義しています：

1.2.1. Webブラウザおよびその他の動的または対話的な user agents

動的または対話的な user agent、ここでは「ブラウザ」と呼びます（Webブラウザ、AT（アクセシビリティ技術）アプリケーション、またはそれに類するプログラムなど）、は次の条件を満たす場合UI Eventsに適合します：

• [DOM-Level-3-Core] で定義されているCoreモジュール

• 本仕様で定義されているすべてのインターフェイスおよびイベント、その関連メソッド、属性、および意味論（ただし deprecated と記されたものは除く。適合するuser agentは、後方互換性のためにdeprecatedなインターフェイス、イベント、APIを実装してもよいが、適合要件ではない）

• [UIEvents-Key] および [UIEvents-Code] で定義されている key および code の全値（プラットフォームで利用可能な場合）、および

• 本仕様で定義されているその他すべての規範的要件。

適合するブラウザは、条件が満たされたとき、適切な EventTarget に イベントを発火 しなければなりません。

ブラウザは、本ドキュメントで定義されたインターフェイスおよび関連する event types を実装している場合、UI Eventsに特化して適合しているといえます。

適合するブラウザは、スクリプティング、宣言型インタラクティビティ、またはその他の方法で、イベントの検出および発火を本仕様で記述された方法でサポートしなければならず、また event type 用に仕様されたAPIもサポートしなければなりません。

その他の適合基準をすべて満たすことに加えて、適合するブラウザは後方互換性のために deprecated と記された仕様の機能を実装してもかまいませんが、その実装は推奨されません。

適合するブラウザは、本仕様にない機能（ただし本仕様で定義されたインターフェイス、イベント、またはその他の機能を用いるもの）をサポートしたり、実装に応じて追加のインターフェイスや event types を実装してもかまいません。こうした機能は将来の仕様で標準化されることもあります。

本仕様の必須部分すべてに適合しないブラウザは、UI Eventsへの適合を主張してはなりません。部分的に本仕様に適合する実装は、その特定部分への適合のみを主張できます。

適合するブラウザは、Web IDL仕様 [WebIDL] で説明されているように、インターフェイス定義言語（IDL）断片の 適合する実装 でもなければなりません。

1.2.2. オーサリングツール

コンテンツオーサリングツールは、本仕様で定義された event types を一貫して使用するコンテンツを生成する場合、UI Eventsに適合しています。

オーサリングツールは、生成するコンテンツが本仕様で deprecated と記された機能を使用している場合、そのコンテンツについてUI Eventsへの適合を主張してはなりません。

適合するコンテンツオーサリングツールは、コンテンツ著者が、コンテンツ文書で使用されるすべての event types およびインターフェイスを、すべての host languages に対して使用できるよう手段を提供すべきです。

1.2.3. コンテンツ著者およびコンテンツ

コンテンツ 著者 は、そのコンテンツが本仕様で定義された event types を一貫して使用する場合、UI Events適合コンテンツを作成したことになります。

コンテンツ著者は、本仕様で deprecated とされる機能を使用すべきではなく、代替手段（本仕様や他仕様で定義されているもの）を利用すべきです。

適合するコンテンツは、本仕様で記述されるインターフェイスや event types の意味論を守らなければなりません。

コンテンツ著者は、アクセシビリティ や 国際化 のガイドライン仕様で説明されるベストプラクティスに従うことが推奨されます。

1.2.4. 仕様およびホスト言語

仕様または host language は、[DOM] で定義されているイベントフロー機構、インターフェイス、イベント、またはその他の機能を参照し、これらの機能を非互換な方法で拡張しない場合、UI Eventsに適合します。

仕様または host language が、本ドキュメントで定義されたインターフェイスおよび関連する event types を参照し、使用する場合、UI Eventsに特化して適合しています。適合する仕様は、仕様に応じて追加のインターフェイスや event types を定義したり、UI Eventsのインターフェイスや event types を、この仕様で定義されている内容と矛盾または衝突しない方法で拡張してもかまいません。

UI Eventsを参照する仕様や host languages は、本仕様で deprecated とされる機能を使用または推奨すべきではなく、可能ならば推奨される代替手段を利用または推奨すべきです。

2. 記述上の慣例

本仕様は提案されたW3C仕様記述慣例 に従っていますが、以下の追加事項があります：

• キーに印字されている キーキャップ は ↓、=、Q といった形で表されます。これは、ユーザー視点でキーを参照する際に使用され、生成される key や code の値は考慮しません。

• 文字を表すグリフは "𣧂" のように示されます。

• Unicode文字コードは U+003d のように表記されます。

• キー押下によって生成されるキー値名（すなわち KeyboardEvent.key の値）は "ArrowDown"、 "="、"q"、"Q" のように示されます。

• 物理キーに関連付けられているキーコード名（すなわち KeyboardEvent.code の値）は "ArrowDown"、 "Equal"、 "KeyQ" のように示されます。

さらに、本仕様では特定の用語が特別な意味で用いられます。「実装」という用語は、本仕様を実装するブラウザ、コンテンツオーサリングツール、その他の user agent を指します。一方、コンテンツ著者は、本仕様で説明されているインターフェイス、メソッド、属性、イベント等を利用してWebアプリケーションを作成する人を指し、ユーザーはそのWebアプリケーションを実装上で利用する人です。

最後に：

これは注記です。

これは未解決の課題です。

これは警告です。

interface Example {
    // This is an IDL definition.
};

3. 基本イベントインターフェイス

[DOM] で定義される基本的なイベントインターフェイスは、UI Eventsに不可欠です。これらの基本イベントインターフェイスは実装で常にサポートされなければなりません：

• Event インターフェイスおよび以下の定数、メソッド、属性：

  • NONE 定数

  • CAPTURING_PHASE 定数

  • AT_TARGET 定数

  • BUBBLING_PHASE 定数

  • type 属性

  • target 属性

  • currentTarget 属性

  • eventPhase 属性

  • bubbles 属性

  • cancelable 属性

  • composed 属性

  • timeStamp 属性

  • defaultPrevented 属性

  • isTrusted 属性

  • stopPropagation() メソッド

  • stopImmediatePropagation() メソッド

  • preventDefault() メソッド

  • initEvent() メソッド

• CustomEvent インターフェイスおよび以下のメソッドと属性：

  • initCustomEvent() メソッド

  • detail 属性

• EventTarget インターフェイスおよび以下のメソッド：

  • addEventListener() メソッド

  • removeEventListener() メソッド

  • dispatchEvent() メソッド

• EventListener インターフェイスおよび handleEvent() メソッド

• Document インターフェイスの createEvent() メソッド

本仕様で定義されるイベント型はこれらの基本インターフェイスから派生し、派生元のインターフェイスが持つすべての属性、メソッド、定数を継承しなければなりません。

以下の図は本仕様で記述されるインターフェイスの継承構造を示します。

3.1. イベント型一覧

各イベントは イベント型 と呼ばれる型に関連づけられ、イベントオブジェクトの type 属性として利用できます。イベント型は DOMString 型でなければなりません。

DOMのサポートレベルや表示（例：画面）・操作（例：マウス、キーボード、タッチスクリーン、音声）用デバイスによって、こうしたイベント型は実装によって生成されます。[XML] や [HTML5] アプリケーションで使用される場合、それぞれの言語仕様によってイベント型に関連する意味論や範囲（特に イベントターゲット の可能性）が制限されることがあります。詳細や、本ドキュメントに定義されていないイベント型を探す場合は、各言語仕様を参照してください。

次の表は、本仕様で記述されるイベント型の情報まとめです。

本仕様で非推奨とされるイベント一覧については、ドキュメント末尾の 旧イベント型 付録を参照してください。

上記の表の解釈例：load イベントは、そのイベント向けに Element ノード上でキャプチャおよびターゲットフェーズでイベントリスナーが発火します。このイベントはキャンセルできません。event listener が Window、Document、Element ノード以外や、バブリングフェーズのみで登録された場合、この event listener は発火しません。

上記の表は記載されたイベント型について決定的なものとして解釈しないでください。例えば load イベントは他仕様でも使用されています（例：XMLHttpRequest）。同様に、dispatchEvent() は 任意の EventTarget を実装するオブジェクトでリスナーに非信頼イベントを発火できます。

上記イベント型に関連付けられるイベントオブジェクトは追加のコンテキスト情報を持っています。詳細はDOMインターフェイスの説明を参照してください。

3.2. ユーザーインターフェイスイベント

ユーザーインターフェイスイベントモジュールは、ユーザーインターフェイスやドキュメント操作に関連する基本的なイベント型を含みます。

3.2.1. UIEvent インターフェイス

DOM Level 2 で導入

UIEvent インターフェイスは、ユーザーインターフェイスイベントに関連する特定のコンテキスト情報を提供します。

UIEvent インターフェイスのインスタンスを生成するには、UIEvent コンストラクタを使用し、必要に応じて UIEventInit 辞書を渡します。

新しく定義されるイベントについては、ユーザーインターフェイスに関連するからといって UIEvent インターフェイスを必ず継承する必要はありません。UIEventInit のメンバーがそのイベントに意味を持つ場合のみ継承してください。

3.2.1.1. UIEvent

[Exposed=Window]
interface UIEvent : Event {
  constructor(DOMString type, optional UIEventInit eventInitDict = {});
  readonly attribute Window? view;
  readonly attribute long detail;
};

UIEvent . view

view 属性は、そのイベントが生成された Window を示します。

この属性の 未初期化値 は null でなければなりません。

UIEvent . detail

Event の種類に応じて、そのイベントに関する詳細情報を指定します。

この属性の 未初期化値 は 0 でなければなりません。

3.2.1.2. UIEventInit

dictionary UIEventInit : EventInit {
  Window? view = null;
  long detail = 0;
};

UIEventInit . view

この値は、このイベントが発火されるグローバル環境の Window オブジェクトに初期化すべきです。このイベントが要素に対して発火される場合は、view プロパティはその要素の ownerDocument を含む Window オブジェクトに設定します。

UIEventInit . detail

この値はアプリケーション固有の数値で初期化されます。

3.2.2. UIEvent のアルゴリズム

3.2.3. UIEvent 型

ユーザーインターフェイスイベント型を以下に示します。これらのイベントの一部は、ユーザーインターフェイスから生成された場合 UIEvent インターフェイスを使用しますが、詳細は各イベントごとに記載されています。

3.2.3.1. load

DOM実装がリソース（例：ドキュメント）および依存リソース（画像、スタイルシート、スクリプトなど）の読み込みを完了したとき、user agent はこのイベントを発火しなければなりません。依存リソースのロード失敗は、親リソースがDOM経由でアクセス可能であれば、このイベントの発火を妨げてはなりません。このイベント型が発火される場合、少なくとも Document ノードでこのイベントを発火する必要があります。

旧来の理由により、ドキュメント内のリソース（例：画像）に対する load イベントは、HTML 実装では伝播パスに Window を含みません。詳細は [HTML5] を参照してください。

3.2.3.2. unload

DOM実装が環境からリソース（例：ドキュメント）や依存リソース（画像、スタイルシート、スクリプトなど）を除去したとき、user agent はこのイベントを発火しなければなりません。このイベント型の発火後にドキュメントはアンロードされる必要があります。このイベント型が発火される場合、少なくとも Document ノードでこのイベントを発火する必要があります。

3.2.3.3. abort

リソースのロードが中断されたとき（例：ユーザーがロード中にキャンセルした場合）、user agent はこのイベントを発火しなければなりません。

3.2.3.4. error

リソースのロードに失敗した場合や、ロードされたが意味的に解釈できない場合（例：不正な画像、スクリプト実行エラー、非整形式XMLなど）、user agent はこのイベントを発火しなければなりません。

3.2.3.5. select

ユーザーがテキストを選択したとき、user agent はこのイベントを選択後に発火しなければなりません。

本仕様では選択されたテキストへのアクセスに関するコンテキスト情報は提供しません。該当する場合、ホスト言語は、ユーザーがどのように内容を選択できるか（国際的な言語慣習も考慮）、select イベントがどのタイミングで発火されるか、コンテンツ著者がユーザー選択内容にどのようにアクセスできるかを定義するべきです。

ユーザー選択内容へアクセスするには、コンテンツ著者は ホスト言語のネイティブ機能（HTML 編集APIの Document.getSelection() メソッドなど）を使用します。[Editing]

select イベントはすべての要素や言語で利用できるとは限りません。例えば [HTML5] では select イベントはフォームの input や textarea 要素でのみ発火できます。 実装は、フォームコントロール外のテキスト選択やSVGなどの画像やマークアップ選択など、適切と判断されるコンテキストで select イベントを発火してもかまいません。

3.3. フォーカスイベント

このインターフェイスと関連するイベント型、および § 3.3.2 フォーカスイベント順序は、User Agent Accessibility Guidelines 2.0 [UAAG20] で定義された概念・指針に基づいて設計されています。 特に フォーカスメカニズム や glossary の focus の定義に注意しています。

3.3.1. FocusEvent インターフェイス

本仕様で導入

FocusEvent インターフェイスは、フォーカスイベントに関連する特定のコンテキスト情報を提供します。

FocusEvent インターフェイスのインスタンスを生成するには、FocusEvent コンストラクタを使用し、必要に応じて FocusEventInit 辞書を渡します。

3.3.1.1. FocusEvent

[Exposed=Window]
interface FocusEvent : UIEvent {
  constructor(DOMString type, optional FocusEventInit eventInitDict = {});
  readonly attribute EventTarget? relatedTarget;
};

FocusEvent . relatedTarget

イベントの種類に応じて、フォーカスイベントに関連する二次的な EventTarget を識別するために使用します。

ネストされたブラウジングコンテキストとのセキュリティ上の理由から、入出時に関連する EventTarget は null であるべきです。

この属性の 未初期化値 は null でなければなりません。

3.3.1.2. FocusEventInit

dictionary FocusEventInit : UIEventInit {
  EventTarget? relatedTarget = null;
};

FocusEventInit . relatedTarget

relatedTarget は、focus や focusin イベントの場合はフォーカスを失う要素、blur や focusout イベントの場合はフォーカスを得る要素に初期化してください。

3.3.2. フォーカスイベント順序

本仕様で定義されるフォーカスイベントは、相互間で一定の順序で発生します。以下は、フォーカスが要素間で移動する典型的なイベントシーケンスです（最初はどの要素にもフォーカスがないと仮定）：

本仕様では focus() や blur() といったメソッドを使った場合のフォーカスイベントの動作は定義しません。該当メソッドが定義されている仕様を参照してください。

3.3.3. ドキュメントフォーカスとフォーカスコンテキスト

このイベントモジュールには、ドキュメントの フォーカス の変更通知のイベント型が含まれます。フォーカスコンテキストには、次の3つの区分があります：

• OSフォーカスコンテキスト：コンピュータ上で現在実行中の複数のアプリケーションのいずれかにフォーカスがある可能性があります。そのうちフォーカスを持つアプリケーションとしてブラウザが含まれる場合があります。

• ブラウザがフォーカスを持つ場合、ユーザーは（例：Tabキーで）アプリケーションフォーカスコンテキストをブラウザのUIフィールド（Webサイトのロケーションバー、検索フィールド等）間で切り替えることができます。そのUIフィールドの一つがタブ内のドキュメントである場合があります。

• ドキュメント自体がフォーカスを持つ場合、ドキュメントフォーカスコンテキストはドキュメント内の任意のフォーカス可能要素に設定できます。

本仕様で定義されるイベント型はドキュメントフォーカスのみを対象にしており、イベント詳細で識別される event target はウィンドウ内のドキュメント（または複数ドキュメント）の一部でなければならず、ブラウザやOSの一部であってはなりません（フォーカスコンテキスト間の切り替え時も同様）。

通常、ドキュメントには常にフォーカスされた要素（ドキュメント要素自身の場合も含む）と持続的な フォーカスリング があります。フォーカスコンテキスト間を切り替える場合も、ドキュメントの現在のフォーカス要素とフォーカスリングは通常そのまま維持されます。例えば、3つのフォーカス可能要素があるドキュメントで、2番目の要素がフォーカスされている場合に、ユーザーがOSのフォーカスを他アプリに移し、再びブラウザに戻しても、ドキュメント内では2番目の要素がフォーカスされており、Tabキー操作で3番目の要素にフォーカスが移ります。ホスト言語 は、特定の要素がフォーカスを受け取る条件や方法、フォーカスの変更手段や順序などを定義してもかまいません。例えば、ある場合はポインタ移動でフォーカスを得たり、他の場合はクリックが必要だったりします。フォーカスできない要素や、クリックのみでフォーカスできTabキーではできない要素もあり得ます。ドキュメントは複数のフォーカスリングを持つ場合もあり、他仕様でより複雑なフォーカスモデル（複数要素が同時にフォーカスを持つ等）が定義されることもあります。

3.3.4. フォーカスイベント型

フォーカスイベント型を以下に示します。

3.3.4.1. blur

user agent は、event target がフォーカスを失ったとき、このイベントを発火しなければなりません。フォーカスはこのイベント型の発火前に要素から取り除かれなければなりません。このイベント型は focusout に似ていますが、バブリングしません。

3.3.4.2. focus

user agent は、event target がフォーカスを受け取ったとき、このイベントを発火しなければなりません。フォーカスはこのイベント型の発火前に要素に付与されなければなりません。このイベント型は focusin に似ていますが、バブリングしません。

3.3.4.3. focusin

user agent は、event target がフォーカスを受け取ったとき、このイベントを発火しなければなりません。event target はフォーカスを受け取った要素でなければなりません。focus イベントはこのイベント型の発火前に発火される必要があります。このイベント型は focus に似ていますが、バブリングします。

3.3.4.4. focusout

user agent は、event target がフォーカスを失ったとき、このイベントを発火しなければなりません。event target はフォーカスを失った要素でなければなりません。blur イベントはこのイベント型の発火前に発火される必要があります。このイベント型は blur に似ていますが、バブリングします。

3.4. マウスイベント

マウスイベントモジュールは、[HTML401] の onclick、ondblclick、 onmousedown、onmouseup、onmouseover、onmousemove、 onmouseout 属性に由来します。本イベントモジュールは、マウスやトラックボールなどのポインティング入力デバイスで使用するために特化して設計されています。

3.4.1. MouseEvent インターフェイス

DOM Level 2 で導入され、本仕様で修正

MouseEvent インターフェイスは、マウスイベントに関連する特定のコンテキスト情報を提供します。

ネストされた要素の場合、マウスイベントは常に最も深い入れ子の要素がターゲットとなります。

ターゲット要素の祖先は、イベントバブリングを利用して、その子孫要素内で発生したマウスイベントの通知を受け取ることができます。

MouseEvent インターフェイスのインスタンスを生成するには、MouseEvent コンストラクタを使用し、必要に応じて MouseEventInit 辞書を渡します。

MouseEvent オブジェクトを initMouseEvent で初期化する場合、実装は clientX や clientY などのクライアント座標を用いて他の座標（DOM Level 0 実装や独自属性、例：pageXなど）を計算することができます。

3.4.1.1. MouseEvent

[Exposed=Window]
interface MouseEvent : UIEvent {
  constructor(DOMString type, optional MouseEventInit eventInitDict = {});
  readonly attribute long screenX;
  readonly attribute long screenY;
  readonly attribute long clientX;
  readonly attribute long clientY;
  readonly attribute long layerX;
  readonly attribute long layerY;

  readonly attribute boolean ctrlKey;
  readonly attribute boolean shiftKey;
  readonly attribute boolean altKey;
  readonly attribute boolean metaKey;

  readonly attribute short button;
  readonly attribute unsigned short buttons;

  readonly attribute EventTarget? relatedTarget;

  boolean getModifierState(DOMString keyArg);
};

screenX, 型: long, 読み取り専用

イベントが発生したスクリーン座標系の原点からの水平座標。

この属性の 未初期化値 は 0 でなければなりません。

screenY, 型: long, 読み取り専用

イベントが発生したスクリーン座標系の原点からの垂直座標。

この属性の 未初期化値 は 0 でなければなりません。

clientX, 型: long, 読み取り専用

イベントが発生したビューポートに対する水平座標。

この属性の 未初期化値 は 0 でなければなりません。

clientY, 型: long, 読み取り専用

イベントが発生したビューポートに対する垂直座標。

この属性の 未初期化値 は 0 でなければなりません。

layerX, 型: long, 読み取り専用

祖先要素のうち、 積み重ねコンテキストであり、positionedであるか、 積み重ねコンテキストを描画する際に positioned phase で描画する要素からの水平オフセット。

この属性の 未初期化値 は 0 でなければなりません。

layerY, 型: long, 読み取り専用

祖先要素のうち、 積み重ねコンテキストであり、positionedであるか、 積み重ねコンテキストを描画する際に positioned phase で描画する要素からの垂直オフセット。

この属性の 未初期化値 は 0 でなければなりません。

ctrlKey, 型: boolean, 読み取り専用

KeyboardEvent の ctrlKey 属性を参照。

この属性の 未初期化値 は false でなければなりません。

shiftKey, 型: boolean, 読み取り専用

KeyboardEvent の shiftKey 属性を参照。

この属性の 未初期化値 は false でなければなりません。

altKey, 型: boolean, 読み取り専用

KeyboardEvent の altKey 属性を参照。

この属性の 未初期化値 は false でなければなりません。

metaKey, 型: boolean, 読み取り専用

KeyboardEvent の metaKey 属性を参照。

この属性の 未初期化値 は false でなければなりません。

button, 型: short, 読み取り専用

マウスボタンの押下や解放によって発生するマウスイベントでは、button 属性で、どのポインタデバイスのボタンが状態変化したかを示す必要があります。

button 属性の値は以下の通りでなければなりません：

• 0：デバイスの主ボタン（一般的には左ボタン、または単一ボタンデバイスの場合は唯一のボタン。UIコントロールのアクティベートやテキスト選択に使用）または未初期化値。

• 1：補助ボタン（一般的には中央ボタン、マウスホイールと組み合わせることが多い）。

• 2：副ボタン（一般的には右ボタン、コンテキストメニュー表示に使用）。

• 3：X1（戻る）ボタン。

• 4：X2（進む）ボタン。

一部のポインティングデバイスはより多くのボタン状態を提供／シミュレートしており、2より大きい、または0より小さい値がそのようなボタンを表す場合があります。

button の値は、マウスボタンの押下／解放で発生していないイベントでは更新されません。 このような場合、値0を左ボタンと解釈せず、未初期化値として扱うよう注意してください。

mousedown や mouseup などのイベントに関連する デフォルト動作 は使用するマウスボタンに依存します。

この属性の 未初期化値 は 0 でなければなりません。

buttons, 型: unsigned short, 読み取り専用

すべてのマウスイベントで、buttons 属性は現在押されているマウスボタンの組み合わせをビットマスクで示す必要があります。

buttons 属性と button 属性は名前が似ていますが値の意味が大きく異なります。button 属性は mousedown / mouseup のイベントハンドラ中で妥当な値とされますが、buttons 属性は、どの信頼できる MouseEvent オブジェクトでもマウスボタンの状態を反映します（「現在どのボタンも押されていない」状態は値0で表現）。

buttons 属性の値は以下の通りでなければなりません：

• 0：現在どのボタンも押されていない場合。

• 1：デバイスの主ボタン（一般的には左ボタン、または単一ボタンデバイスの場合は唯一のボタン。UIコントロールのアクティベートやテキスト選択に使用）。

• 2：副ボタン（一般的には右ボタン、コンテキストメニュー表示など）、該当する場合。

• 4：補助ボタン（一般的には中央ボタン、マウスホイールと組み合わせることが多い）。

一部のポインティングデバイスはより多くのボタンを提供／シミュレートしており、そのようなボタンを表す場合は各ボタンごとに値を2倍（バイナリ系列 8、16、32 ... ）する必要があります。

任意のボタン値の合計は一意の値となるため、コンテンツ著者はビット演算を用いて現在押されているボタン数や種類を判定できます。例えば値3は左ボタンと右ボタンが両方押されていること、値5は左ボタンと中央ボタンが両方押されていることを示します。

mousedown や mouseup などのイベントに関連する デフォルト動作 は使用するマウスボタンに依存します。

この属性の 未初期化値 は 0 でなければなりません。

relatedTarget, 型: EventTarget, 読み取り専用, nullable

UIイベントの種類に応じて、二次的な EventTarget を識別するために使用します。

この属性の 未初期化値 は null でなければなりません。

getModifierState(keyArg)

本仕様で導入

キー値を使ってモディファイアの状態を問い合わせます。

モディファイアキーでかつそのモディファイアが有効なら true、そうでなければ false を返します。

DOMString keyArg

KeyboardEvent の getModifierState() メソッドの説明を参照してください。

3.4.1.2. MouseEventInit

dictionary MouseEventInit : EventModifierInit {
  long screenX = 0;
  long screenY = 0;
  long clientX = 0;
  long clientY = 0;

  short button = 0;
  unsigned short buttons = 0;
  EventTarget? relatedTarget = null;
};

screenX, 型: long, デフォルトは 0

screenX 属性（MouseEvent オブジェクト）のユーザー画面上のマウスポインタの水平方向の相対位置を初期化します。

イベントオブジェクトを指定したマウス位置に初期化しても、ユーザーのマウスポインタをその位置に移動してはなりません。

screenY, 型: long, デフォルトは 0

screenY 属性（MouseEvent オブジェクト）のユーザー画面上のマウスポインタの垂直方向の相対位置を初期化します。

イベントオブジェクトを指定したマウス位置に初期化しても、ユーザーのマウスポインタをその位置に移動してはなりません。

clientX, 型: long, デフォルトは 0

clientX 属性（MouseEvent オブジェクト）のユーザーのブラウザのクライアントウィンドウに対するマウスポインタの水平方向の位置を初期化します。

イベントオブジェクトを指定したマウス位置に初期化しても、ユーザーのマウスポインタをその位置に移動してはなりません。

clientY, 型: long, デフォルトは 0

clientY 属性（MouseEvent オブジェクト）のユーザーのブラウザのクライアントウィンドウに対するマウスポインタの垂直方向の位置を初期化します。

イベントオブジェクトを指定したマウス位置に初期化しても、ユーザーのマウスポインタをその位置に移動してはなりません。

button, 型: short, デフォルトは 0

button 属性（MouseEvent オブジェクト）をマウスのボタン状態（数値）で初期化します。

0は主マウスボタン、1は補助／中央ボタン、2は右ボタン。2より大きい値も可能ですが、本書では規定しません。

buttons, 型: unsigned short, デフォルトは 0

buttons 属性（MouseEvent オブジェクト）を、アクティブとみなすべきマウスボタン（1つ以上）の数値で初期化します。

buttons 属性はビットフィールドです。ビットフィールド値に対して1のマスク値がtrueの場合は主ボタン、2なら右ボタン、4なら補助／中央ボタンが押されていることを示します。

JavaScriptで右ボタン(2)と中央ボタン(4)が同時に押されている場合、buttons値は
{ buttons: 2 | 4 }
または
{ buttons: 6 }

relatedTarget, 型: EventTarget, nullable, デフォルトは null

relatedTarget は、マウスポインタが直前に離れた要素（mouseover や mouseenter イベントの場合）や、マウスポインタが入った要素（mouseout、mouseleave、focusout イベントの場合）に初期化する必要があります。他のイベントではこの値は割り当て不要（デフォルトは null）。

マウスイベント生成時、現在のクリック数を管理しなければなりません。これは、特定の時間内にポインティングデバイスのボタンが連続してクリックされた回数を示す非負整数です。カウントがリセットされる遅延は環境設定に依存します。

3.4.2. イベント修飾子初期化辞書

MouseEvent と KeyboardEvent インターフェイスは、キーボード修飾子属性のセットを共有し、追加の修飾子状態取得メカニズムをサポートしています。次の辞書は、MouseEvent および KeyboardEvent インターフェイスのキーボード修飾子属性や getModifierState() で問い合わせる追加修飾子状態を初期化するために利用できます。 この辞書を使ったイベント構築手順は MouseEvent constructors セクションで定義されています。

dictionary EventModifierInit : UIEventInit {
  boolean ctrlKey = false;
  boolean shiftKey = false;
  boolean altKey = false;
  boolean metaKey = false;

  boolean modifierAltGraph = false;
  boolean modifierCapsLock = false;
  boolean modifierFn = false;
  boolean modifierFnLock = false;
  boolean modifierHyper = false;
  boolean modifierNumLock = false;
  boolean modifierScrollLock = false;
  boolean modifierSuper = false;
  boolean modifierSymbol = false;
  boolean modifierSymbolLock = false;
};

ctrlKey, 型: boolean, デフォルトは false

ctrlKey 属性（MouseEvent または KeyboardEvent ）を Control 修飾キーが有効なら true、そうでなければ false に初期化します。

true の場合、イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Control を渡した場合は true を返すようにする必要があります。

shiftKey, 型: boolean, デフォルトは false

shiftKey 属性（MouseEvent または KeyboardEvent ）を Shift 修飾キーが有効なら true、そうでなければ false に初期化します。

true の場合、イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Shift を渡した場合は true を返すようにする必要があります。

altKey, 型: boolean, デフォルトは false

altKey 属性（MouseEvent または KeyboardEvent ）を Alt（オルタナティブ）や Option 修飾キーが有効なら true、そうでなければ false に初期化します。

true の場合、イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Alt を渡した場合は true を返すようにする必要があります。

metaKey, 型: boolean, デフォルトは false

metaKey 属性（MouseEvent または KeyboardEvent ）を Meta 修飾キーが有効なら true、そうでなければ false に初期化します。

true の場合、イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Meta を渡した場合は true を返すようにする必要があります。

modifierAltGraph, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に AltGraph を渡した場合は true を返すようにする必要があります。

modifierCapsLock, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に CapsLock を渡した場合は true を返すようにする必要があります。

modifierFn, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Fn を渡した場合は true を返すようにする必要があります。

modifierFnLock, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に FnLock を渡した場合は true を返すようにする必要があります。

modifierHyper, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Hyper を渡した場合は true を返すようにする必要があります。

modifierNumLock, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に NumLock を渡した場合は true を返すようにする必要があります。

modifierScrollLock, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に ScrollLock を渡した場合は true を返すようにする必要があります。

modifierSuper, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Super を渡した場合は true を返すようにする必要があります。

modifierSymbol, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に Symbol を渡した場合は true を返すようにする必要があります。

modifierSymbolLock, 型: boolean, デフォルトは false

イベントオブジェクトのキー修飾状態も初期化し、getModifierState() や getModifierState() に SymbolLock を渡した場合は true を返すようにする必要があります。

3.4.2.1. マウスイベントの構築

一般的に、Event インターフェイス、またはEvent インターフェイスから継承されたインターフェイスのコンストラクタが呼び出された場合、[DOM]で記述されている手順に従う必要があります。ただし、MouseEvent インターフェイスは、Event オブジェクトのキー修飾子（特に getModifierState() メソッドで問い合わせる内部状態）を初期化するための追加辞書メンバーを提供します。このセクションは、DOM4で定義される新しい MouseEvent オブジェクトの初期化手順に、これらのオプションの修飾子状態を補足します。

MouseEvent の構築、または下記アルゴリズムでこれらのオブジェクトから派生したオブジェクトを構築する場合、 すべての MouseEvent およびその派生オブジェクトは 内部キー修飾子状態 を持ち、キー修飾子名（修飾キー一覧表、[UIEvents-Key]参照）を利用して設定・取得できます。

以下の手順は、DOM4で定義されるイベント構築アルゴリズムを補足します：

• 構築されるEvent が MouseEvent オブジェクト、またはそれを継承したオブジェクトであり、 コンストラクタにEventModifierInit 引数が指定された場合、以下のサブ手順を実行します：

  • 各EventModifierInit 引数に対して、辞書メンバー名が"modifier"で始まる場合、キー修飾子名を、プレフィックス"modifier"を除いた辞書メンバー名とし、 Event オブジェクトの内部キー修飾子状態のうち、キー修飾子名に一致するものを対応する値で設定する。

3.4.3. MouseEventアルゴリズム

3.4.3.1. ネイティブOS要件

このセクションのアルゴリズムは、ネイティブプラットフォームOSが下記を提供することを前提とします：

• マウスが移動したときのイベント（ネイティブマウス移動の処理で扱う）

• マウスボタンが押されたときのイベント（ネイティブマウス押下の処理で扱う）

• マウスボタンが離されたときのイベント（ネイティブマウス解放の処理で扱う）

• マウスボタンの押下が「クリック」として解釈されるべき時を識別する手段（ネイティブマウスクリックの処理で扱う）

  • 例えば、フラグや独立したイベントとして

  • 独立した「クリック」イベントが発火される場合、ネイティブOSは対応する「マウスアップ」イベントの直後、他のマウス関連イベントを挟まずに発火する

• マウスクリックが「ダブルクリック」として解釈されるべき時を識別する手段（ネイティブマウスダブルクリックの処理で扱う）

これらのイベントでは、OSは以下の情報を提供できる必要があります：

• ネイティブOSデスクトップに対するx,yマウス座標

• UAのウィンドウビューポートに対するx,yマウス座標

• 現在押されているキーボード修飾キー

3.4.3.2. MouseEventのグローバル状態

3.4.3.2.1. ユーザーエージェントレベルの状態

UAは、ユーザーエージェント全体で共有される以下の値を管理しなければなりません。

マウスボタンの現在の状態を追跡する マウスボタン・ビットマスク。

3.4.3.2.2. ウィンドウレベルの状態

UAは、ウィンドウで共有される以下の値を管理しなければなりません。

直近でMouseEventを送信した Element を追跡する last mouse element（初期値は未定義）。

直近でMouseEventが送信された際のlast mouse DOM path（初期値は空）。これは last mouse element の祖先 Element のスナップショットを保持します。

3.4.3.3. MouseEventの内部状態

MouseEvent は、各種修飾キーの状態を追跡するための以下の内部フラグを持ちます：shiftフラグ、controlフラグ、altフラグ、altgraphフラグ、 metaフラグ。 これらはマウスイベント発生時に対応する修飾キーが押されていた場合に設定されます。

3.5. ホイールイベント

ホイールは1つ以上の空間軸で回転でき、ポインタデバイスに関連付けることができるデバイスです。座標系は環境設定によって異なります。

ユーザーの環境設定によっては、垂直スクロールがy軸回転、水平スクロールがx軸回転、ズームがz軸回転に対応している場合があります。

WheelEvent オブジェクトの deltaX, deltaY, deltaZ 属性は、それぞれの軸方向での測定値をピクセル・行・ページ単位で示します。報告される測定値は、実際のホイールデバイスの回転・移動を環境固有のアルゴリズムで適切な値と単位に変換した後のものです。

ユーザーの環境設定により、ホイールデバイスの回転・移動の実際を様々な方法で解釈できます。一般的なギザギザ型マウスホイールの1回の動きで162ピクセル分の測定値が出ることがあります（162は例で、実際の値はユーザーエージェントの画面サイズ等で変動します）。ユーザーが設定を変更してマウスホイールの速度を速めることもできます。さらに、マウスホイールのソフトウェアは加速度（ホイール回転が速いほど各測定値のdeltaが大きくなる）やサブピクセル回転測定にも対応できます。このため、著者はあるユーザーエージェントでの回転量がすべてのユーザーエージェントで同じdelta値になるとは限らないことに注意してください。

deltaX, deltaY, deltaZ属性の値の符号（正負）は、ホイールデバイスが同じ方向に動いている間は複数回のwheelイベント間で一貫していなければなりません。ユーザーエージェントがwheelイベントのデフォルトアクションとしてスクロールを行う場合、符号は右手系座標系に従って、X・Y・Z軸の正方向が文書の右端・下端・奥（ユーザーから遠い）方向になるべきです。

ユーザーエージェントやハードウェア構成によって、同じ物理的ホイール操作の解釈は異なります。例えば、トラックパッド端で上から下へ垂直スワイプすると、ページを下にスクロールする動作（deltaYが正）かページを上にパンする動作（deltaYが負）のいずれかになります。

ユーザーエージェントは最初のホイールイベントが発火したとき、ホイールイベントトランザクションを生成しなければなりません。これにより実装固有の一定時間以内の後続ホイールイベントを同じ要素にターゲットできます。ホイールイベントトランザクションは1つのユーザー操作に関連付けられた一連のホイールイベントのことです。ホイールイベントトランザクションは最初のグループホイールイベント発生時点の最上位イベントターゲットを関連付けなければなりません。

スクロール可能な要素上で始まった一連のホイールイベントが、後続のユーザー操作で子要素上に移動することもあります。

3.5.1. WheelEventインターフェース

この現行標準で導入

WheelEvent インターフェースはwheelイベントに関連する特有のコンテキスト情報を提供します。

インスタンス生成には、WheelEvent コンストラクタを使い、オプションでWheelEventInit辞書を渡します。

3.5.1.1. WheelEvent

[Exposed=Window]
interface WheelEvent : MouseEvent {
  constructor(DOMString type, optional WheelEventInit eventInitDict = {});
  // DeltaModeCode
  const unsigned long DOM_DELTA_PIXEL = 0x00;
  const unsigned long DOM_DELTA_LINE  = 0x01;
  const unsigned long DOM_DELTA_PAGE  = 0x02;

  readonly attribute double deltaX;
  readonly attribute double deltaY;
  readonly attribute double deltaZ;
  readonly attribute unsigned long deltaMode;
};

DOM_DELTA_PIXEL

deltaの測定単位はピクセルでなければなりません。これはほとんどのOSや実装設定で最も一般的です。

DOM_DELTA_LINE

deltaの測定単位はテキストの1行でなければなりません。多くのフォームコントロールでこれが使われます。

DOM_DELTA_PAGE

deltaの測定単位はページ（単一画面または区切られたページ）でなければなりません。

deltaX, 型 double, readonly

ユーザーエージェントでwheelイベントのデフォルトアクションがスクロールの場合、この値はx軸方向（ピクセル・行・ページ単位）のスクロール量（イベントがキャンセルされなかった場合）でなければなりません。そうでなければ、ホイールデバイスのx軸回転の環境固有測定値です。

この属性の未初期化値は0.0でなければなりません。

deltaY, 型 double, readonly

ユーザーエージェントでwheelイベントのデフォルトアクションがスクロールの場合、この値はy軸方向（ピクセル・行・ページ単位）のスクロール量（イベントがキャンセルされなかった場合）でなければなりません。そうでなければ、ホイールデバイスのy軸回転の環境固有測定値です。

この属性の未初期化値は0.0でなければなりません。

deltaZ, 型 double, readonly

ユーザーエージェントでwheelイベントのデフォルトアクションがスクロールの場合、この値はz軸方向（ピクセル・行・ページ単位）のスクロール量（イベントがキャンセルされなかった場合）でなければなりません。そうでなければ、ホイールデバイスのz軸回転の環境固有測定値です。

この属性の未初期化値は0.0でなければなりません。

deltaMode, 型 unsigned long, readonly

deltaMode属性はdelta値の測定単位を示します。デフォルト値はDOM_DELTA_PIXEL（ピクセル）です。

この属性は、delta値の測定単位を示すDOM_DELTA定数のいずれかで設定されなければなりません。正確な測定単位はデバイス・OS・アプリケーション構成によって異なります。

この属性の未初期化値は0でなければなりません。

3.5.1.2. WheelEventInit

dictionary WheelEventInit : MouseEventInit {
  double deltaX = 0.0;
  double deltaY = 0.0;
  double deltaZ = 0.0;
  unsigned long deltaMode = 0;
};

deltaX, 型 double, デフォルト0.0

deltaZ属性を参照。

deltaY, 型 double, デフォルト0.0

deltaZ属性を参照。

deltaZ, 型 double, デフォルト0.0

deltaZ 属性を初期化する。相対的な正の値（deltaXやdeltaYも）は右手系座標系によってX・Y・Z軸が文書の右端・下端・奥（ユーザーから遠い）方向になる。負の値は逆方向。

deltaMode, 型 unsigned long, デフォルト0

deltaMode 属性を0,1,2の定数で初期化する。これは回転によってスクロールされるピクセル（DOM_DELTA_PIXEL）、行（DOM_DELTA_LINE）、ページ（DOM_DELTA_PAGE）の量を表す。

3.5.2. ホイールイベント型

3.5.2.1. wheel

ユーザーエージェントは、マウスホイールがいずれかの軸で回転した時、または同等の入力デバイス（マウスボール、タブレット、タッチパッド等）が同じ動作をエミュレートした時、このイベントをディスパッチしなければなりません。プラットフォームや入力デバイスによっては、斜め方向のホイールdeltaが1回のwheelイベントの複数軸値として、または各軸ごとに別のwheelイベントとして配信されることがあります。

典型的なデフォルトアクションは、文書を指定量スクロール（または場合によってはズーム）することです。このイベントがキャンセルされた場合、実装は文書のスクロール・ズーム・その他現行標準で定めるデフォルト操作をしてはなりません。

一部のユーザーエージェントや入力デバイスでは、ホイールの回転速度がdelta値に影響し、速く回すほどdelta値が大きくなります。

3.5.2.2. ホイールイベントのキャンセル可否

wheelイベントでpreventDefaultを呼ぶことで、スクロールの防止や中断が可能です。最大限のスクロールパフォーマンスのため、ユーザーエージェントはスクロールに関連する各wheelイベントがキャンセルされるかどうか処理を待たない場合があります。その場合、cancelable属性がfalseのwheelイベントを生成し、preventDefaultではスクロールの防止や中断ができないことを示します。そうでなければcancelableはtrueになります。

特に、ユーザーエージェントは非パッシブリスナーがないことを検知した場合、キャンセル不可のwheelイベントのみ生成すべきです。

3.6. 入力イベント

入力イベントは、ユーザーの操作（例：編集可能領域でのキーボード入力、テキスト削除やフォーマットなど）によってDOMが更新されたとき（または更新される直前）に通知として送信されます。

3.6.1. InputEventインターフェース

3.6.1.1. InputEvent

DOM Level 3で導入

[Exposed=Window]
interface InputEvent : UIEvent {
  constructor(DOMString type, optional InputEventInit eventInitDict = {});
  readonly attribute USVString? data;
  readonly attribute boolean isComposing;
  readonly attribute DOMString inputType;
};

data, 型 USVString, readonly, nullable

dataは入力メソッドによって生成された文字の値を保持します。これは1つのUnicode文字または空でないUnicode文字列列である場合があります [Unicode]。文字は NFC 正規化形式で正規化されるべきです。詳細は [UAX15]参照。 この属性は空文字列を含む場合があります。

この属性の未初期化値はnullでなければなりません。

isComposing, 型 boolean, readonly

trueの場合、この入力イベントは合成セッション中（compositionstartイベント発生後、対応するcompositionendイベント発生前）に発生したことを示します。

この属性の未初期化値はfalseでなければなりません。

inputType, 型 DOMString, readonly

inputTypeにはイベントに関連する入力の種類を表す文字列が入ります。

この属性の有効値一覧は [Input-Events] 現行標準を参照。

この属性の未初期化値は空文字列 "" でなければなりません。

3.6.1.2. InputEventInit

dictionary InputEventInit : UIEventInit {
  DOMString? data = null;
  boolean isComposing = false;
  DOMString inputType = "";
};

data, 型 DOMString, nullable, デフォルトnull

InputEventオブジェクトのdata属性を初期化する。

isComposing, 型 boolean, デフォルトfalse

InputEventオブジェクトのisComposing属性を初期化する。

inputType, 型 DOMString, デフォルト""

InputEventオブジェクトのinputType属性を初期化する。

3.6.2. 入力イベント順序

この現行標準で定義される入力イベントは、互いに相対して一定の順序で発生しなければなりません。

3.6.3. 入力イベント型

3.6.3.1. beforeinput

ユーザーエージェントは、DOMが更新される直前にこのイベントをディスパッチしなければなりません。

3.6.3.2. input

ユーザーエージェントは、DOMが更新された直後にこのイベントをディスパッチしなければなりません。

3.7. キーボードイベント

キーボードイベントはデバイス依存であり、入力デバイスの機能やOSでのマッピングに依存します。詳細やキーボードイベントと組み合わせたコンポジションイベントの使用例についてはキーボードイベントとキー値を参照してください。文字生成デバイスによってはキーボードイベントが生成されない場合があります。

キーボードイベントはテキスト入力の一つのモダリティに過ぎません。編集用途の場合は、InputEvent をキーボードイベントの代替または補助として使用することも考慮してください。

3.7.1. KeyboardEventインターフェース

この現行標準で導入

KeyboardEvent インターフェースはキーボードデバイスに関連する特有のコンテキスト情報を提供します。各キーボードイベントは値でキーを参照します。キーボードイベントは通常フォーカスを持つ要素に向けて送られます。

KeyboardEvent インターフェースは、ctrlKey、 shiftKey、 altKey、 metaKey などの一般的な修飾キーに便利な属性を提供します。これらの属性は、それぞれgetModifierState()をControl, Shift, Alt, Metaで呼び出すのと同等です。

KeyboardEvent インターフェースのインスタンスを生成するには、KeyboardEvent コンストラクタにオプションでKeyboardEventInit 辞書を渡します。

3.7.1.1. KeyboardEvent

[Exposed=Window]
interface KeyboardEvent : UIEvent {
  constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
  // KeyLocationCode
  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;

  readonly attribute DOMString key;
  readonly attribute DOMString code;
  readonly attribute unsigned long location;

  readonly attribute boolean ctrlKey;
  readonly attribute boolean shiftKey;
  readonly attribute boolean altKey;
  readonly attribute boolean metaKey;

  readonly attribute boolean repeat;
  readonly attribute boolean isComposing;

  boolean getModifierState(DOMString keyArg);
};

DOM_KEY_LOCATION_STANDARD

キーの発動が左・右のバージョンの区別なく、かつ（NumLockキー以外は）テンキー由来でない場合、またはテンキー相当の仮想キー由来でない場合。

PC 101キーUSキーボードのQキー。
PC 101キーUSキーボードのNumLockキー。
PC 101キーUSキーボードのメインセクションにある1キー。

DOM_KEY_LOCATION_LEFT

キーが左側のキー位置から発動した場合（同じキーが複数位置にある場合）。

PC 101キーUSキーボードの左Controlキー。

DOM_KEY_LOCATION_RIGHT

キーが右側のキー位置から発動した場合（同じキーが複数位置にある場合）。

PC 101キーUSキーボードの右Shiftキー。

DOM_KEY_LOCATION_NUMPAD

キーがテンキーまたはテンキー相当の仮想キーから発動した場合（同じキーが複数位置にある場合）。なおNumLockキーは常にlocation にDOM_KEY_LOCATION_STANDARDで符号化すること。

PC 101キーUSキーボードのテンキー上の1キー。

key, 型 DOMString, readonly

keyは押されたキーに対応するkey属性値を保持します。

key属性は旧来のkeyCode属性とは無関係であり、値のセットも異なります。

この属性の未初期化値は空文字列""でなければなりません。

code, 型 DOMString, readonly

codeは物理的に押されたキーを識別する文字列を保持します。値は現在のキーボードレイアウトや修飾キー状態に影響されず、特定キーは常に同じ値となります。

この属性の未初期化値は空文字列""でなければなりません。

location, 型 unsigned long, readonly

location 属性はキーの論理的な位置を示します。

この属性はDOM_KEY_LOCATION定数のいずれかでデバイス上のキー位置を示すよう設定しなければなりません。

ユーザーエージェントがキーのリマップを許可する場合、リマップ後のキーに適切な値を設定しなければなりません。例えば"ControlLeft"キーが"KeyQ"キーにリマップされた場合はlocation属性をDOM_KEY_LOCATION_STANDARDに設定。逆に、"KeyQ"キーがControlキーのいずれかにリマップされた場合はlocation属性をDOM_KEY_LOCATION_LEFTまたはDOM_KEY_LOCATION_RIGHTに設定すること。

この属性の未初期化値は0でなければなりません。

ctrlKey, 型 boolean, readonly

trueの場合、Control（コントロール）修飾キーが有効だったことを示します。

この属性の未初期化値はfalseでなければなりません。

shiftKey, 型 boolean, readonly

trueの場合、Shift修飾キーが有効だったことを示します。

この属性の未初期化値はfalseでなければなりません。

altKey, 型 boolean, readonly

trueの場合、Alt（オルタナティブ、または"Option"）修飾キーが有効だったことを示します。

この属性の未初期化値はfalseでなければなりません。

metaKey, 型 boolean, readonly

trueの場合、Meta修飾キーが有効だったことを示します。

Macintoshシステムでは"Command"（"⌘"）修飾キーがこの修飾キーで表現されます。

この属性の未初期化値はfalseでなければなりません。

repeat, 型 boolean, readonly

trueの場合、キーが持続的に押されていることを示します。キーを押し続けることで、keydown、beforeinput、 inputがこの順序で、システム設定で定められた速度で繰り返し発火します。モバイルデバイスの長押し動作では、最初にrepeat属性値がtrueとなるイベントが長押しの指標となります。繰り返し発生するまでの押下時間は環境設定依存です。

この属性の未初期化値はfalseでなければなりません。

isComposing, 型 boolean, readonly

trueの場合、このキーイベントは合成セッション中（compositionstartイベント発生後、対応するcompositionendイベント発生前）に発生したことを示します。

この属性の未初期化値はfalseでなければなりません。

getModifierState(keyArg)

修飾キーの状態をキー値で問い合わせます。

修飾キーの場合は有効ならtrue、それ以外ならfalseを返します。

DOMString keyArg

修飾キー値。修飾キーはModifier Keys table（[UIEvents-Key]）で定義。

右左の修飾キーの区別をしたい場合は、キーボードイベントとlocationを併用して判別可能です。

3.7.1.2. KeyboardEventInit

dictionary KeyboardEventInit : EventModifierInit {
  DOMString key = "";
  DOMString code = "";
  unsigned long location = 0;
  boolean repeat = false;
  boolean isComposing = false;
};

key, 型 DOMString, デフォルト""

KeyboardEventオブジェクトのkey属性を初期化します。すべての修飾キー（シフト状態など）を考慮した後のキーの意味を表すUnicode文字列です。これはキーの最終的な有効値となります。キーが印刷可能文字でない場合は、[UIEvents-Key]で定義されたキー値のいずれかであるべきです。

code, 型 DOMString, デフォルト""

KeyboardEventオブジェクトのcode属性を初期化します。押されたキーを示すUnicode文字列で、キーボードレイアウト等の修飾状態を無視します。この値は[UIEvents-Code]で定義されたコード値のいずれかであるべきです。

location, 型 unsigned long, デフォルト0

KeyboardEventオブジェクトのlocation 属性を以下のいずれかの数値定数で初期化します：

• DOM_KEY_LOCATION_STANDARD （数値 0）

• DOM_KEY_LOCATION_LEFT （数値 1）

• DOM_KEY_LOCATION_RIGHT （数値 2）

• DOM_KEY_LOCATION_NUMPAD （数値 3）

repeat, 型 boolean, デフォルトfalse

KeyboardEventオブジェクトのrepeat属性を初期化します。現在のKeyboardEventが長押しされた単一キーによる繰り返しイベント列の一部であればtrue、そうでなければfalseとします。

isComposing, 型 boolean, デフォルトfalse

KeyboardEventオブジェクトのisComposing属性を初期化します。このイベントが合成シーケンス中に発生した場合はtrue、それ以外はfalseとします。

互換性維持のため、仮想キーボード（画面上のソフトウェアキーボード等）は物理キーがなくても通常の範囲のキーボードイベントを生成することが期待されます。

一部の実装やシステム構成では、IMEによってキーイベントや値が抑制される場合があります。

3.7.2. キーボードイベントのキー位置

location 属性は、左/右のShiftキーや物理矢印キーとテンキーの矢印キー（NumLockオフ時）など、同じキー値が異なる物理キーで生成される場合の判別に使えます。

次の表は、キーボード上で複数位置を持つ特殊キーの有効なlocation 値を示します：

この表に記載のないすべてのキーでは、location 属性は常にDOM_KEY_LOCATION_STANDARDに設定しなければなりません。

3.7.3. KeyboardEventアルゴリズム

3.7.3.1. KeyboardEventのグローバル状態

3.7.3.1.1. ユーザーエージェントレベルの状態

UAは、ユーザーエージェント全体で共有される以下の値を維持しなければなりません。

キー修飾状態（初期値は空）。システム上で利用可能な各修飾キーの現在の状態を追跡します。

3.7.4. キーボードイベント順序

この現行標準で定義されるキーボードイベントは、任意のキーごとに相互の順序で発生します：

キーが長押しされた場合、次のイベントが環境依存の頻度で繰り返し発生する場合があります：

通常、特定のキーに関連するデフォルトアクションはkeyupイベントがディスパッチされる前に完了します。これによりkeyupイベントの発火が若干遅れる場合があります（ただし知覚できる遅延ではありません）。

キーイベントのイベントターゲットは現在フォーカスを持ち、キーボード操作を処理している要素です。多くの場合HTMLのinput要素や編集可能なテキスト要素ですが、ホスト言語によって非テキスト目的（アクセラレータキーの起動や他の挙動のトリガーなど）にキーボード入力を受け付ける要素になる場合もあります。適切な要素がフォーカスされていない場合、イベントターゲットはHTMLのbody要素（存在すれば）、それ以外はroot要素です。

イベントターゲットはキーイベントごとに変わる場合があります。例えばTabキーのkeydownイベントは、同じキーストロークのkeyupイベントとは異なるイベントターゲットになる可能性があります。

3.7.5. キーボードイベント型

3.7.5.1. keydown

ユーザーエージェントは、キーが押下されたときこのイベントをディスパッチしなければなりません。keydownイベント型はデバイス依存であり、入力デバイスの機能やOSでのマッピングに依存します。このイベント型はキー割り当ての後に生成しなければなりません。また、同じキーに関連するbeforeinput、input、keyupイベントよりも前にディスパッチしなければなりません。

keydownイベントのデフォルトアクションはキーごとに異なります：

• キーが文字に対応している場合、デフォルトアクションはbeforeinputイベントの後にinputイベントをディスパッチすること。複数の文字（マクロやデッドキー連続など）に対応する場合は、文字ごとにbeforeinput／inputイベントをセットでディスパッチすること。

• キーがテキスト合成システムに関連している場合は、デフォルトアクションはそのシステムの起動としなければなりません。

• キーがTabの場合、デフォルトアクションは現在フォーカスされている要素（存在すれば）から新しいフォーカス要素へドキュメントフォーカスを移すこと（フォーカスイベント型参照）。

• キーがEnterまたは （スペース）で、現在のフォーカスが状態変更要素上の場合、デフォルトアクションはclickイベントおよびDOMActivateイベント（ユーザーエージェントが対応していれば）をディスパッチすること。

このイベントがキャンセルされた場合、関連イベント型はディスパッチされず、関連アクションも実行されてはなりません。

keydownおよびkeyupイベントは、文字値を生成するキーだけでなく、すべてのキー検出に伝統的に用いられます。

3.7.5.2. keyup

ユーザーエージェントは、キーが解放されたときこのイベントをディスパッチしなければなりません。keyupイベント型はデバイス依存であり、入力デバイスの機能やOSでのマッピングに依存します。このイベント型はキー割り当ての後に生成しなければなりません。また、同じキーに関連するkeydown、beforeinput、inputイベントの後にディスパッチしなければなりません。

keydownおよびkeyupイベントは、文字値を生成するキーだけでなく、すべてのキー検出に伝統的に用いられます。

3.8. 合成イベント

合成イベントは、キーボードイベント以外にも補助的または代替的な方法でテキスト入力を行う手段を提供します。これにより、キーボード上に一般的に存在しない文字も利用できます。例えば、合成イベントは標準USキーボードにない文字へのアクセント追加、多くのアジア言語の表意文字の構成要素からの合成、モバイルデバイスキーボード上の複数キー操作による単語選択、音声認識プロセッサによる音声コマンドからのテキスト変換などに使われます。合成イベントとキーボードイベントの組み合わせ例については§4 キーボードイベントとキー値を参照してください。

概念的には、合成セッションはcompositionstartイベントが1回、compositionupdateイベントが1回以上、compositionendイベントが1回の流れで構成されます。この間、data 属性の値が各「段階」ごとに保持されます。

注: 合成セッションが有効な間、入力デバイスとしてキーボードが使われていればキーボードイベントもDOMにディスパッチされます。詳細はcompositionstartイベントの解説およびIMEセクションのイベント順序を参照してください。

すべてのIMEシステムやデバイスが必要なデータをDOMに公開するわけではないので、アクティブな合成文字列（「読みウィンドウ」や「候補選択メニュー」など）がこのインターフェース経由で利用不可の場合、選択結果は空文字列で表現される場合があります。

3.8.1. CompositionEventインターフェース

この現行標準で導入

CompositionEvent インターフェースは合成イベントに関連する特有のコンテキスト情報を提供します。

インスタンス生成にはCompositionEvent コンストラクタにオプションでCompositionEventInit 辞書を渡します。

3.8.1.1. CompositionEvent

[Exposed=Window]
interface CompositionEvent : UIEvent {
  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
  readonly attribute USVString data;
};

data, 型 USVString, readonly

dataは入力メソッドで生成された文字値を保持します。これは1つのUnicode文字または空でないUnicode文字列列である場合があります [Unicode]。文字は NFC 正規化形式で正規化されるべきです。詳細は [UAX15]参照。この属性は空文字列の場合もあります。

この属性の未初期化値は空文字列""でなければなりません。

3.8.1.2. CompositionEventInit

dictionary CompositionEventInit : UIEventInit {
  DOMString data = "";
};

data, 型 DOMString, デフォルト""

CompositionEventオブジェクトのdata属性をIME合成で生成された文字値で初期化します。

3.8.2. 合成イベント順序

この現行標準で定義される合成イベントは以下の順序で発生しなければなりません：

3.8.3. 手書き認識システム

以下は、ペンタブレット等の手書き認識システムで「text」という文章を合成する場合の、合成イベントを用いた想定イベントシーケンスの例です。

3.8.4. 合成イベントのキャンセル

keydownイベントがキャンセルされた場合、そのkeydownに起因して発火するはずだった合成イベントはディスパッチすべきではありません：

最初のcompositionstartイベントがキャンセルされた場合、テキスト合成セッションは終了すべきです。セッションが終了するか否かに関わらず、compositionendイベントは必ず送信されなければなりません。

3.8.5. 合成中のキーイベント

合成セッション中は、keydownおよびkeyupイベントは引き続き送信され、これらのイベントはisComposing属性がtrueでなければなりません。

3.8.6. 合成中の入力イベント

合成セッション中は、compositionupdateはbeforeinputの後、inputイベントの前にディスパッチされなければなりません。

ほとんどのIMEは合成セッション中の更新キャンセルをサポートしていません。

beforeinput およびinputイベントは、合成に伴うDOM更新時にcompositionupdateイベントとともに送信されます。compositionendイベントにはDOM更新が伴わないため、そのタイミングではbeforeinputおよびinputイベントを送信すべきではありません。