アドイン コマンドの可用性を変更する

アドインの一部の機能を特定のコンテキストでのみ使用できる必要がある場合は、これらのコンテキストでのみ使用できるようにカスタム アドイン コマンドをプログラムで構成できます。 たとえば、テーブルのヘッダーを変更する関数は、カーソルがテーブル内にある場合にのみ使用できます。

サポートされている機能

プログラムを使用して、次の機能のアドイン コマンドの可用性を変更できます。

• リボン ボタン、メニュー、タブ。
• コンテキスト メニュー項目。

Office アプリケーションと要件セットのサポート

次の表は、アドイン コマンドの可用性の構成をサポートする Office アプリケーションの概要を示しています。 また、API を使用するために必要な要件セットも一覧表示されます。

共有ランタイムを構成する

リボンまたはコンテキスト メニュー のコントロールまたは項目の可用性を変更するには、まずアドインのマニフェストを 共有ランタイムを使用するように構成する必要があります。 共有ランタイムを設定する方法のガイダンスについては、「共有ランタイム を使用するように Office アドインを構成する」を参照してください。

プログラムによってアドイン コマンドの可用性を変更する

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

const enableButton = async () => {
    const button: Control = { id: "MyButton", enabled: true };
    const parentGroup: Group = { id: "CustomGroup111", controls: [button] };
    const parentTab: Tab = { id: "OfficeAddinTab1", groups: [parentGroup] };
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

await Office.contextMenu.requestUpdate({
    controls: [
        {
            id: Addin.CtxMenu.Button1,
            enabled: true
        },
        {
            id: Addin.CtxMenu.Button2,
            enabled: false
        },
    ]
});

イベントに応じて状態を変更する

リボンまたはコンテキスト メニュー コントロールの状態が変更される一般的なシナリオは、ユーザーが開始したイベントがアドイン コンテキストを変更する場合です。 グラフがアクティブ化されている場合にのみボタンを使用できるシナリオを検討してください。 次の例ではリボン コントロールを使用していますが、同様の実装をコンテキスト メニューのカスタム項目に適用できます。

1. まず、マニフェストのボタンの <Enabled> 要素を false に設定します。 これを構成する方法のガイダンスについては、「 起動時にリボン コントロールを非アクティブ化する」を参照してください。

2. 次に、ハンドラーを割り当てます。 これは通常、次の例のように Office.onReady 関数で実行されます。 この例では、(後の手順で作成した) ハンドラーが、Excel ワークシートのすべてのグラフの onActivated イベントと onDeactivated イベントに割り当てられます。

   Office.onReady(async () => {
       await Excel.run((context) => {
           const charts = context.workbook.worksheets
               .getActiveWorksheet()
               .charts;
           charts.onActivated.add(enableChartFormat);
           charts.onDeactivated.add(disableChartFormat);
           return context.sync();
       });
   });
   

3. enableChartFormat ハンドラーを定義します。 次に簡単な例を示します。 コントロールの状態を変更するより堅牢な方法については、「 ベスト プラクティス: コントロールの状態エラーのテスト」を参照してください。

   function enableChartFormat() {
       const button =
           {
               id: "ChartFormatButton",
               enabled: true
           };
       const parentGroup =
           {
               id: "MyGroup",
               controls: [button]
           };
       const parentTab =
           {
               id: "CustomChartTab",
               groups: [parentGroup]
           };
       const ribbonUpdater = { tabs: [parentTab] };
       Office.ribbon.requestUpdate(ribbonUpdater);
   }
   

4. disableChartFormat ハンドラーを定義します。 ボタン オブジェクトの enabled プロパティが false に設定されている点を除き、enableChartFormat ハンドラーと同じです。

ベスト プラクティス: コントロールの状態エラーのテスト

状況によっては、 requestUpdate が呼び出された後にリボンまたはコンテキスト メニューが再描画されないため、コントロールのクリック可能な状態は変更されません。 このため、アドインがコントロールの状態を追跡するのがベスト プラクティスです。 アドインは、次の規則に準拠している必要があります。

• requestUpdate が呼び出された場合はいつでも、コードがカスタム ボタンとメニュー項目の意図した状態を記録する必要があります。
• カスタム コントロールを選択すると、ハンドラー内の最初のコードがチェックされ、ボタンが使用可能になっているかどうかを確認する必要があります。 使用できない場合は、コードでエラーを報告またはログに記録し、ボタンを目的の状態に設定し直す必要があります。

次の例は、リボンのボタンを非アクティブ化し、ボタンの状態を記録する関数を示しています。 この例では、 chartFormatButtonEnabled はグローバルブール変数であり、アドインのマニフェストのボタンの Enabled 要素と同じ値に初期化されます。 この例ではリボン ボタンを使用していますが、コンテキスト メニューのカスタム項目にも同様の実装を適用できます。

function disableChartFormat() {
    const button =
    {
        id: "ChartFormatButton",
        enabled: false
    };
    const parentGroup =
    {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab =
    {
        id: "CustomChartTab",
        groups: [parentGroup]
    };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

次の例は、ボタンのハンドラーがボタンの不正な状態をテストする方法を示しています。 reportError は、エラーを表示または記録する関数です。

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here.

    } else {
        // Report the error and try to make the button unavailable again.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

エラー処理

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

function disableChartFormat() {
    try {
        const button =
        {
            id: "ChartFormatButton",
            enabled: false
        };
        const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
        const ribbonUpdater = { tabs: [parentTab] };
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

関連項目

• アドイン コマンド
• アドインのみのマニフェストを使用してアドイン コマンドを作成する
• Office アドインでカスタム コンテキスト タブを作成する