Vue 3 composables and components for HyperBind
npm install @hyperbind-lib/vueVue 3アプリケーションでキーボードショートカットを簡単に実装するためのComposablesとコンポーネントライブラリ。
``bash`
npm install @hyperbind-lib/vue
前提条件:
- Vue 3.0.0以上
- @hyperbind-lib/core(自動的にインストールされます)
`vue
Ctrl+S で保存
`
#### useKeybind(keyCombo: string, callback: () => void)
シンプルなキーバインドを登録するComposable。コンポーネントのマウント時に登録し、アンマウント時に自動的に解除します。
`vue`
引数:
- keyCombo: キーの組み合わせ(例: "ctrl+s", "cmd+k", "f1")callback
- : キー押下時に実行される関数
#### usePresetKeybind(presetId: string, callback: () => void)
プリセットキーバインドを使用するComposable。プリセットIDを指定するだけで、キーの組み合わせとpreventDefault設定が自動的に適用されます。
`vue`
引数:
- presetId: プリセットキーバインドのID(例: "common-help", "search-show")callback
- : キー押下時に実行される関数
利用可能なプリセット:
- common-help: F1 - ヘルプ表示common-palette
- : F2 - パレットを表示search-show
- : F3 - 検索common-reference
- : F4 - 項目の参照@hyperbind-lib/core
- その他多数(のALL_PRESET_KEYBINDSを参照)
#### useInputKeybind(options: UseInputKeybindOptions)
入力フィールド専用のキーバインドComposable。特定の入力要素にフォーカスがある場合のみ実行されます。
`vue
`
オプション:
- elementRef: 対象となる入力要素への参照keyCombo
- : キーの組み合わせ(デフォルト: "Enter")onTrigger
- : キー押下時に実行される関数enabled
- : キーバインドを有効にするか(デフォルト: true)preventDefault
- : デフォルトのブラウザ動作を防ぐか(デフォルト: true)
#### useCustomKeybinds(options?: UseCustomKeybindsOptions)
カスタムキーバインドを管理するComposable。ユーザーが定義したキーバインドの追加、削除、更新、有効/無効の切り替えを提供します。localStorageへの自動保存も行います。
`vue
@click="
addKeybind({
label: '新しいアクション',
keyCombo: 'ctrl+k',
enabled: true,
preventDefault: true,
})
"
>
キーバインド追加
:on-toggle="toggleKeybind"
:on-toggle-prevent-default="togglePreventDefault"
:on-remove="removeKeybind"
:on-update="updateKeybind"
/>
`
戻り値:
- keybinds: キーバインドの配列(ref)addKeybind
- : キーバインドを追加する関数removeKeybind
- : キーバインドを削除する関数updateKeybind
- : キーバインドを更新する関数toggleKeybind
- : キーバインドの有効/無効を切り替える関数togglePreventDefault
- : preventDefaultの有効/無効を切り替える関数
オプション:
- storageKey: localStorageのキー名(デフォルト: "hyperbind_custom_keybinds")onTrigger
- : キーバインドが実行されたときに呼ばれる関数
#### useModalKeybind(options: UseModalKeybindOptions)
モーダルやダイアログの開閉をキーバインドで制御するComposable。同じキーで開閉を切り替えるトグル動作を提供します。
`vue
`
オプション:
- keyCombo: キーの組み合わせ(例: "f1", "escape")onOpen
- : モーダルを開くときに実行される関数onClose
- : モーダルを閉じるときに実行される関数(省略可能)isOpen
- : モーダルが現在開いているかどうか(デフォルト: false)preventDefault
- : デフォルトのブラウザ動作を防ぐか(デフォルト: true)
#### useGlobalKeybindToggle()
すべてのキーバインドをグローバルにON/OFFするComposable。
`vue
⚠️ すべてのキーバインドが無効化されています
`
戻り値:
- isEnabled: キーバインドが有効かどうか(ref)enable
- : キーバインドを有効化する関数disable
- : キーバインドを無効化する関数toggle
- : キーバインドの有効/無効を切り替える関数
#### useDisableKeyBindsWhileMounted()
コンポーネントがマウントされている間、すべてのキーバインドを無効化するComposable。モーダルやフォームで、キーバインドの干渉を防ぎたい場合に使用します。
`vue
`
#### useDisableCustomKeybindsWhileMounted()
コンポーネントがマウントされている間、カスタムキーバインドのみを無効化するComposable。タブ移動などの標準的なキーバインドは有効のままです。モーダルやダイアログで、カスタムキーバインドの干渉を防ぎたい場合に使用します。
`vue
`
####
フォーム内の入力フィールド間を自動的にナビゲートするコンポーネント。Tab/Shift+TabとEnterキーで、指定された入力フィールド間を循環的に移動できます。IME入力中の動作も適切に処理します。
`vue
`
プロパティ:
- inputRefs: フォーム内の入力要素への参照の配列
動作:
- Tabキー: 次のフィールドへ移動Shift+Tab
- キー: 前のフィールドへ移動Enter
- キー: 次のフィールドへ移動(テキストエリアの場合は無効)
####
キーボード入力を記録するコンポーネント。ユーザーがキーを押すと、その組み合わせ("ctrl+s"など)を記録します。予約キー(ブラウザやOSで使用されるキー)の使用時には警告を表示します。
`vue
{{ warning }}
`
プロパティ:
- modelValue: 現在のキーの組み合わせ(v-model)showWarning
- : 警告メッセージを表示するかどうか(デフォルト: false)@warning
- : 警告状態が変化したときに呼ばれるイベント
####
カスタムキーバインドの一覧を表示・編集するコンポーネント。各キーバインドに対して以下の操作が可能です:
- 有効/無効の切り替え
- ラベルとキーの組み合わせの編集
- preventDefaultの切り替え
- 削除
予約キーを使用している場合は、視覚的に警告を表示します。
`vue
:on-toggle="toggleKeybind"
:on-toggle-prevent-default="togglePreventDefault"
:on-remove="removeKeybind"
:on-update="updateKeybind"
/>
`
プロパティ:
- keybinds: 表示するキーバインドの配列onToggle
- : キーバインドの有効/無効を切り替えるときに呼ばれる関数onTogglePreventDefault
- : preventDefaultの有効/無効を切り替えるときに呼ばれる関数onRemove
- : キーバインドを削除するときに呼ばれる関数onUpdate
- : キーバインドを更新するときに呼ばれる関数
####
キーバインド機能付きの入力フィールドコンポーネント。標準のHTML input要素に、カスタムキーバインド機能を追加したコンポーネントです。通常のinputプロパティ(placeholder、value、@inputなど)もすべて使用可能です。
`vue
v-model="query"
trigger-key="cmd+enter"
@key-press="() => console.log('検索実行:', query)"
/>
`
プロパティ:
- すべての標準的な要素のプロパティtriggerKey
- : キーの組み合わせ(デフォルト: "Enter")@keyPress
- : キーが押されたときに実行されるイベントkeybindEnabled
- : キーバインドを有効にするか(デフォルト: true)preventDefault
- : デフォルトのブラウザ動作を防ぐか(デフォルト: true)
#### isReservedKey(keyCombo: string): boolean
指定されたキーの組み合わせが予約キーかどうかを判定します。
`typescript
import { isReservedKey } from "@hyperbind-lib/vue";
if (isReservedKey("ctrl+s")) {
console.log("このキーは予約されています");
}
`
#### getReservedKeyWarning(keyCombo: string): string | null
指定されたキーの組み合わせが予約キーの場合、警告メッセージを返します。
`typescript
import { getReservedKeyWarning } from "@hyperbind-lib/vue";
const warning = getReservedKeyWarning("ctrl+s");
if (warning) {
console.warn(warning); // "Ctrl+S はブラウザの保存機能で使用されています"
}
`
`vue`
`vue`
`vue
`
`vue
`
`vue
ヘルプ
`
`vue
@click="
addKeybind({
label: 'カスタムアクション',
keyCombo: 'ctrl+k',
enabled: true,
preventDefault: true,
})
"
>
キーバインド追加
:on-toggle="toggleKeybind"
:on-remove="removeKeybind"
:on-update="updateKeybind"
/>
`
`vue
⚠️ すべてのキーバインドが無効化されています
`
Mac と Windows/Linux のキーボードの違いを自動的に吸収します:
- Mac の Cmd キー(⌘)と Windows/Linux の Ctrl キーを統一的に扱えます"ctrl+s"
- または "cmd+s" のどちらで登録しても、両方のプラットフォームで動作します
`vue`
ブラウザやOSで使用されるキーは予約キーとして扱われ、使用時に警告が表示されます:
- Ctrl+S: ブラウザの保存機能Ctrl+R
- , F5: ページのリロードCtrl+F
- : ブラウザの検索機能Ctrl+P
- : 印刷
- その他多数
予約キーを使用する場合は、preventDefault: true`を設定してブラウザのデフォルト動作を防ぐことを推奨します。
MIT