Office アドインにカスタムキーボードショートカットを追加する

[アーティクル]
07/03/2024

キーの組み合わせとも呼ばれるキーボードショートカットを使用すると、アドインのユーザーがより効率的に作業できるようになります。また、キーボードショートカットを使用すると、マウスに代わる機能を提供することで、障穏のあるユーザー向けのアドインのアクセシビリティも向上します。

重要

キーボードショートカットは現在、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 プロパティから取得されることに注意してください。

1 つのショートカットに対して 2 つの異なるアクションを持つ競合モーダル。

ユーザーは、キーボードショートカットが実行するアクションを選択できます。選択を行った後、同じショートカットを今後使用するために設定が保存されます。ショートカット設定は、プラットフォームごとに、ユーザーごとに保存されます。ユーザーが自分の設定を変更する場合は、検索ボックス [通知] から [Office アドインのショートカット設定をリセットする] コマンドを呼び出すことができます。コマンドを呼び出すと、ユーザーのすべてのアドインショートカット設定がクリアされ、次回競合するショートカットを使用しようとしたときに、ユーザーに再度競合ダイアログボックスが表示されます。

Office アドインのショートカット設定のリセットアクションが表示されている Excel の [通知] 検索ボックス。

最適なユーザーエクスペリエンスを得るには、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 アドインにカスタムキーボードショートカットを追加する

マニフェストを構成する

共有ランタイムを使用するようにアドインを構成する

マッピングファイルをマニフェストにリンクする

ショートカット JSON ファイルを作成または編集する

アクションの関数へのマッピングを作成する

詳細と制限

アクションオブジェクトを構築する

ショートカットオブジェクトを構築する

他のアドインでキーの組み合わせを使用しないようにする

プラットフォームごとのキーボードショートカットのカスタマイズ

キーボードショートカット JSON をローカライズする

オーバーライドできないブラウザーショートカット

特定のユーザーのカスタムキーボードショートカットを有効にする

次の手順

フィードバック

その他のリソース

次の方法で共有

Office アドインにカスタム キーボード ショートカットを追加する

マニフェストを構成する

共有ランタイムを使用するようにアドインを構成する

マッピング ファイルをマニフェストにリンクする

ショートカット JSON ファイルを作成または編集する

アクションの関数へのマッピングを作成する

詳細と制限

アクション オブジェクトを構築する

ショートカット オブジェクトを構築する

他のアドインでキーの組み合わせを使用しないようにする

プラットフォームごとのキーボード ショートカットのカスタマイズ

キーボード ショートカット JSON をローカライズする

オーバーライドできないブラウザー ショートカット

特定のユーザーのカスタム キーボード ショートカットを有効にする

次の手順

フィードバック

その他のリソース

Office アドインにカスタムキーボードショートカットを追加する

マッピングファイルをマニフェストにリンクする

アクションオブジェクトを構築する

ショートカットオブジェクトを構築する

プラットフォームごとのキーボードショートカットのカスタマイズ

キーボードショートカット JSON をローカライズする

オーバーライドできないブラウザーショートカット

特定のユーザーのカスタムキーボードショートカットを有効にする