Office アドインでカスタムコンテキストタブを作成する

[アーティクル]
08/18/2023

コンテキストタブは、Office リボンの非表示のタブコントロールであり、Office ドキュメントで指定したイベントが発生したときにタブ行に表示されます。たとえば、テーブルが選択されている場合に Excel リボンに表示される [テーブル デザイン ] タブなどです。 Office アドインにカスタムコンテキストタブを含め、表示または非表示のタイミングを指定するには、可視性を変更するイベントハンドラーを作成します。 (ただし、カスタムコンテキストタブはフォーカスの変更に応答しません)。

注:

この記事では、次のドキュメントについて理解していることを前提としています。最近、アドインコマンド (カスタムメニュー項目とリボンボタン) を使用してない場合は、ドキュメントをご確認ください。

アドインコマンドの基本概念

重要

カスタムコンテキストタブは現在、Excel でのみサポートされており、これらのプラットフォームとビルドでのみサポートされています。

Windows 上の Excel: バージョン 2102 (ビルド 13801.20294) 以降。
Excel on Mac: バージョン 16.53.806.0 以降。
Excel on the web

注:

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

コード内のランタイムチェックを使用して、「メソッドと要件セットのサポートのランタイムチェック」で説明されているように、ユーザーのホストとプラットフォームの組み合わせでこれらの要件セットがサポートされているかどうかをテストできます。 (マニフェストで要件セットを指定する手法は、この記事でも説明されていますが、RibbonApi 1.2 では現在機能しません)。または、カスタムコンテキストタブがサポートされていない場合に、代替 UI エクスペリエンスを実装することもできます。

カスタムコンテキストタブの動作

カスタムコンテキストタブのユーザーエクスペリエンスは、組み込みの Office コンテキストタブのパターンに従います。配置カスタムコンテキストタブの基本原則を次に示します。

カスタムコンテキストタブが表示されると、リボンの右端に表示されます。
アドインの 1 つ以上の組み込みコンテキストタブと 1 つ以上のカスタムコンテキストタブが同時に表示される場合、カスタムコンテキストタブは常にすべての組み込みコンテキストタブの右側に表示されます。
アドインに複数のコンテキストタブがあり、複数のコンテキストが表示される場合は、アドインで定義されている順序で表示されます。 (方向は Office 言語と同じ方向です。つまり、左から右の言語では左から右、右から左の言語では右から左)。定義方法の詳細については、「タブに表示されるグループとコントロールを定義する」を参照してください。
特定のコンテキストで表示されるコンテキストタブが複数のアドインにある場合は、アドインが起動された順序で表示されます。
カスタム コンテキスト タブは、カスタムコアタブとは異なり、Office アプリケーションのリボンに永続的に追加されません。アドインが実行されている Office ドキュメントにのみ表示されます。

アドインにコンテキストタブを含める主な手順

アドインにカスタムコンテキストタブを含める主な手順を次に示します。

共有ランタイムを使用するようにアドインを構成します。
タブとそのタブに表示されるグループとコントロールを定義します。
コンテキストタブを Office に登録します。
タブが表示される状況を指定します。

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

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

タブに表示されるグループとコントロールを定義する

マニフェストで XML で定義されるカスタムコアタブとは異なり、カスタムコンテキストタブは実行時に JSON BLOB で定義されます。コードでは、BLOB を JavaScript オブジェクトに解析し、そのオブジェクトを Office.ribbon.requestCreateControls メソッドに渡します。カスタムコンテキストタブは、アドインが現在実行されているドキュメントにのみ存在します。これは、アドインのインストール時に Office アプリケーションリボンに追加され、別のドキュメントを開いたときに表示されるカスタムコアタブとは異なります。また、メソッドはアドインの requestCreateControls セッションで 1 回だけ実行できます。再度呼び出された場合は、エラーがスローされます。

注:

JSON BLOB のプロパティとサブプロパティ (およびキー名) の構造は、マニフェスト XML 内の CustomTab 要素とその子孫要素の構造とほぼ平行です。

コンテキストタブ JSON BLOB の例を段階的に作成します。コンテキストタブ JSON の完全なスキーマは、 dynamic-ribbon.schema.json にあります。 Visual Studio Code で作業している場合は、このファイルを使用して IntelliSense を取得し、JSON を検証できます。詳細については、「 Visual Studio Code を使用した JSON の編集 - JSON スキーマと設定」を参照してください。

まず、とという名前 actions の 2 つの配列プロパティを持つ JSON 文字列を tabs作成します。配列は actions 、コンテキストタブのコントロールによって実行できるすべての関数の仕様です。配列は tabs 、1 つ以上のコンテキストタブ ( 最大 20 個) を定義します。
```
'{
  "actions": [

  ],
  "tabs": [

  ]
}'
```
コンテキストタブのこの単純な例では、ボタンが 1 つしかないため、アクションは 1 つだけです。配列の唯一のメンバーとして次を actions 追加します。このマークアップについては、次の点に注意してください。
- idプロパティと type プロパティは必須です。
- の type 値は、"ExecuteFunction" または "ShowTaskpane" のいずれかです。
- プロパティは functionName 、の type 値がの ExecuteFunction場合にのみ使用されます。これは、FunctionFile で定義されている関数の名前です。 FunctionFile の詳細については、「アドインコマンドの基本的な概念」を参照してください。
- 後の手順では、このアクションをコンテキストタブのボタンにマップします。
```
{
  "id": "executeWriteData",
  "type": "ExecuteFunction",
  "functionName": "writeData"
}
```
配列の唯一のメンバーとして次を tabs 追加します。このマークアップについては、次の点に注意してください。
- id プロパティは必須です。アドイン内のすべてのコンテキストタブで一意の簡単でわかりやすい ID を使用します。
- label プロパティは必須です。コンテキストタブのラベルとして機能するわかりやすい文字列です。
- groups プロパティは必須です。タブに表示されるコントロールのグループを定義します。少なくとも 1 つのメンバーを持 ち、20 以下である必要があります。 (カスタムコンテキストタブで使用できるコントロールの数にも制限があり、グループの数も制限されます。詳細については、次の手順を参照してください)。
注:

Tab オブジェクトには、アドインの起動時にタブをすぐに表示するかどうかを指定する省略可能な visible プロパティを指定することもできます。コンテキストタブは通常、ユーザーイベントによって可視性がトリガーされるまで非表示になるため (ユーザーがドキュメント内の何らかの種類のエンティティを選択する場合など) visible 、プロパティは既定で存在しない場合にに false 設定されます。後のセクションでは、イベントに応答してプロパティをに true 設定する方法について説明します。
```
{
  "id": "CtxTab1",
  "label": "Contoso Data",
  "groups": [

  ]
}
```
単純な進行中の例では、コンテキストタブのグループは 1 つだけです。配列の唯一のメンバーとして次を groups 追加します。このマークアップについては、次の点に注意してください。
- すべてのプロパティが必要です。
- プロパティは id 、マニフェスト内のすべてのグループ間で一意である必要があります。最大 125 文字の簡単でわかりやすい ID を使用します。
- labelは、グループのラベルとして機能するわかりやすい文字列です。
- iconプロパティの値は、リボンと Office アプリケーションウィンドウのサイズに応じて、グループがリボンに表示するアイコンを指定するオブジェクトの配列です。
- controlsプロパティの値は、グループ内のボタンとメニューを指定するオブジェクトの配列です。少なくとも 1 つ必要です。
重要

タブ全体のコントロールの合計数は、20 以下にすることができます。 たとえば、それぞれ 6 つのコントロールを持つ 3 つのグループと 2 つのコントロールを持つ 4 つ目のグループを含めることができますが、それぞれ 6 つのコントロールを持つ 4 つのグループを持つすることはできません。
```
{
    "id": "CustomGroup111",
    "label": "Insertion",
    "icon": [

    ],
    "controls": [

    ]
}
```
すべてのグループには、32x32 px と 80x80 px の少なくとも 2 つのサイズのアイコンが必要です。必要に応じて、サイズ 16x16 px、20x20 px、24x24 px、40x40 px、48x48 px、64x64 px のアイコンを使用することもできます。 Office は、リボンと Office アプリケーションウィンドウのサイズに基づいて、使用するアイコンを決定します。アイコン配列に次のオブジェクトを追加します。 (ウィンドウとリボンのサイズが、グループのコントロールの少なくとも 1 つを表示するのに十分な大きさの場合、グループアイコンはまったく表示されません。たとえば、Word ウィンドウを縮小して展開するときに、Word リボンの [スタイル] グループをwatchします)。このマークアップについては、次の点に注意してください。
- どちらのプロパティも必要です。
- sizeプロパティの測定単位はピクセルです。アイコンは常に正方形であるため、数値は高さと幅の両方です。
- プロパティは sourceLocation 、アイコンへの完全な URL を指定します。
重要

通常、開発から運用環境に移行する場合 (localhost から contoso.com へのドメインの変更など) にアドインのマニフェストの URL を変更する必要があるのと同様に、コンテキストタブの JSON 内の URL も変更する必要があります。
```
{
    "size": 32,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
},
{
    "size": 80,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
}
```
簡単な進行中の例では、グループには 1 つのボタンしかありません。次のオブジェクトを配列の唯一の controls メンバーとして追加します。このマークアップについては、次の点に注意してください。
- を除く enabledすべてのプロパティが必要です。
- type はコントロールの種類を指定します。値には、"Button"、"Menu"、または "MobileButton" を指定できます。
- id は最大 125 文字です。
- actionId は、配列で actions 定義されているアクションの ID である必要があります。 (このセクションの手順 1 を参照してください)。
- label は、ボタンのラベルとして機能するわかりやすい文字列です。
- superTip は、豊富なツールヒントを表します。プロパティと description プロパティのtitle両方が必要です。
- icon ボタンのアイコンを指定します。グループアイコンに関する以前の説明もここに適用されます。
- enabled (省略可能) コンテキストタブが起動したときにボタンを有効にするかどうかを指定します。存在しない場合の既定値はです true。
```
{
    "type": "Button",
    "id": "CtxBt112",
    "actionId": "executeWriteData",
    "enabled": false,
    "label": "Write Data",
    "superTip": {
        "title": "Data Insertion",
        "description": "Use this button to insert data into the document."
    },
    "icon": [
        {
            "size": 32,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
        },
        {
            "size": 80,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
        }
    ]
}
```

JSON BLOB の完全な例を次に示します。

`{
  "actions": [
    {
      "id": "executeWriteData",
      "type": "ExecuteFunction",
      "functionName": "writeData"
    }
  ],
  "tabs": [
    {
      "id": "CtxTab1",
      "label": "Contoso Data",
      "groups": [
        {
          "id": "CustomGroup111",
          "label": "Insertion",
          "icon": [
            {
                "size": 32,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
            },
            {
                "size": 80,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
            }
          ],
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "executeWriteData",
                "enabled": false,
                "label": "Write Data",
                "superTip": {
                    "title": "Data Insertion",
                    "description": "Use this button to insert data into the document."
                },
                "icon": [
                    {
                        "size": 32,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
                    },
                    {
                        "size": 80,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
                    }
                ]
            }
          ]
        }
      ]
    }
  ]
}`

requestCreateControls を使用してコンテキストタブを Office に登録する

コンテキストタブは、 Office.ribbon.requestCreateControls メソッドを呼び出すことによって Office に登録されます。これは通常、関数に割り当てられている関数または関数を使用して Office.initialize 実行されます Office.onReady 。これらの関数とアドインの初期化の詳細については、「 Office アドインの初期化」を参照してください。ただし、初期化後はいつでもメソッドを呼び出すことができます。

重要

メソッドは requestCreateControls 、アドインの特定のセッションで 1 回だけ呼び出されることがあります。再度呼び出されるとエラーがスローされます。

次に例を示します。 JSON 文字列を JavaScript 関数に渡すには、メソッドを使用 JSON.parse して JavaScript オブジェクトに変換する必要があることに注意してください。

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string such as the one at the end of the preceding section.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);
});

タブが requestUpdate で表示されるコンテキストを指定する

通常、ユーザーが開始したイベントがアドインコンテキストを変更すると、カスタムコンテキストタブが表示されます。 (Excel ブックの既定のワークシート上の) グラフがアクティブ化されている場合にのみ、タブを表示するシナリオを検討してください。

まず、ハンドラーを割り当てます。これは一般的に、次の例のように関数で Office.onReady 実行されます。これは、ハンドラー (後の手順で作成) を onActivated ワークシート内のすべてのグラフのイベントと onDeactivated イベントに割り当てます。

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);

    await Excel.run(context => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(showDataTab);
        charts.onDeactivated.add(hideDataTab);
        return context.sync();
    });
});

次に、ハンドラーを定義します。の簡単な例を次に示しますが、より堅牢なバージョンの showDataTab関数については、この記事の後半の「HostRestartNeededed エラーの処理」を参照してください。このコードについては、以下の点に注意してください。

Office では、リボンの状態を更新するタイミングが制御されます。 Office.ribbon.requestUpdate メソッドは、更新要求をキューに入れます。メソッドは、リボンが実際に Promise 更新されたときではなく、要求をキューに入れるとすぐにオブジェクトを解決します。
メソッドの requestUpdate パラメーターは RibbonUpdaterData オブジェクトで、(1) は JSON で指定されたとおりに ID でタブを指定 し、(2) はタブの可視性を指定します。
同じコンテキストで表示する必要があるカスタムコンテキストタブが複数ある場合は、配列に追加のタブオブジェクトを tabs 追加するだけです。

async function showDataTab() {
    await Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            }
        ]});
}

タブを非表示にするハンドラーは、プロパティをに戻visiblefalseす点を除いて、ほぼ同じです。

また、Office JavaScript ライブラリには、オブジェクトの構築RibbonUpdateData を容易にするために、いくつかのインターフェイス (型) も用意されています。 TypeScript の関数を showDataTab 次に示します。これらの型を使用します。

const showDataTab = async () => {
    const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
    const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
    await Office.ribbon.requestUpdate(ribbonUpdater);
}

タブの表示とボタンの有効な状態を同時に切り替える

メソッドは requestUpdate 、カスタムコンテキストタブまたはカスタムコアタブのカスタムボタンの有効または無効の状態を切り替えるためにも使用されます。詳細については、「アドインコマンドを有効または無効にする」を参照してください。タブの表示とボタンの有効な状態の両方を同時に変更するシナリオがある場合があります。これは、の 1 回の requestUpdate呼び出しで行います。次に、コンテキストタブと同時にコアタブのボタンを有効にする例を示します。

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            },
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                            }
                        ]
                    }
                ]
            ]}
        ]
    });
}

次の例では、有効になっているボタンは、表示されるコンテキストタブとまったく同じです。

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true,
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                           }
                       ]
                   }
               ]
            }
        ]
    });
}

コンテキストタブから作業ウィンドウを開く

カスタムコンテキストタブのボタンから作業ウィンドウを開くには、のを使用して JSON にアクションをtypeShowTaskpane作成します。次に、プロパティがアクションのの actionIdid に設定されたボタンを定義します。これにより、マニフェストの Runtime> 要素で指定された既定の<作業ウィンドウが開きます。

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

既定の作業ウィンドウではない作業ウィンドウを開くには、アクションの定義でプロパティを指定 sourceLocation します。次の例では、別のボタンから 2 つ目の作業ウィンドウが開きます。

重要

アクションに sourceLocation が指定されている場合、作業ウィンドウは共有ランタイムを使用 しません 。新しい個別のランタイムで実行されます。
共有ランタイムを使用できる作業ウィンドウは複数ないため、プロパティを省略sourceLocationできる型ShowTaskpaneのアクションは複数ありません。

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    },
    {
      "id": "openTablesTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Tables",
      "supportPinning": false
      "sourceLocation": "https://MyDomain.com/myPage.html"
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            },
            {
                "type": "Button",
                "id": "CtxBt113",
                "actionId": "openTablesTaskpane",
                "enabled": false,
                "label": "Open Tables Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

JSON テキストをローカライズする

渡される requestCreateControls JSON BLOB は、カスタムコアタブのマニフェストマークアップがローカライズされるのと同じ方法でローカライズされません (マニフェストからのローカライズの制御に関するページで説明されています)。代わりに、ロケールごとに個別の JSON BLOB を使用して実行時にローカライズを行う必要があります。 Office.context.displayLanguage プロパティをswitchテストするステートメントを使用することをお勧めします。次に例を示します。

function GetContextualTabsJsonSupportedLocale () {
    const displayLanguage = Office.context.displayLanguage;

        switch (displayLanguage) {
            case 'en-US':
                return `{
                    "actions": [
                        // actions omitted
                     ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Data",
                          "groups": [
                              // groups omitted
                          ]
                        }
                    ]
                }`;

            case 'fr-FR':
                return `{
                    "actions": [
                        // actions omitted 
                    ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Données",
                          "groups": [
                              // groups omitted
                          ]
                       }
                    ]
               }`;

            // Other cases omitted
       }
}

次に、次の例のように、関数を呼び出してに requestCreateControls渡されるローカライズされた BLOB を取得します。

const contextualTabJSON = GetContextualTabsJsonSupportedLocale();

カスタムコンテキストタブのベストプラクティス

カスタムコンテキストタブがサポートされていない場合に代替 UI エクスペリエンスを実装する

プラットフォーム、Office アプリケーション、および Office ビルドの組み合わせによっては、がサポート requestCreateControlsされていません。アドインは、これらの組み合わせのいずれかでアドインを実行しているユーザーに代替エクスペリエンスを提供するように設計する必要があります。以降のセクションでは、フォールバックエクスペリエンスを提供する 2 つの方法について説明します。

非コンテキストタブまたはコントロールを使用する

マニフェスト要素 OverriddenByRibbonApi は、カスタムコンテキストタブをサポートしていないアプリケーションまたはプラットフォームでアドインが実行されているときにカスタムコンテキストタブを実装するフォールバックエクスペリエンスをアドインに作成するように設計されています。

この要素を使用する最も簡単な方法は、アドイン内のカスタムコンテキストタブのリボンのカスタマイズを複製するカスタムコアタブ (つまり、 コンテキストに依存しない カスタムタブ) をマニフェストに定義することです。ただし、カスタムコアタブの重複するグループ、コントロール、メニュー<項目>要素の最初の子要素としてを追加<OverriddenByRibbonApi>true</OverriddenByRibbonApi>します。その効果は次のとおりです。

カスタムコンテキストタブをサポートするアプリケーションとプラットフォームでアドインが実行されている場合、カスタムコアグループとコントロールはリボンに表示されません。代わりに、アドインがメソッドを呼び出すと、カスタムコンテキストタブが requestCreateControls 作成されます。
をサポートrequestCreateControlsしていないアプリケーションまたはプラットフォームでアドインが実行されている場合、要素はカスタムコアタブに表示されます。

次に例を示します。カスタムコンテキストタブがサポートされていない場合にのみ、カスタムコアタブに "MyButton" が表示されることに注意してください。ただし、カスタムコンテキストタブがサポートされているかどうかに関係なく、親グループとカスタムコアタブが表示されます。

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>              
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton1">
                  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
                  ...
                  <Action ...>
...
</OfficeApp>

その他の例については、「 OverriddenByRibbonApi」を参照してください。

親グループまたはメニューがで <OverriddenByRibbonApi>true</OverriddenByRibbonApi>マークされている場合、そのグループは表示されず、カスタムコンテキストタブがサポートされていない場合、その子マークアップはすべて無視されます。そのため、これらの子要素のいずれかが OverriddenByRibbonApi> 要素を<持っているか、その値が何であるかは関係ありません。これは、メニュー項目またはコントロールをすべてのコンテキストで表示する必要がある場合は、でマーク <OverriddenByRibbonApi>true</OverriddenByRibbonApi>する必要があるだけでなく、 先祖のメニューとグループもこのようにマークする必要がないということです。

重要

グループまたはメニュー のすべての 子要素をで <OverriddenByRibbonApi>true</OverriddenByRibbonApi>マークしないでください。前の段落で指定した理由で親要素がで <OverriddenByRibbonApi>true</OverriddenByRibbonApi> マークされている場合、これは無意味です。さらに、親に対して <OverriddenByRibbonApi> を省略した場合 (またはに false設定) すると、カスタムコンテキストタブがサポートされているかどうかに関係なく親が表示されますが、サポートされている場合は空になります。そのため、カスタムコンテキストタブがサポートされているときにすべての子要素が表示されない場合は、親をで <OverriddenByRibbonApi>true</OverriddenByRibbonApi>マークします。

指定したコンテキストで作業ウィンドウを表示または非表示にする API を使用する

OverriddenByRibbonApi> の<代わりに、アドインは、カスタムコンテキストタブのコントロールの機能を複製する UI コントロールを含む作業ウィンドウを定義できます。次に、Office.addin.showAsTaskpane メソッドと Office.addin.hide メソッドを使用して、コンテキストタブがサポートされている場合に作業ウィンドウを表示します。これらの方法の使用方法の詳細については、「 Office アドインの作業ウィンドウを表示または非表示にする」を参照してください。

HostRestartNeeded エラーを処理する

一部のシナリオでは、Office はリボンを更新できず、エラーを返します。たとえば、アドインがアップグレードされ、アップグレードされたアドインに異なるカスタムアドインコマンドのセットがある場合は、Office アプリケーションを閉じてから、もう一度開く必要があります。それまでの間、requestUpdate メソッドは HostRestartNeeded エラーを返します。コードでこのエラーを処理する必要があります。方法の例を次に示します。この場合、reportError メソッドがユーザーにエラーを表示します。

function showDataTab() {
    try {
        Office.ribbon.requestUpdate({
            tabs: [
                {
                    id: "CtxTab1",
                    visible: true
                }
            ]});
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, then close and reopen the Office application.");
        }
    }
}

リソース

コードサンプル: リボンにカスタムコンテキストタブを作成する
コンテキストタブのコミュニティデモのサンプル

Office アドインでカスタムコンテキストタブを作成する

カスタムコンテキストタブの動作

アドインにコンテキストタブを含める主な手順

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

タブに表示されるグループとコントロールを定義する

requestCreateControls を使用してコンテキストタブを Office に登録する

タブが requestUpdate で表示されるコンテキストを指定する

タブの表示とボタンの有効な状態を同時に切り替える

コンテキストタブから作業ウィンドウを開く

JSON テキストをローカライズする

カスタムコンテキストタブのベストプラクティス

カスタムコンテキストタブがサポートされていない場合に代替 UI エクスペリエンスを実装する

非コンテキストタブまたはコントロールを使用する

指定したコンテキストで作業ウィンドウを表示または非表示にする API を使用する

HostRestartNeeded エラーを処理する

リソース

フィードバック

その他のリソース

Office アドインでカスタム コンテキスト タブを作成する

カスタム コンテキスト タブの動作

アドインにコンテキスト タブを含める主な手順

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

タブに表示されるグループとコントロールを定義する

requestCreateControls を使用してコンテキスト タブを Office に登録する

タブが requestUpdate で表示されるコンテキストを指定する

タブの表示とボタンの有効な状態を同時に切り替える

コンテキスト タブから作業ウィンドウを開く

JSON テキストをローカライズする

カスタム コンテキスト タブのベスト プラクティス

カスタム コンテキスト タブがサポートされていない場合に代替 UI エクスペリエンスを実装する

非コンテキスト タブまたはコントロールを使用する

指定したコンテキストで作業ウィンドウを表示または非表示にする API を使用する

HostRestartNeeded エラーを処理する

リソース

フィードバック

その他のリソース

Office アドインでカスタムコンテキストタブを作成する

カスタムコンテキストタブの動作

アドインにコンテキストタブを含める主な手順

requestCreateControls を使用してコンテキストタブを Office に登録する

コンテキストタブから作業ウィンドウを開く

カスタムコンテキストタブのベストプラクティス

カスタムコンテキストタブがサポートされていない場合に代替 UI エクスペリエンスを実装する

非コンテキストタブまたはコントロールを使用する