Office アドインにカスタム キーボード ショートカットを追加する
キーの組み合わせとも呼ばれるキーボード ショートカットを使用すると、アドインのユーザーがより効率的に作業できるようになります。 また、キーボード ショートカットを使用すると、マウスに代わる機能を提供することで、障穏のあるユーザー向けのアドインのアクセシビリティも向上します。
重要
キーボード ショートカットは現在、Excel でのみサポートされており、これらのプラットフォームとビルドでのみサポートされています。
- Excel on the web
- Excel on Windows: バージョン 2102 (ビルド 13801.20632) 以降
- Excel on Mac: バージョン 16.48 以降
注:
キーボード ショートカットは、次の要件セットをサポートするプラットフォームでのみ機能します。 要件セットとその使用方法の詳細については、「 Office アプリケーションと API の要件を指定する」を参照してください。
- SharedRuntime 1.1
- アドインを使用してユーザーがキーボード ショートカットをカスタマイズできる場合にも必要です: KeyboardShortcuts 1.1
注:
キーボード ショートカットが既に有効になっているアドインの作業バージョンから開始するには、サンプル の Excel キーボード ショートカットを複製して実行します。 独自のアドインにキーボード ショートカットを追加する準備ができたら、この記事に進んでください。
アドインにキーボード ショートカットを追加するには、3 つの手順があります。
- アドインのマニフェストを構成します。
- ショートカット JSON ファイルを作成または編集 して、アクションとそのキーボード ショートカットを定義します。
- Office.actions.associate API の 1 つ以上のランタイム呼び出しを追加して、各アクションに関数をマップします。
マニフェストを構成する
マニフェストに対して行う小さな変更は 2 つあります。 1 つは、アドインで共有ランタイムを使用できるようにすることです。もう 1 つは、キーボード ショートカットを定義した JSON 形式のファイルを指す方法です。
共有ランタイムを使用するようにアドインを構成する
カスタム キーボード ショートカットを追加するには、アドインで 共有ランタイムを使用する必要があります。 詳細については、「 共有ランタイムを使用するようにアドインを構成する」を参照してください。
マッピング ファイルをマニフェストにリンクする
マニフェスト内の <VersionOverrides> 要素の直下 (内部ではない) に、ExtendedOverrides 要素を追加します。
Url
属性を、後の手順で作成するプロジェクト内の JSON ファイルの完全な URL に設定します。
...
</VersionOverrides>
<ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>
ショートカット JSON ファイルを作成または編集する
プロジェクトに JSON ファイルを作成します。 ファイルのパスが、ExtendedOverrides 要素のUrl
属性に指定した場所と一致していることを確認します。 このファイルには、キーボード ショートカットと、それらが呼び出すアクションが記述されます。
JSON ファイル内には、2 つの配列があります。 actions 配列には、呼び出すアクションを定義するオブジェクトが含まれます。ショートカット配列には、キーの組み合わせをアクションにマップするオブジェクトが含まれます。 次に例を示します。
{ "actions": [ { "id": "SHOWTASKPANE", "type": "ExecuteFunction", "name": "Show task pane for add-in" }, { "id": "HIDETASKPANE", "type": "ExecuteFunction", "name": "Hide task pane for add-in" } ], "shortcuts": [ { "action": "SHOWTASKPANE", "key": { "default": "Ctrl+Alt+Up" } }, { "action": "HIDETASKPANE", "key": { "default": "Ctrl+Alt+Down" } } ] }
JSON オブジェクトの詳細については、「 アクション オブジェクトの構築 」および「 ショートカット オブジェクトの構築」を参照してください。 ショートカット JSON の完全なスキーマは 、extended-manifest.schema.jsonにあります。
注:
この記事では、"Ctrl" の代わりに "CONTROL" を使用できます。
アクションは、作成した関数にマップされます。 この例では、"SHOWTASKPANE" を Office.addin.showAsTaskpane メソッドを呼び出す関数にマップし、"HIDETASKPANE" を Office.addin.hide メソッドを呼び出す関数にマップします。
アクションの関数へのマッピングを作成する
プロジェクトで、HTML ページによって読み込まれた JavaScript ファイルを <FunctionFile> 要素で開きます。
JavaScript ファイルで、 Office.actions.associate API を使用して、JSON ファイルで指定した各アクションを JavaScript 関数にマップします。 ファイルに次の JavaScript を追加します。 コードについては、次の点に注意してください。
- 最初のパラメーターは、JSON ファイルからのアクションの 1 つです。
- 2 番目のパラメーターは、ユーザーが JSON ファイル内のアクションにマップされているキーの組み合わせを押したときに実行される関数です。
Office.actions.associate("SHOWTASKPANE", showTaskPane); Office.actions.associate("HIDETASKPANE", hideTaskPane); function showTaskPane() { return Office.addin.showAsTaskpane() .then(() => { console.log("Task pane is visible."); }) .catch((error) => { console.log(error.code); }); } function hideTaskPane() { return Office.addin.hide() .then(() => { console.log("Task pane is hidden."); }) .catch((error) => { console.log(error.code); }) }
前の手順に従うと、アドインで Ctrl + Alt + Up キーと Ctrl + Alt +Down キーを押して、作業ウィンドウの表示を切り替えることができます。 同じ動作が、GitHub の Office アドイン サンプル リポジトリの Excel キーボード ショートカット サンプルに示されています。
詳細と制限
アクション オブジェクトを構築する
shortcuts.jsonの actions
配列内のオブジェクトを指定する場合は、次のガイドラインを使用します。
- プロパティ名
id
とname
は必須です。 -
id
プロパティは、キーボード ショートカットを使用して呼び出すアクションを一意に識別するために使用されます。 -
name
プロパティは、アクションを説明するわかりやすい文字列である必要があります。 文字 A - Z、a - z、0 - 9、および句読点 "-"、"_"、および "+" の組み合わせである必要があります。 - プロパティは省略可能です。 現在、
ExecuteFunction
型のみがサポートされています。
次に例を示します。
"actions": [
{
"id": "SHOWTASKPANE",
"type": "ExecuteFunction",
"name": "Show task pane for add-in"
},
{
"id": "HIDETASKPANE",
"type": "ExecuteFunction",
"name": "Hide task pane for add-in"
}
]
ショートカット JSON の完全なスキーマは 、extended-manifest.schema.jsonにあります。
ショートカット オブジェクトを構築する
shortcuts.jsonの shortcuts
配列内のオブジェクトを指定する場合は、次のガイドラインを使用します。
- プロパティ名
action
、key
、およびdefault
が必要です。 -
action
プロパティの値は文字列であり、アクション オブジェクトのid
プロパティのいずれかに一致する必要があります。 -
default
プロパティには、文字 A - Z、-z、0 - 9、および句読点 "-"、"_"、および "+" の任意の組み合わせを指定できます。 (規則により、これらのプロパティでは小文字は使用されません)。 -
default
プロパティには、少なくとも 1 つの修飾子キー (Alt、Ctrl、Shift) の名前と、他の 1 つのキーのみを含む必要があります。 - Shift キーを唯一の修飾子キーとして使用することはできません。 Shift キーを Alt キーまたは Ctrl キーで結合します。
- Mac の場合は、Command 修飾子キーもサポートされています。
- Mac の場合、Alt キーは Option キーにマップされます。 Windows の場合、コマンドは Ctrl キーにマップされます。
- 2 つの文字が標準キーボードの同じ物理キーにリンクされている場合、それらは
default
プロパティ内のシノニムです。たとえば、Alt + a と Alt + A は同じショートカットであるため、"-" と "_" は同じ物理キーであるため、Ctrl + + と Ctrl +_ になります。 - "+" 文字は、その両側のキーが同時に押されることを示します。
次に例を示します。
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "Ctrl+Alt+Up"
}
},
{
"action": "HIDETASKPANE",
"key": {
"default": "Ctrl+Alt+Down"
}
}
]
ショートカット JSON の完全なスキーマは 、extended-manifest.schema.jsonにあります。
注:
キーヒントは、連続キー ショートカットとも呼ばれ、塗りつぶしの色 Alt + H、H を選択するための Excel ショートカットなど、Office アドインではサポートされていません。
他のアドインでキーの組み合わせを使用しないようにする
Office で既に使用されているキーボード ショートカットは多数あります。 既に使用されているアドインのキーボード ショートカットは登録しないでください。 ただし、既存のキーボード ショートカットをオーバーライドしたり、同じキーボード ショートカットを登録している複数のアドイン間の競合を処理したりする必要がある場合があります。
競合が発生した場合、ユーザーが競合するキーボード ショートカットを初めて使用しようとすると、ダイアログ ボックスが表示されます。 このダイアログに表示されるアドイン オプションのテキストは、shortcuts.json
ファイル内のアクション オブジェクトの name
プロパティから取得されることに注意してください。
ユーザーは、キーボード ショートカットが実行するアクションを選択できます。 選択を行った後、同じショートカットを今後使用するために設定が保存されます。 ショートカット設定は、プラットフォームごとに、ユーザーごとに保存されます。 ユーザーが自分の設定を変更する場合は、検索ボックス [通知] から [Office アドインのショートカット設定をリセットする] コマンドを呼び出すことができます。 コマンドを呼び出すと、ユーザーのすべてのアドイン ショートカット設定がクリアされ、次回競合するショートカットを使用しようとしたときに、ユーザーに再度競合ダイアログ ボックスが表示されます。
最適なユーザー エクスペリエンスを得るには、Excel との競合を最小限に抑え、これらの優れたプラクティスを使用することをお勧めします。
- Ctrl + Shift + Alt + x というパターンのキーボード ショートカットのみを使用 します。x は他のキーです。
- さらにキーボード ショートカットが必要な場合は、 Excel キーボード ショートカットの一覧を確認し、アドインで使用しないようにします。
- キーボード フォーカスがアドイン UI 内にある場合、 Ctrl + Space キー と Ctrl + Shift + F10 は機能しません。これらは、基本的なアクセシビリティ ショートカットであるためです。
- Windows または Mac コンピューターで、検索メニューで [Office アドインのショートカット設定をリセットする] コマンドを使用できない場合、ユーザーはコンテキスト メニューからリボンをカスタマイズすることで、リボンにコマンドを手動で追加できます。
プラットフォームごとのキーボード ショートカットのカスタマイズ
プラットフォーム固有のショートカットをカスタマイズできます。
windows
、mac
、web
の各プラットフォームのショートカットをカスタマイズする shortcuts
オブジェクトの例を次に示します。 ショートカットごとに default
ショートカット キーが必要であることに注意してください。
次の例では、 default
キーは、指定されていないプラットフォームのフォールバック キーです。 指定されていない唯一のプラットフォームは Windows であるため、 default
キーは Windows にのみ適用されます。
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "Ctrl+Alt+Up",
"mac": "Command+Shift+Up",
"web": "Ctrl+Alt+1",
}
},
{
"action": "HIDETASKPANE",
"key": {
"default": "Ctrl+Alt+Down",
"mac": "Command+Shift+Down",
"web": "Ctrl+Alt+2"
}
}
]
キーボード ショートカット JSON をローカライズする
アドインで複数のロケールがサポートされている場合は、アクション オブジェクトの name
プロパティをローカライズする必要があります。 また、アドインでサポートされているロケールのいずれかが異なるアルファベットや書き込みシステムを持ち、そのためキーボードが異なる場合は、ショートカットもローカライズする必要があります。 JSON のキーボード ショートカットをローカライズする方法については、「 拡張オーバーライドをローカライズする」を参照してください。
オーバーライドできないブラウザー ショートカット
Web でカスタム キーボード ショートカットを使用する場合、ブラウザーで使用される一部のキーボード ショートカットをアドインでオーバーライドすることはできません。この一覧は進行中の作業です。 オーバーライドできない他の組み合わせが見つからない場合は、このページの下部にあるフィードバック ツールを使用してお知らせください。
- Ctrl + N
- Ctrl + Shift + N
- Ctrl + T
- Ctrl + Shift + T
- Ctrl + W
- Ctrl + PgUp/PgDn
特定のユーザーのカスタム キーボード ショートカットを有効にする
アドインを使用すると、ユーザーはアドインのアクションを別のキーボードの組み合わせに再割り当てできます。
注:
このセクションで説明する API には、 KeyboardShortcuts 1.1 要件セットが必要です。
Office.actions.replaceShortcuts メソッドを使用して、ユーザーのカスタム キーボードの組み合わせをアドイン アクションに割り当てます。 メソッドは {[actionId:string]: string|null}
型のパラメーターを受け取ります。ここで、 actionId
はアドインの拡張マニフェスト JSON で定義する必要があるアクション ID のサブセットです。 値は、ユーザーが推奨するキーの組み合わせです。 値を null
することもできます。これにより、その actionId
のカスタマイズが削除され、アドインの拡張マニフェスト JSON で定義されている既定のキーボードの組み合わせに戻ります。
ユーザーが Office にログインしている場合、カスタムの組み合わせはプラットフォームごとのユーザーのローミング設定に保存されます。 現在、匿名ユーザーのショートカットのカスタマイズはサポートされていません。
const userCustomShortcuts = {
SHOWTASKPANE:"CTRL+SHIFT+1",
HIDETASKPANE:"CTRL+SHIFT+2"
};
Office.actions.replaceShortcuts(userCustomShortcuts)
.then(function () {
console.log("Successfully registered.");
})
.catch(function (ex) {
if (ex.code == "InvalidOperation") {
console.log("ActionId does not exist or shortcut combination is invalid.");
}
});
ユーザーに既に使用されているショートカットを確認するには、 Office.actions.getShortcuts メソッドを 呼び出します。 このメソッドは、 [actionId:string]:string|null}
型のオブジェクトを返します。値は、指定したアクションを呼び出すためにユーザーが使用する必要がある現在のキーボードの組み合わせを表します。 値は、次の 3 つの異なるソースから取得できます。
- ショートカットと競合していて、ユーザーがそのキーボードの組み合わせに対して別のアクション (ネイティブまたは別のアドイン) を使用することを選択した場合、返される値は
null
されます。これは、ショートカットがオーバーライドされ、ユーザーがそのアドイン アクションを呼び出すために現在使用できるキーボードの組み合わせがないためです。 - Office.actions.replaceShortcuts メソッドを使用してショートカットがカスタマイズされている場合、返される値はカスタマイズされたキーボードの組み合わせになります。
- ショートカットがオーバーライドまたはカスタマイズされていない場合は、アドインの拡張マニフェスト JSON から値が返されます。
次に例を示します。
Office.actions.getShortcuts()
.then(function (userShortcuts) {
for (const action in userShortcuts) {
let shortcut = userShortcuts[action];
console.log(action + ": " + shortcut);
}
});
「他の アドインでキーの組み合わせを使用しないようにする」で説明されているように、ショートカットの競合を回避することをお勧めします。 1 つ以上のキーの組み合わせが既に使用されているかどうかを検出するには、それらを文字列の配列として Office.actions.areShortcutsInUse メソッドに渡します。 メソッドは、 {shortcut: string, inUse: boolean}
型のオブジェクトの配列の形式で既に使用されているキーの組み合わせを含むレポートを返します。
shortcut
プロパティは、"Ctrl + Shift + 1" などのキーの組み合わせです。 組み合わせが既に別のアクションに登録されている場合、 inUse
プロパティは true
に設定されます。 たとえば、「 [{shortcut: "CTRL+SHIFT+1", inUse: true}, {shortcut: "CTRL+SHIFT+2", inUse: false}]
」のように入力します。 次のコード スニペットは例です。
const shortcuts = ["CTRL+SHIFT+1", "CTRL+SHIFT+2"];
Office.actions.areShortcutsInUse(shortcuts)
.then(function (inUseArray) {
const availableShortcuts = inUseArray.filter(function (shortcut) { return !shortcut.inUse; });
console.log(availableShortcuts);
const usedShortcuts = inUseArray.filter(function (shortcut) { return shortcut.inUse; });
console.log(usedShortcuts);
});
次の手順
- Excel キーボード ショートカットのサンプル アドインを参照してください。
- 「マニフェストの拡張オーバーライドを処理する」で 拡張オーバーライドの操作の概要を取得します。
Office Add-ins