From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- files/ja/web/api/keyboardevent/index.html | 343 ++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 files/ja/web/api/keyboardevent/index.html (limited to 'files/ja/web/api/keyboardevent/index.html') diff --git a/files/ja/web/api/keyboardevent/index.html b/files/ja/web/api/keyboardevent/index.html new file mode 100644 index 0000000000..a9174b98e6 --- /dev/null +++ b/files/ja/web/api/keyboardevent/index.html @@ -0,0 +1,343 @@ +--- +title: KeyboardEvent +slug: Web/API/KeyboardEvent +tags: + - API + - DOM + - Event + - Input + - Interface + - Key Events + - Keyboard Events + - KeyboardEvent + - MakeBrowserAgnostic + - Reference + - UI Events + - keyboard + - user input + - イベント +translation_of: Web/API/KeyboardEvent +--- +
{{APIRef("DOM Events")}}
+ +

KeyboardEvent オブジェクトは、キーボードによるユーザーの操作を示します。個々のイベントがユーザーとキーとの間の単一の操作 (または修飾キーとの組み合わせ) を表します。イベントの種類 ({{event('keydown')}}, {{event('keypress')}}, {{event('keyup')}}) はキーボード操作が発生した種類を識別します。

+ +
メモ: KeyboardEvent は、単にユーザーがキーボードのキーで行った操作が何であるかを低水準で示すものであり、その操作のその場面における意味は持ちません。テキストの入力を処理したい場合は、代わりに {{event("input")}} イベントを使用してください。ユーザーが他の種類のテキスト入力、例えば、タブレット端末やタブレット機器による手書き入力システムなどを使用している場合は、キーボードイベントが発生することはありません。
+ +

{{InheritanceDiagram}}

+ +

コンストラクター

+ +
+
{{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}
+
KeyboardEvent オブジェクトを生成します。
+
+ +

定数

+ +

KeyboardEvent インターフェースは、以下の定数を定義しています。

+ +

Keyboard locations

+ +

以下の定数は、キーイベントがキーボードのどの部分から発信されるかを識別します。これらは、KeyboardEvent.DOM_KEY_LOCATION_STANDARD などとしてアクセスされます。

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
キーボードの場所の識別子
定数値説明
DOM_KEY_LOCATION_STANDARD0x00 +

イベントによって記述されたキーは、キーボードの特定の領域にあることが特定されず、テンキー上にはなく(NumLock キーでない限り)、キーボードの左右に重複しているキーについては、何らかの理由で、そのキーは、その場所に関連付けられていないことになります。

+ +

例としては、標準的な PC 101 US キーボードの英数字キー、NumLock キー、スペースバーなどがあります。

+
DOM_KEY_LOCATION_LEFT0x01 +

キーは、キーボード上の複数の位置に存在してもよいものであり、この例では、キーボードの左側にある。

+ +

例としては、左の Ctrl キー、Macintosh キーボードの左の Command キー、左の Shift キーなどがあります。

+
DOM_KEY_LOCATION_RIGHT0x02 +

キーは、キーボード上の複数の位置に存在してもよいものであり、この場合、キーボードの右側に位置している。

+ +

例としては、右の Shift キーや右の Alt キー (Mac キーボードの Option) などがあります。

+
DOM_KEY_LOCATION_NUMPAD0x03 +

キーはテンキー上に配置されているか、またはキーの発生源となる場所が複数ある場合はテンキーに関連付けられた仮想キーとなります。NumLock キーはこのグループには該当せず、常に DOM_KEY_LOCATION_STANDARD の位置でエンコードされています。

+ +

例としては、テンキーパッドの数字、キーパッドの Enter キー、キーパッドの小数点などがあります。

+
+ +
+
+ +

プロパティ

+ +

このインターフェイスでは、親に相当する {{domxref("UIEvent")}} と {{domxref("Event")}} の両者からもプロパティを継承しています。

+ +
+
{{domxref("KeyboardEvent.altKey")}} {{Readonlyinline}}
+
そのキーイベントが発生した際に Alt (OS X の場合は Option または ⌥) キーが押されていれば {{jsxref("Boolean")}} true を返します。
+
+ +
+
{{domxref("KeyboardEvent.code")}} {{Readonlyinline}}
+
そのイベントが表すキーについて、キーのコード値を {{domxref("DOMString")}} で返します。 +
警告: これはユーザーのキーボード配列を無視しますので、ユーザーが QWERTY キーボード配列の "Y" の位置のキー (ホーム行の上の行の中ほど) を押すと、ユーザーが QWERTZ キーボード (ユーザーが "Z" だと思っており、その他のプロパティも "Z" を示している) や Dvorak キーボード配列 (ユーザーは "F" だと思っている) を使用していても、常に "KeyY" を返します。
+
+
+ +
+
{{domxref("KeyboardEvent.ctrlKey")}} {{Readonlyinline}}
+
そのキーイベントが発生した際に Ctrl キーが押されていれば {{jsxref("Boolean")}}  true を返します。
+
{{domxref("KeyboardEvent.isComposing")}} {{Readonlyinline}}
+
そのイベントが compositionstart と compositionend の間に発生したものであれば {{jsxref("Boolean")}} true を返します。
+
{{domxref("KeyboardEvent.key")}} {{Readonlyinline}}
+
イベントが表すキーのキー値を表す {{domxref("DOMString")}} を返します。
+
{{domxref("KeyboardEvent.locale")}} {{Readonlyinline}}
+
キーボードが設定されているロケールを示すロケール文字列を {{domxref("DOMString")}} で返します。ブラウザやデバイスがキーボードのロケールを知らない場合は空文字列となります。 +
メモ: このプロパティは入力データのロケールを表すことはありません。例えば、ユーザーが使用するキーボードレイアウトと入力テキストとで言語が異なる場合があります。
+
+
{{domxref("KeyboardEvent.location")}}{{Readonlyinline}}
+
キーボードなどの入力デバイス上のキーの位置を表す {{jsxref("Number")}} を返します。位置を特定する定数の一覧は、上記の {{anch("Keyboard locations")}} の中にあります。
+
{{domxref("KeyboardEvent.metaKey")}} {{Readonlyinline}}
+
{{jsxref("Boolean")}} を返し、そのキーイベントが発生した際に Meta キー（Mac キーボードは ⌘ Command キー、 Windows キーボードは Windows キー ⊞ ）が押されていれば true を返します。
+
{{domxref("KeyboardEvent.repeat")}} {{Readonlyinline}}
+
{{jsxref("Boolean")}} を返し、そのキーが自動的に繰り返し押下されていた場合に true を返します。
+
{{domxref("KeyboardEvent.shiftKey")}} {{Readonlyinline}}
+
{{jsxref("Boolean")}} を返し、そのキーイベントが発生した際に Shift キーが押されていれば true を返します。
+
+ +

メソッド

+ +

このインターフェイスでは、親に相当する {{domxref("UIEvent")}} と {{domxref("Event")}} の両者からもメソッドを継承しています。

+ +
+
{{domxref("KeyboardEvent.getModifierState()")}}
+
そのイベントが発生した際に修飾キー (Alt / Shift / Ctrl / Meta) が押されていたかどうかを表す{{jsxref("Boolean")}} を返します。
+
+ +

廃止されたメソッド

+ +
+
{{domxref("KeyboardEvent.initKeyEvent()")}} {{deprecated_inline}}
+
KeyboardEvent オブジェクトを初期化します。これは Firefox でのみ実装されていたもので、Firefox でもサポートされていないため、代わりに {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} コンストラクタを使用する必要があります。
+
{{domxref("KeyboardEvent.initKeyboardEvent()")}} {{deprecated_inline}}
+
KeyboardEvent オブジェクトを初期化します。これは現在では非推奨です。代わりに {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} コンストラクタを使用する必要があります。
+
+ +

廃止されたプロパティ

+ +
+
{{domxref("KeyboardEvent.char")}} {{Non-standard_inline}}{{Deprecated_inline}}{{Readonlyinline}}
+
キーの文字値を表す {{domxref("DOMString")}} を返します。キーが印刷可能な文字に対応している場合、この値はその文字を含む空でない Unicode 文字列となります。キーが印刷可能な表現を持たない場合は、これは空の文字列です。 +
注意: キーが複数の文字を挿入するマクロとして使用されている場合、この属性の値は最初の文字だけでなく文字列全体となります。
+
+
{{domxref("KeyboardEvent.charCode")}} {{Deprecated_inline}}{{Readonlyinline}}
+
キーの Unicode 参照番号を表す {{jsxref("Number")}} を返します。この属性は、keypress イベントでのみ使用されます。char 属性が複数の文字を含むキーの場合、これはその属性の最初の文字の Unicode 値となります。Firefox 26 では、これは印刷可能な文字のコードを返します。 +
警告: この属性は非推奨です。利用可能な場合は、代わりに {{domxref("KeyboardEvent.key")}} を使用する必要があります。
+
+
{{domxref("KeyboardEvent.keyCode")}} {{deprecated_inline}}{{Readonlyinline}}
+
押されたキーの変更されていない値を示す、システムや実装に依存した数値コードを表す {{jsxref("Number")}} を返します。 +
警告: この属性は非推奨です。利用可能な場合は、代わりに {{domxref("KeyboardEvent.key")}} を使用する必要があります。
+
+
{{domxref("KeyboardEvent.keyIdentifier")}} {{Non-standard_inline}}{{deprecated_inline}}{{Readonlyinline}}
+
このプロパティは非標準であり、{{domxref("KeyboardEvent.key")}} を支持して非推奨とされています。これは古いバージョンの DOM Level 3 Events の一部でした。
+
{{domxref("KeyboardEvent.keyLocation")}} {{Non-standard_inline}}{{deprecated_inline}}{{Readonlyinline}}
+
これは {{domxref("KeyboardEvent.location")}} の非標準の非推奨エイリアスです。これは古いバージョンの DOM Level 3 Events の一部でした。
+
{{domxref("KeyboardEvent.which")}} {{deprecated_inline}} {{Readonlyinline}}
+
押されたキーの変更されていない値を識別するシステムおよび実装依存の数値コードを表す {{jsxref("Number")}} を返します。これは通常 keyCode と同じです。 +
警告: この属性は非推奨です。利用可能な場合は、代わりに {{domxref("KeyboardEvent.key")}} を使用する必要があります。
+
+
+ +

イベント

+ +

以下のイベントは、KeyboardEvent 型に基づいています。これらのイベントは、{{domxref("Element")}}、{{domxref("Document")}}、および {{domxref("Window")}} を含む {{domxref("GlobalEventHandlers")}} を実装している任意のオブジェクトに配信することができます。以下のリストでは、各イベントは、そのイベントの Document ハンドラのドキュメントにリンクしています。

+ +
+
{{domxref("Document.keydown_event", "keydown")}}
+
キーが押されました。
+
{{domxref("Document.keyup_event", "keyup")}}
+
キーが離されました。
+
+ +

廃止されたイベント

+ +
+
{{domxref("Document.keypress_event", "keypress")}} {{obsolete_inline}}
+
通常は文字値を生成するキーが押されました。このイベントはデバイス依存度が高く、時代遅れのものです。使用すべきではありません。
+
+ +

使用上の注意

+ +

イベントには keydown / keypress / keyup の 3 種類があります。 Gecko ではほとんどのキーにおいて、以下のようにキーイベントが連続して発生します。

+ +
    +
  1. そのキーが最初に押された時点で keydown イベントが発生します。
    2. +
  2. そのキーが修飾キーでなかった場合、 keypress イベントが発生します。
    3. +
  3. ユーザがキーから指を離した時点で keyup イベントが発生します。
    4. +
+ +

特殊な場合

+ +

Caps Lock や Num Lock、 Scroll Lock などのキーは LED 表示も切り替わります。このようなキーについて、 Windows と Linux では keydown と keyup イベントのみが発生します。

+ +
+

Linux の Firefox 12 以前では keypress イベントも発生していました。

+
+ +

しかし Mac OS X のイベントモデルに関する制約から、Mac OS X の Caps Lock は keydown イベントのみが発生します。 (2007 年モデル以前の) ノート型では Num Lock もサポートされていましたが、今日の Mac OS X では外部キーボードにおいても Num Lock に対応していません。 Num Lock キーがある古い MacBook 上では、Num Lock キーによってイベントは何も発生しません。また、 F14 キーが接続されている外部キーボードであれば、 Gecko は Scroll Lock に対応しています。古い特定のバージョンの Firefox では、このキーによって keypress イベントが発生していました。この矛盾する挙動は {{bug(602812)}} で修正されました。

+ +

自動リピートの扱い

+ +

キーが押されたままになると自動リピートが始まります。これによって以下のようにイベントが連続して発生します。

+ +
    +
  1. keydown
    2. +
  2. keypress
    3. +
  3. keydown
    4. +
  4. keypress
    5. +
  5. <<ユーザがキーから指を離すまで繰り返し>>
    6. +
  6. keyup
    7. +
+ +

この流れは DOM Level 3 仕様書に定義されているものです。しかし、これには以下のような注意点があります。

+ +

Ubuntu 9.4 など一部の GTK 環境における自動リピート

+ +

GTK を用いた環境の中には、自動リピート時にネイティブの key-up イベントが発生するものがあります。このため、キーが連続して押されているのか自動リピートなのかを Gecko 側から認識することはできません。そのようなプラットフォームでの自動リピート時では、以下のようにキーイベントが連続して発生します。

+ +
    +
  1. keydown
    2. +
  2. keypress
    3. +
  3. keyup
    4. +
  4. keydown
    5. +
  5. keypress
    6. +
  6. keyup
    7. +
  7. <<ユーザがキーから指を離すまで繰り返し>>
    8. +
  8. keyup
    9. +
+ +

こういった環境では残念ながら、自動リピートなのか連続して押されているのかをウェブコンテンツ側から区別することはできません。

+ +

Gecko 5.0 以前の自動リピートの扱い

+ +

Gecko 5.0 {{geckoRelease('5.0')}} 以前では、プラットフォーム間でキーボードのイベントハンドリングに差異が生じていました。

+ +
+
Windows
+
自動リピートの挙動に関して Gecko 4.0 とそれ以降で変化はありません。
+
Mac
+
最初に keydown イベントが発生した後、 keyup イベントが発生するまでは keypress イベントのみが発生します。断続的に keydown イベントが発生することはありません。
+
Linux
+
イベントの挙動はプラットフォームによって異なります。ネイティブのイベントモデルによって、 Windows のような挙動を示したり、 Mac のような挙動を示すものがあります。
+
+ +

メモ: 手動でイベントを発生させても、関連する既定のアクションは生じません。例えば、手動でキーイベントを発生させても、その文字がテキストとして入力されることはありません。このような UI イベントの挙動は、セキュリティを意識して設計されています。この設計により、ブラウザーとやり取りするユーザー操作をスクリプトが模倣できないようにしています。

+ +

例

+ +
<!DOCTYPE html>
+<html>
+<head>
+<script>
+'use strict';
+
+document.addEventListener('keydown', (event) => {
+  const keyName = event.key;
+
+  if (keyName === 'Control') {
+    // do not alert when only Control key is pressed.
+    return;
+  }
+
+  if (event.ctrlKey) {
+    // Even though event.key is not 'Control' (e.g., 'a' is pressed),
+    // event.ctrlKey may be true if Ctrl key is pressed at the same time.
+    alert(`Combination of ctrlKey + ${keyName}`);
+  } else {
+    alert(`Key pressed ${keyName}`);
+  }
+}, false);
+
+document.addEventListener('keyup', (event) => {
+  const keyName = event.key;
+
+  // As the user releases the Ctrl key, the key is no longer active,
+  // so event.ctrlKey is false.
+  if (keyName === 'Control') {
+    alert('Control key was released');
+  }
+}, false);
+
+</script>
+</head>
+
+<body>
+</body>
+</html>
+
+ +

仕様書

+ + + + + + + + + + + + + + + + +
仕様書状態備考
{{SpecName('DOM3 Events', '#interface-keyboardevent', 'KeyboardEvent')}}{{Spec2('DOM3 Events')}}初回定義
+ +

KeyboardEvent インターフェイスの草案は数多く提案されてきました。まず最初は DOM Events Level 2 でしたが意見がまとまらず破棄され、続いて DOM Events Level 3 が提案されました。これにより、非標準な初期化メソッドが実装されてしまいました (Gecko では DOM Events Level 2 の初期に定義されていた {{domxref("KeyboardEvent.initKeyEvent()")}} が、他のブラウザでは DOM Events Level 3 の初期に定義されていた {{domxref("KeyboardEvent.initKeyboardEvent()")}} です)。しかし両者のメソッドは、モダンなコンストラクターである {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} で置き換えられています。

+ +

ブラウザーの対応

+ + + +

{{Compat("api.KeyboardEvent")}}

+ +

互換性のメモ

+ + + +

関連情報

+ + -- cgit v1.2.3-54-g00ecf