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

[アーティクル]
09/24/2024

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

注:

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

前提条件

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

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

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

ヒント

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

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

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

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

警告

現在、カスタムコンテキストタブを使用すると、ユーザーが以前の Excel アクションを元に戻すことができなくなる可能性があります。これは既知の問題 ( この GitHub スレッドを参照) であり、アクティブな調査中です。

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

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

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

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

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

コンテキストタブのアイコンを指定する

コンテキストタブをカスタマイズするには、まず、アドインのマニフェストの [リソース] セクションで Image 要素を使用して表示されるアイコンを指定する必要があります。各アイコンには、16x16 px、32x32 px、80x80 px の 3 つ以上のサイズが必要です。

次に例を示します。

<Resources>
    <bt:Images>
        <bt:Image id="contextual-tab-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"/>
        <bt:Image id="contextual-tab-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"/>
        <bt:Image id="contextual-tab-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"/>
        <bt:Image id="contextual-button-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"/>
        <bt:Image id="contextual-button-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"/>
        <bt:Image id="contextual-button-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"/>
    </bt:Images>
    ...
</Resources>

重要

アドインを開発から運用環境に移行する場合は、必要に応じてマニフェストの URL を更新してください (ドメインを localhost から contoso.comに変更するなど)。

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

マニフェストで 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 と tabs という名前の 2 つの配列プロパティを持つ JSON 文字列を作成します。 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": [

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

通常、開発から運用環境に移行するときにアドインのマニフェストの URL を変更する必要があるのと同様に、コンテキストタブの JSON の URL も変更する必要があります。
```
{
    "size": 16,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
},
{
    "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 は、豊富なツールヒントを表します。 titleプロパティとdescriptionプロパティの両方が必要です。
- 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": 16,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
        },
        {
            "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": 16,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
            },
            {
                "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": 16,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
                    },
                    {
                        "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の簡単な例を示しますが、より堅牢なバージョンの関数については、この記事の後半の「HostRestartNeeded エラーの処理」を参照してください。このコードについては、以下の点に注意してください。

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

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

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

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

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 に作成します。次に、 actionId プロパティがアクションの id に設定されているボタンを定義します。これにより、マニフェストの <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型のアクションは 1 つ以上ありません。

`{
  "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> を、カスタムコアタブの重複する Group、 Control、menu <Item> 要素の最初の子要素として追加します。その効果は次のとおりです。

カスタムコンテキストタブをサポートするアプリケーションとプラットフォームでアドインが実行されている場合、カスタムコアグループとコントロールはリボンに表示されません。代わりに、アドインが 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 エクスペリエンスを実装する

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