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

[アーティクル]
12/05/2024

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

アドインにキーボードショートカットを追加するには、3 つの手順があります。

アドインのマニフェストを構成します。
ショートカット JSON ファイルを作成または編集して、アクションとそのキーボードショートカットを定義します。
Office.actions.associate API を使用して、カスタムアクションを関数にマップします。

前提条件

キーボードショートカットは現在、次のプラットフォームと Excel とWordのビルドでのみサポートされています。

Office on the web

注:

キーボードショートカット機能は現在、Web 上のWordにロールアウトされています。この時点で web 上のWordで機能をテストすると、アドインの作業ウィンドウ内からアクティブ化されている場合、ショートカットが機能しない可能性があります。機能が完全にサポートされているタイミングを確認するには、キーボードショートカット要件セットを定期的にチェックすることをお勧めします。
Windows での Office
- Excel: バージョン 2102 (ビルド 13801.20632) 以降
- Word: バージョン 2408 (ビルド 17928.20114) 以降
Office on Mac
- Excel: バージョン 16.55 (21111400) 以降
- Word: バージョン 16.88 (24081116) 以降

また、キーボードショートカットは、次の要件セットをサポートするプラットフォームでのみ機能します。要件セットとその使用方法については、「 Office アプリケーションと API の要件を指定する」を参照してください。

SharedRuntime 1.1
KeyboardShortcuts 1.1 (アドインがキーボードショートカットをカスタマイズするオプションをユーザーに提供する場合に必要)

ヒント

キーボードショートカットが既に構成されているアドインの作業バージョンから開始するには、「 Office アドインアクションにキーボードショートカットを使用する」サンプルを複製して実行します。独自のアドインにキーボードショートカットを追加する準備ができたら、この記事に進んでください。

マニフェストを構成する

マニフェストに対して行う小さな変更は 2 つあります。 1 つは、アドインで共有ランタイムを使用できるようにすることです。もう 1 つは、キーボードショートカットを定義した JSON 形式のファイルを指す方法です。

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

カスタムキーボードショートカットを追加するには、アドインで共有ランタイムを使用する必要があります。詳細については、「共有ランタイムを使用するようにアドインを構成する」を参照してください。

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

マニフェスト内の <VersionOverrides> 要素の直下 (内部ではない) に、ExtendedOverrides 要素を追加します。 Url属性を、後の手順で作成するプロジェクト内の JSON ファイルの完全な URL に設定します。

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>

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

カスタムキーボードショートカットは JSON ファイルで定義されます。このファイルには、キーボードショートカットと、ユーザーが呼び出すアクションが記述されています。 JSON ファイルの完全なスキーマは、extended-manifest.schema.jsonにあります。

アドインプロジェクトで JSON ファイルを作成します。ファイルのパスが、ExtendedOverrides 要素のUrl属性に指定した場所と一致していることを確認します。
以下のマークアップをファイルに追加します。コードについては、次の点に注意してください。
- "actions" 配列には、呼び出すアクションを定義するオブジェクトが含まれています。 "actions.id" プロパティと "actions.name" プロパティが必要です。
- "actions.id" プロパティは、キーボードショートカットを使用して呼び出すアクションを一意に識別します。
- "actions.name" プロパティは、キーボードショートカットのアクションを記述する必要があります。指定した説明は、複数のアドイン間または Microsoft 365 との間にショートカットの競合がある場合にユーザーに表示されるダイアログに表示されます。 Office では、説明の末尾にアドインの名前をかっこで囲んで追加します。キーボードショートカットとの競合の処理方法の詳細については、「他のアドインでキーの組み合わせを使用しないようにする」を参照してください。
- "type" プロパティは省略可能です。現時点では、"ExecuteFunction" 型のみがサポートされています。
- 指定したアクションは、後の手順で作成した関数にマップされます。この例では、後で "ShowTaskpane" を、 Office.addin.showAsTaskpane メソッドを呼び出す関数と "HideTaskpane" を、 Office.addin.hide メソッドを呼び出す関数にマップします。
- "ショートカット" 配列には、キーの組み合わせをアクションにマップするオブジェクトが含まれています。 "shortcuts.action"、"shortcuts.key"、および "shortcuts.key.default" プロパティが必要です。
- "shortcuts.action" プロパティの値は、該当するアクションオブジェクトの "actions.id" プロパティと一致している必要があります。
- プラットフォーム固有のショートカットをカスタマイズできます。この例では、"shortcuts" オブジェクトは、"windows"、"mac"、"web" の各プラットフォームのショートカットをカスタマイズします。各ショートカットの既定のショートカットキーを定義する必要があります。これは、特定のプラットフォームにキーの組み合わせが指定されていない場合にフォールバックキーとして使用されます。
ヒント

カスタムキーの組み合わせを作成する方法のガイダンスについては、「カスタムキーの組み合わせのガイドライン」を参照してください。
```
{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "Show task pane"
        },
        {
            "id": "HideTaskpane",
            "type": "ExecuteFunction",
            "name": "Hide task pane"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "Ctrl+Alt+Up",
                "mac": "Command+Shift+Up",
                "web": "Ctrl+Alt+1",
                "windows": "Ctrl+Alt+Up"
            }
        },
        {
            "action": "HideTaskpane",
            "key": {
                "default": "Ctrl+Alt+Down",
                "mac": "Command+Shift+Down",
                "web": "Ctrl+Alt+2",
                "windows": "Ctrl+Alt+Up"
            }
        }
    ]
}
```

カスタムアクションを関数にマップする

プロジェクトで、HTML ページによって読み込まれた JavaScript ファイルを <FunctionFile> 要素で開きます。
JavaScript ファイルで、 Office.actions.associate API を使用して、JSON ファイルで指定した各アクションを JavaScript 関数にマップします。ファイルに次の JavaScript を追加します。コードについては、次の点に注意してください。
- 最初のパラメーターは、JSON ファイルからのアクションの 1 つです。
- 2 番目のパラメーターは、ユーザーが JSON ファイル内のアクションにマップされているキーの組み合わせを押したときに実行される関数です。
```
Office.actions.associate("ShowTaskpane", () => {
    return Office.addin.showAsTaskpane()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});
```
```
Office.actions.associate("HideTaskpane", () => {
    return Office.addin.hide()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});
```

カスタムキーの組み合わせに関するガイドライン

アドインのカスタムキーの組み合わせを作成するには、次のガイドラインを使用します。

キーボードショートカットには、少なくとも 1 つの修飾子キー (Alt/Option、 Ctrl/Cmd、 Shift) と他の 1 つのキーのみを含める必要があります。これらのキーは、 + 文字で結合する必要があります。
Cmd 修飾子キーは、macOS プラットフォームでサポートされています。
macOS では、 Alt キーが Option キーにマップされます。 Windows では、 Cmd キーが Ctrl キーにマップされます。
Shift キーを唯一の修飾子キーとして使用することはできません。 Alt/Option または Ctrl/Cmd と組み合わせる必要があります。
キーの組み合わせには、文字 "A-Z"、"a-z"、"0-9"、および句読点 "-"、"_"、および "+" を含めることができます。規則により、小文字はキーボードショートカットでは使用されません。
2 つの文字が標準キーボードの同じ物理キーにリンクされている場合、カスタムキーボードショートカットのシノニムになります。たとえば、 Alt+a と Alt+A は同じショートカットであり、 Ctrl+-Ctrl+_ ("-" と "_" は同じ物理キーにリンクされます)。

注:

カスタムキーボードショートカットを同時に押す必要があります。キーヒント (シーケンシャルキーショートカット ( Alt+H、 H など) は、Office アドインではサポートされていません。

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

Web でカスタムキーボードショートカットを使用する場合、ブラウザーで使用される一部のキーボードショートカットをアドインでオーバーライドすることはできません。次の一覧は、進行中の作業です。オーバーライドできない他の組み合わせが見つからない場合は、このページの下部にあるフィードバックツールを使用してお知らせください。

Ctrl+N
Ctrl+Shift+N
Ctrl+T
Ctrl+Shift+T
Ctrl+W
Ctrl+PgUp/PgDn

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

Microsoft 365 で既に使用されているキーボードショートカットは多数あります。既に使用されているアドインのキーボードショートカットは登録しないでください。ただし、既存のキーボードショートカットをオーバーライドしたり、同じキーボードショートカットを登録している複数のアドイン間の競合を処理したりする必要がある場合があります。

競合が発生した場合、ユーザーが競合するキーボードショートカットを初めて使用しようとすると、ダイアログボックスが表示されます。このダイアログに表示されるアドインオプションのテキストは、ショートカット JSON ファイルの "actions.name" プロパティから取得されることに注意してください。

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

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

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

最適なユーザーエクスペリエンスを得るには、これらの優れたプラクティスとのキーボードショートカットの競合を最小限に抑えることが推奨されます。

Ctrl+Shift+Alt+x というパターンのキーボードショートカットのみを使用します。x は他のキーです。
Excel とWordで確立されたキーボードショートカットを使用しないでください。一覧については、次を参照してください。
- Excel のキーボードショートカット
- Wordのキーボードショートカット
キーボードフォーカスがアドイン UI 内にある場合、 Ctrl+Space と Ctrl+Shift+F10 は機能しません。これらは、基本的なアクセシビリティショートカットであるためです。
Windows または Mac コンピューターで、 検索メニューで [Office アドインのショートカット設定のリセット ] コマンドを使用できない場合、ユーザーはコンテキストメニューからリボンをカスタマイズすることで、リボンにコマンドを手動で追加できます。

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

次のシナリオでは、カスタムキーボードショートカットをローカライズする必要がある場合があります。

アドインでは、複数のロケールがサポートされています。
アドインでは、さまざまなアルファベット、書き込みシステム、またはキーボードレイアウトがサポートされています。

JSON のキーボードショートカットをローカライズする方法については、「拡張オーバーライドをローカライズする」を参照してください。

特定のユーザーのショートカットカスタマイズを有効にする

注:

このセクションで説明する API には、 KeyboardShortcuts 1.1 要件セットが必要です。

アドインのユーザーは、アドインのアクションを別のキーボードの組み合わせに再割り当てできます。

Office.actions.replaceShortcuts メソッドを使用して、ユーザーのカスタムキーボードの組み合わせをアドインアクションに割り当てます。メソッドは {[actionId:string]: string|null} 型のパラメーターを受け取ります。ここで、 actionIdはアドインの拡張マニフェスト JSON で定義する必要があるアクション ID のサブセットです。値は、ユーザーが推奨するキーの組み合わせです。値を nullすることもできます。これにより、その actionId のカスタマイズが削除され、指定した既定のキーボードの組み合わせに戻ります。

ユーザーが Microsoft 365 にログインしている場合、カスタムの組み合わせはプラットフォームごとのユーザーのローミング設定に保存されます。現在、匿名ユーザーのショートカットのカスタマイズはサポートされていません。

const userCustomShortcuts = {
    ShowTaskpane: "Ctrl+Shift+1",
    HideTaskpane: "Ctrl+Shift+2"
};

Office.actions.replaceShortcuts(userCustomShortcuts)
    .then(() => {
        console.log("Successfully registered shortcut.");
    })
    .catch((error) => {
        if (error.code == "InvalidOperation") {
            console.log("ActionId doesn't 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((inUseArray) => {
        const availableShortcuts = inUseArray.filter((shortcut) => {
            return !shortcut.inUse;
        });
        console.log(availableShortcuts);
        const usedShortcuts = inUseArray.filter((shortcut) => {
            return shortcut.inUse;
        });
        console.log(usedShortcuts);
    });

サポートされている Microsoft 365 アプリ全体にカスタムキーボードショートカットを実装する

Excel やWordなど、サポートされている Microsoft 365 アプリ全体で使用するカスタムキーボードショートカットを実装できます。同じタスクを実行する実装がアプリごとに異なる場合は、 Office.actions.associate メソッドを使用して、アプリごとに異なるコールバック関数を呼び出す必要があります。以下にコードの例を示します。

const host = Office.context.host;
if (host === Office.HostType.Excel) {
    Office.actions.associate("ChangeFormat", changeFormatExcel);
} else if (host === Office.HostType.Word) {
    Office.actions.associate("ChangeFormat", changeFormatWord);
}
...

次の方法で共有

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

前提条件

マニフェストを構成する

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

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

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

カスタムアクションを関数にマップする

カスタムキーの組み合わせに関するガイドライン

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

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

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

特定のユーザーのショートカットカスタマイズを有効にする

サポートされている Microsoft 365 アプリ全体にカスタムキーボードショートカットを実装する

関連項目

その他のリソース

次の方法で共有

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

前提条件

マニフェストを構成する

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

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

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

カスタム アクションを関数にマップする

カスタム キーの組み合わせに関するガイドライン

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

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

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

特定のユーザーのショートカットカスタマイズを有効にする

サポートされている Microsoft 365 アプリ全体にカスタム キーボード ショートカットを実装する

関連項目

その他のリソース

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

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

カスタムアクションを関数にマップする

カスタムキーの組み合わせに関するガイドライン

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

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

サポートされている Microsoft 365 アプリ全体にカスタムキーボードショートカットを実装する