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

アドインで Microsoft 365 用の統合アプリ マニフェストを使用する場合、カスタム キーボード ショートカットとそのアクションがマニフェストで定義されます。

1. アドイン プロジェクトで、 manifest.json ファイルを開きます。

2. "extensions.runtimes" 配列に次のオブジェクトを追加します。 このマークアップについて、次の情報にご注意ください。

   • "actions" オブジェクトは、アドインで実行できる関数を指定します。 次の例では、アドインで作業ウィンドウの表示と非表示を切り替えることができます。 これらの関数は、後のセクションで作成します。 現在、カスタム キーボード ショートカットでは、"executeFunction" 型のアクションのみを実行できます。
   • "actions.displayName" プロパティは省略可能ですが、アクションにカスタム キーボード ショートカットを作成する場合は必須です。 このプロパティは、キーボード ショートカットのアクションを記述するために使用されます。 指定した説明は、複数のアドイン間または Microsoft 365 との間にショートカットの競合がある場合にユーザーに表示されるダイアログに表示されます。 Office では、説明の末尾にアドインの名前をかっこで囲んで追加します。 キーボード ショートカットとの競合の処理方法の詳細については、「 他のアドインでキーの組み合わせを使用しないようにする」を参照してください。

   "runtimes": [
       {
           "id": "TaskPaneRuntime",
           "type": "general",
           "code": {
               "page": "https://localhost:3000/taskpane.html"
           },
           "lifetime": "long",
           "actions": [
               {
                   "id": "ShowTaskpane",
                   "type": "executeFunction",
                   "displayName": "Show task pane (Contoso Add-in)"
               },
               {
                   "id": "HideTaskpane",
                   "type": "executeFunction",
                   "displayName": "Hide task pane (Contoso Add-in)"
               }
           ],
       }
   ]
   

3. "extensions" 配列に次を追加します。 マークアップについては、次の点に注意してください。

   • SharedRuntime 1.1 要件セットは、カスタム キーボード ショートカットをサポートするために"requirements.capabilities" オブジェクトで指定されています。
   • 各 "ショートカット" オブジェクトは、キーボード ショートカットによって呼び出される 1 つのアクションを表します。 Office on the web、Windows、Mac など、さまざまなプラットフォームでサポートされているキーの組み合わせを指定します。 カスタム キーの組み合わせを作成する方法のガイダンスについては、「カスタム キーの 組み合わせのガイドライン」を参照してください。
   • 既定のキーの組み合わせを指定する必要があります。 特定のプラットフォーム用に構成された特定の組み合わせがない場合は、サポートされているすべてのプラットフォームで使用されます。
   • "actionId" プロパティの値は、該当する "extensions.runtimes.actions" オブジェクトの "id" プロパティで指定された値と一致する必要があります。

   "keyboardShortcuts": [
       {
           "requirements": {
               "capabilities": [
                   {
                       "name": "SharedRuntime",
                       "minVersion": "1.1"
                   }
               ]
           },
           "shortcuts": [
               {
                   "key": {
                       "default": "Ctrl+Alt+Up",
                       "mac": "Command+Shift+Up",
                       "web": "Ctrl+Alt+1",
                       "windows": "Ctrl+Alt+Up"
                   },
                   "actionId": "ShowTaskpane"
               },
               {
                   "key": {
                       "default": "Ctrl+Alt+Down",
                       "mac": "Command+Shift+Down",
                       "web": "Ctrl+Alt+2",
                       "windows": "Ctrl+Alt+Up"
                   },
                   "actionId": "HideTaskpane"
               }
           ]
       }
   ]
   

共有ランタイムを使用するようにマニフェストを構成する

アドインのキーボード ショートカットをカスタマイズするには、まず 、共有ランタイムを使用するようにアドイン マニフェストを構成する必要があります。 共有ランタイムを使用するようにアドインを構成する方法のガイダンスについては、「共有ランタイムを使用 するようにアドインを構成する」を参照してください。

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

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

1. アドイン プロジェクトで JSON ファイルを作成します。

2. 以下のマークアップをファイルに追加します。 コードについては、次の点に注意してください。

   • "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"
               }
           }
       ]
   }
   

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

1. アドイン プロジェクトで、 manifest.xml ファイルを開きます。
2. マニフェスト内の <VersionOverrides> 要素の直下 (内部ではない) に、ExtendedOverrides 要素を追加します。 Url属性を、前の手順で作成した JSON ファイルの完全な URL に設定します。

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

Microsoft 365 用の統合アプリ マニフェストを使用してカスタム キーボード ショートカットをローカライズする方法については、「 アプリ マニフェストで文字列をローカライズする」を参照してください。

ExtendedOverrides 要素の ResourceUrl 属性を使用して、Microsoft 365 をローカライズされたリソースのファイルに指定します。 次に例を示します。

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/extended-overrides.json" 
                       ResourceUrl="https://contoso.com/addin/my-resources.json">
    </ExtendedOverrides>
</OfficeApp>

拡張オーバーライド ファイルでは、文字列の代わりにトークンが使用されます。 トークンは、リソース ファイル内の文字列に名前を付けます。 アドインの作業ウィンドウを表示する関数 (他の場所で定義) にキーボード ショートカットを割り当てる例を次に示します。 このマークアップに関する注意:

• この例は非常に有効ではありません。 (後の手順で必要な追加プロパティを追加します)。
• トークンの形式は ${resource である必要があります。name-of-resource}。

{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "${resource.ShowTaskpane_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "${resource.ShowTaskpane_default_shortcut}"
            }
        }
    ] 
}

JSON 形式のリソース ファイルには、トップレベルの resources プロパティがあり、ロケールごとにサブプロパティに分割されます。 ロケールごとに、拡張オーバーライド ファイルで使用された各トークンに文字列が割り当てられます。 en-usとfr-frの文字列を含む例を次に示します。 この例では、キーボード ショートカットは両方のロケールで同じですが、特にアルファベットや書き込みシステムが異なるロケールで異なるキーボードをローカライズする場合は、必ずしもそうは限りません。

{
    "resources":{ 
        "en-us": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Show task pane for add-in",
            }, 
        },
        "fr-fr": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Afficher le volet de tâche pour add-in",
              } 
        }
    }
}

en-usセクションとfr-frセクションのピアであるdefault プロパティはファイルにありません。 これは、Microsoft 365 ホスト アプリケーションのロケールがリソース ファイル内の ll-cc プロパティと一致しない場合に使用される既定の文字列を、 拡張オーバーライド ファイル自体で定義する必要があるためです。 拡張オーバーライド ファイルで既定の文字列を直接定義すると、Microsoft 365 アプリケーションのロケールがアドインの既定のロケール (マニフェストで指定されている) と一致する場合に、Microsoft 365 がリソース ファイルをダウンロードしないようにします。 次に、リソース トークンを使用する拡張オーバーライド ファイルの前の例の修正版を示します。

{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "${resource.ShowTaskpane_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "${resource.ShowTaskpane_default_shortcut}"
            }
        }
    ],
    "resources": { 
        "default": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Show task pane for add-in",
            } 
        }
    }
}