HTML5資料室 » KeyboardJS

KeyboardJS

Last modified by mtakeuchi on 2013/09/11, 17:55

資料目次

HTML5 APIs
- IndexedDB
- Canvas
  - Android 標準ブラウザの canvas 利用時のメモリリーク
UI ライブラリ
- OpenSeadragon
テスト支援
ドキュメント
- JSDoc3
コード品質ツール
- JSLint/JSHint
バリデータ
- jQuery Validate
キー入力支援
- KeyboardJS
テストダブル
- Sinon.JS
ハイブリッドアプリケーション
- PhoneGap
継続的インテグレーション
- QUnit, Karma, JSHint, JSDoc3 を組み合わせて Jenkins 上で CI を行う

KeyboardJSとは
主な機能
基本的な使い方
その他の操作
日本語ロケールへの対応

KeyboardJSとは

単一のキー入力や、キーの組み合わせによる入力(Ctrl+S 等)に対して、操作の割り当てを容易に実装することができるライブラリです。

主な機能

キー名やキーコンボを指定してハンドラを登録し、押された指定された条件に一致するとハンドラが実行される
キーボードロケールの追加・削除
キーの追加・削除
マクロの追加・削除
アクティブ(現在操作されたキー)なキー名の取得
KeyboardJSを有効または無効の切り替え
キーコンボ文字列をキー文字列を持つ配列に変換
キー文字列を持つ配列をキーコンボ文字列に変換

基本的な使い方

KeyboardJS.on()でキーコンボに対してバインドするハンドラを登録します。

KeyboardJS.on(String keyCombo, Function onDownCallback, Function onUpCallback)

パラメータ名	型	説明
keyCombo	String	キーコンボ(キーコンボの詳細はこちらを参照)
onDownCallback(ev, keys, keycombo)	Function	キーダウン時に実行されるメソッドパラメータ ev: イベントオブジェクト keys: 現在押されているキー名の配列(KeyboardJS.activeKeys()と同じ値が返ってくる) keycombo: キーコンボ文字列
onUpCallback(ev, keys, keycombo)	Function	キーアップ時に実行されるメソッド ev: イベントオブジェクト keys: 現在押されているキー名の配列(KeyboardJS.activeKeys()と同じ値が返ってくる) keycombo: キーコンボ文字列
onUpCallback(ev, keys, keycombo)	Function	キーダウン時に実行されるメソッド

サンプルコード

CTRLキーとFキーが一緒に押された場合の処理を登録しています。

KeyboardJS.on("ctrl + f", function(ev, key, keycombo) {
   // ev: KeyboardEvent
   // key: ["ctrl", "f"]
   // keycombo: "ctrl + f"
}, function(ev, key, keycombo) {
   // ev: KeyboardEvent
   // key: ["ctrl", "f"]
   // keycombo: "ctrl + f"
});

キーコンボとは

押されるキーの条件文です。

パターンは以下の通りです。
キーコンボの条件指定に使用する文字列は、

> (大なり)
+ (プラス)
, (カンマ)

があります。

例:

条件	意味
a	aのキーが押されたか
a , b	aまたはbのキーが押されたか
a + b	aとbのキーが同時に押されか
a > b	aが押された状態でのbキーを押されたか
a + b, c + d	aとbのキーが同時におされた、またはcとdのキーが同時に押されたか
a + b > c + d	aとbのキーが同時におしながら、cとdのキーを同時におされたか

その他の操作

アクティブなキー名を取得する

KeyboardJS.activeKeys()

Ctrl+Aが押された場合

'{rootElement} keyup': function(context) {
console.log(KeyboardJS.activeKeys()); // ["ctrl", "a"]
}

※ キーが押されているときにこのメソッドを実行する必要があります。(直近でアクティブだったキー名を返す訳ではない)

キーコンボに割り当てたハンドラを除去する

KeyboardJS.clear(String keyCombo)

   KeyboardJS.on("a", function() {
        ...
   }, function() {
        ...
   });

   KeyboardJS.clear("a"); // KeyboardJS.on("a")のハンドラが動作しなくなる。

キーに紐づくハンドラを全て除去する

KeyboardJS.clear.key(String key)

   KeyboardJS.on("shift + a", function() {
        ...
   }, function() {
        ...
   });

   KeyboardJS.on("ctrl + a", function() { //
       ...
   }, function() {
        ...
   });

   KeyboardJS.clear.key("a"); // shift + a, ctrl + aのハンドラが動作しなくなる

ロケールを登録する

KeyboardJS.locale.register(String localeName, Object localeDefinition)

  var jpLocale = {
        map: { "29": ["muhenkan", "無変換"] },
        macros: [ ['shift + ^', ["tilde", "チルダ", "~"]] ]
   };
   KeyboardJS.locale.register("jp", jpLocale); // jpとしてロケールを定義する

ロケール定義の書き方

{
"map": {
   "3": ["cancel"],
   "8": ["backspace"],
   "9": ["tab"],

    ...
  },
"macros": [
    ['shift + `', ["tilde", "~"]],
    ['shift + 1', ["exclamation", "exclamationpoint", "!"]],
    ['shift + 2', ["at", "@"]],
    ['shift + 3', ["number", "#"]],
    ['shift + 4', ["dollar", "dollars", "dollarsign", "$"]],

    ...
  ]
};

mapとmacrosをキーにもつオブジェクトで定義します。
mapには、キーにキーコード、値にキー名が列挙された配列を持つオブジェクトを指定します。
macrosには、キーコンボとキー名の配列を持つ配列を指定します。

ロケールを変更する

KeyboardJS.locale(String localeName)

  var jpLocale = {
        map: { "29": ["muhenkan", "無変換"] },
        macros: [ ['shift + ^', ["tilde", "チルダ", "~"]] ]
   };
   KeyboardJS.locale.register("jp", jpLocale);

   KeyboardJS.clear.key("jp"); // ロケールがusからjpに変更される

マクロを登録する

KeyboardJS.macro(String keyCombo, Array keyNames)

   KeyboardJS.macro('ctrl + v', ['paste', '貼り付け']);

   KeyboardJS.on("ctrl + v", function(ev, key, keycombo) { // CTRLキーとVキーが同時に押されると実行される
       // ev: KeyboardEvent
       // key: ["ctrl", "v", "paste", "貼り付け"]
       // keycombo: "ctrl + v"
  }, function(ev, key, keycombo) {
       // ev: KeyboardEvent
       // key: ["ctrl", "v", "paste", "貼り付け"]
       // keycombo: "ctrl + v"
  });

マクロを除去する

KeyboardJS.macro.remove(String keyCombo)

   KeyboardJS.macro.remove('ctrl + v');

   KeyboardJS.on("ctrl + v", function(ev, key, keycombo) { // CTRLキーとVキーが同時押されても動作しなくなる
       ...
   }, function(ev, key, keycombo) {
        ...
   });

キーコードに紐づくキー名を取得する

KeyboardJS.key.name(Number keyCode)

KeyboardJS.key.name(42); // ["printscreen"]

KeyboardJS.key.name(100); // ["numfour", "num4"]

※ このメソッドは、ロケール定義のmapに設定されている値からキー名を返します。

キー名に紐づくキーコードを取得する

KeyboardJS.key.code(Number keyCode)

KeyboardJS.key.code("ctrl"); // 17

KeyboardJS.key.name("a"); // 65

KeyboardJS.key.name("$"); // false

KeyboardJS.key.name("shift + 1"); // false

※ このメソッドは、ロケール定義のmapに設定されている値からキーコードを返します。

文字列を解析してキーコンボを持つ配列に変換する

KeyboardJS.combo.parse(String keyCombo)

KeyboardJS.key.code("shift + 1"); // [ [ ["shift", "1"] ] ]

KeyboardJS.combo.parse('a, b'); // [ [ ["a"] ], [ ["b"] ] ]

KeyboardJS.combo.parse('a + b > c + d'); // [ [ ["a", "b"], ["c", "d"] ] ]

配列の値を解析してキーコンボ文字列に変換する

KeyboardJS.combo.stringify(Array keyComboArray)

KeyboardJS.combo.stringify([ [["a"]], [["b"]] ]); // "a b"

KeyboardJS.combo.stringify([ [["a"], ["b"]] ]); // "a > b"

KeyboardJS.combo.stringify([ [ ["a", "b"], ["c", "d"] ] ]); // "a + b > c + d"

KeyboardJSの動作を有効化または無効化する

KeyboardJS.enable()

KeyboardJS.on()に登録したハンドラの動作を有効にします。
デフォルトはこの状態です。

KeyboardJS.disable()

KeyboardJS.on()に登録したハンドラの動作を無効にします。

日本語ロケールへの対応

KeyboardJSのデフォルトロケールはus(英語キーボード)になっており、日本語のロケールは用意されておりません。
そのため、日本語のロケールをユーザが定義する必要があります。

以下のコードは、日本語(109キーボード)に対応するためのロケール定義の一例です。
この定義をKeyboardJS.setLocale()に指定して、日本語キーボード用のロケールを追加します。