XML マニフェストを使用してアドインコマンドを作成する

[アーティクル]
02/29/2024

アドインコマンドは、アクションを実行する指定された UI 要素を使用して、既定の Office ユーザーインターフェイス (UI) をカスタマイズする簡単な方法を提供します。アドインコマンドの概要については、「アドインコマンド」を参照してください。

この記事では、XML マニフェストを編集してアドインコマンドを定義する方法と、関数コマンドのコードを作成する方法について説明します。

ヒント

Microsoft 365 用の統合マニフェストを使用してアドインコマンドを作成する手順については、「Microsoft 365 用の統合マニフェストを使用してアドインコマンドを作成する」を参照してください。

次の図に、アドインコマンドを定義するのに使用される要素の階層を示します。これらの要素は、この記事で詳細に説明します。

サンプルコマンド

Yo Office によって作成されたすべての作業ウィンドウアドインには、アドインコマンドがあります。作業ウィンドウを表示するアドインコマンド (ボタン) が含まれています。 Excel 作業ウィンドウアドインの作成など、いずれかのクイックスタートに従ってこれらのプロジェクトを生成します。コマンド機能を理解するために、アドインコマンドを読み取っていることを確認します。

アドインコマンドの重要な部分

次の手順では、既存のアドインにアドインコマンドを追加する方法について説明します。

手順 1: VersionOverrides 要素を追加する

<VersionOverrides> 要素は、アドインコマンドの定義を含むルート要素です。有効な属性と影響の詳細については、マニフェストのバージョンオーバーライドに関するページを参照してください。

次の例は、 <VersionOverrides> 要素とその子要素を示しています。

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Requirements>
      <!-- add information about requirement sets -->
    </Requirements>
    <Hosts>
      <Host xsi:type="Workbook">
        <!-- add information about form factors -->
      </Host>
    </Hosts>
    <Resources> 
      <!-- add information about resources -->
    </Resources>
  </VersionOverrides>
...
</OfficeApp>

手順 2: ホスト、ホスト、および DesktopFormFactor 要素を追加する

Hosts> 要素には<、1 つ以上<の Host 要素が>含まれています。 Host> 要素は<、特定の Office アプリケーションを指定します。 <Host> 要素には、アドインをその Office アプリケーションにインストールした後に表示するアドインコマンドを指定する子要素が含まれています。 2 つ以上の異なる Office アプリケーションで同じアドインコマンドを表示するには、各 <ホスト>の子要素を複製する必要があります。

DesktopFormFactor> 要素は<、Office on the web、Windows、Mac で実行されるアドインの設定を指定します。

次の例は、Hosts>、Host、DesktopFormFactor の各要素を示しています<。<><>

<OfficeApp>
...
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
  ...
    <Hosts>
      <Host xsi:type="Workbook">
        <DesktopFormFactor>

              <!-- information about FunctionFile and ExtensionPoint -->

        </DesktopFormFactor>
      </Host>
    </Hosts>
  ...
  </VersionOverrides>
...
</OfficeApp>

手順 3: FunctionFile 要素を追加する

FunctionFile> 要素は<、アドインコマンドが ExecuteFunction アクションを使用するときに実行する JavaScript コードを含むファイルを指定します。 <FunctionFile> 要素の resid 属性は、アドインコマンドで必要なすべての JavaScript ファイルを含む HTML ファイルに設定されます。 You can't link directly to a JavaScript file. You can only link to an HTML file. ファイル名は、Resources> 要素の<<Url> 要素として指定されます。

注:

Yo Office プロジェクトでは、Webpack を使用して、JavaScript を HTML に手動で追加しないようにします。

FunctionFile 要素の例を次に <示> します。

<DesktopFormFactor>
    <FunctionFile resid="Commands.Url" />
    <ExtensionPoint xsi:type="PrimaryCommandSurface">
      <!-- information about this extension point -->
    </ExtensionPoint>

    <!-- You can define more than one ExtensionPoint element as needed -->
</DesktopFormFactor>

重要

Office.js は、アドインコマンドロジックを実行する前に初期化する必要があります。詳細については、「 Office アドインを初期化する」を参照してください。

Outlook の通知

アドインから進捗状況の更新 (進行状況インジケータやエラーメッセージなど) を提供する必要がある場合は、通知 API を介して行う必要があります。通知の処理は、マニフェストのノードで指定された別の HTML ファイルでも FunctionFile 定義する必要があります。

手順 4: ExtensionPoint 要素を追加する

ExtensionPoint> 要素は<、アドインコマンドを Office UI に表示する場所を定義します。

次の例では、PrimaryCommandSurface 属性値と ContextMenu 属性値で ExtensionPoint> 要素を使用<する方法と、それぞれに使用する子要素を使用する方法を示します。

重要

ID 属性を含む要素では、一意の ID を指定してください。会社の名前と ID を使用することをお勧めします。たとえば、次の形式にします。<CustomTab id="mycompanyname.mygroupname">

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso Tab">
  <!-- If you want to use a default tab that comes with Office, remove the above CustomTab element, and then uncomment the following OfficeTab element -->
  <!-- <OfficeTab id="TabData"> -->
    <Label resid="residLabel4" />
    <Group id="Group1Id12">
      <Label resid="residLabel4" />
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Tooltip resid="residToolTip" />
      <Control xsi:type="Button" id="Button1Id1">

        <!-- information about the control -->
      </Control>
      <!-- other controls, as needed -->
    </Group>
  </CustomTab>
</ExtensionPoint>
<ExtensionPoint xsi:type="ContextMenu">
  <OfficeMenu id="ContextMenuCell">
    <Control xsi:type="Menu" id="ContextMenu2">
            <!-- information about the control -->
    </Control>
    <!-- other controls, as needed -->
  </OfficeMenu>
</ExtensionPoint>

手順 5: コントロール要素を追加する

Control> 要素は<、コマンドの使用可能なサーフェス (ボタン、メニューなど) と、それに関連付けられているアクションを定義します。

Button コントロール

ボタンコントロールは、ユーザーが選択したときに 1 つのアクションを実行します。 JavaScript 関数を実行するか、作業ウィンドウを表示することができます。次の例は、2 つのボタンを定義する方法を示しています。最初のボタンは UI を表示しないで JavaScript 関数を実行し、2 つ目のボタンは作業ウィンドウを表示します。 Control 要素で、次の操作を<行います。>

type 属性は必須であり、Button に設定する必要があります。
Control> 要素の<id 属性は、最大 125 文字の文字列です。

<!-- Define a control that calls a JavaScript function. -->
<Control xsi:type="Button" id="Button1Id1">
  <Label resid="residLabel" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>highlightSelection</FunctionName>
  </Action>
</Control>

<!-- Define a control that shows a task pane. -->
<Control xsi:type="Button" id="Button2Id1">
  <Label resid="residLabel2" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon2_32x32" />
    <bt:Image size="32" resid="icon2_32x32" />
    <bt:Image size="80" resid="icon2_32x32" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="residUnitConverterUrl" />
  </Action>
</Control>

次のコードは、FunctionName で使用される関数の例を<>示しています。への呼び出しに注意してください event.completed。これにより、イベントが正常に処理されたことを示します。同一のアドインコマンドを複数回クリックするなど、関数を複数回呼び出すと、すべてのイベントが自動的にキューに入れられます。最初のイベントが自動的に実行され、その他のイベントはキューに残ります。関数がを呼び出 event.completedすと、その関数に対する次のキューに登録された呼び出しが実行されます。を実装 event.completedする必要があります。それ以外の場合、関数は実行されません。

// Initialize the Office Add-in.
Office.onReady(() => {
  // If needed, Office.js is ready to be called
});

// The command function.
async function highlightSelection(event) {

    // Implement your custom code here. The following code is a simple Excel example.  
    try {
          await Excel.run(async (context) => {
              const range = context.workbook.getSelectedRange();
              range.format.fill.color = "yellow";
              await context.sync();
          });
      } catch (error) {
          // Note: In a production add-in, notify the user through your add-in's UI.
          console.error(error);
      }

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
}

// You must register the function with the following line.
Office.actions.associate("highlightSelection", highlightSelection);

メニューコントロールは PrimaryCommandSurface または ContextMenu で使用でき、次を定義します。

ルートレベルのメニュー項目。
サブメニュー項目のリスト。

When used with PrimaryCommandSurface, the root menu item displays as a button on the ribbon. When the button is selected, the submenu displays as a drop-down list. ContextMenu で使用すると、サブメニューを含むメニュー項目がコンテキストメニューに挿入されます。 In both cases, individual submenu items can either execute a JavaScript function or show a task pane. Only one level of submenus is supported at this time.

次の例では、2 つのサブメニュー項目を持つメニュー項目を定義する方法を示します。最初のサブメニュー項目は作業ウィンドウを示し、2 番目のサブメニュー項目は JavaScript 関数を実行します。 Control 要素で、次の操作を<行います。>

xsi:type 属性は必須であり、Menu に設定する必要があります。
id 属性は、最大 125 文字の文字列です。

<Control xsi:type="Menu" id="TestMenu2">
  <Label resid="residLabel3" />
  <Tooltip resid="residToolTip" />
  <Supertip>
    <Title resid="residLabel" />
    <Description resid="residToolTip" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="icon1_32x32" />
    <bt:Image size="32" resid="icon1_32x32" />
    <bt:Image size="80" resid="icon1_32x32" />
  </Icon>
  <Items>
    <Item id="showGallery2">
      <Label resid="residLabel3"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Action xsi:type="ShowTaskpane">
        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
        <SourceLocation resid="residUnitConverterUrl" />
      </Action>
    </Item>
    <Item id="showGallery3">
      <Label resid="residLabel5"/>
      <Supertip>
        <Title resid="residLabel" />
        <Description resid="residToolTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="icon4_32x32" />
        <bt:Image size="32" resid="icon4_32x32" />
        <bt:Image size="80" resid="icon4_32x32" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>getButton</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

手順 6: Resources 要素を追加する

<Resources> 要素には、VersionOverrides 要素のさまざまな子要素によって使用されるリソースが<>含まれています。リソースには、アイコン、文字列、URL が含まれます。 An element in the manifest can use a resource by referencing the id of the resource. Using the id helps organize the manifest, especially when there are different versions of the resource for different locales. An id has a maximum of 32 characters.

Resources 要素の使用方法の例を次に<>示します。各リソースには、特定のロケールに対して異なるリソースを定義するために、1 つ以上 <の Override> 子要素を含めることができます。

<Resources>
  <bt:Images>
    <bt:Image id="icon1_16x16" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp16-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_32x32" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp32-icon_default.png" />
    </bt:Image>
    <bt:Image id="icon1_80x80" DefaultValue="https://www.contoso.com/Images/icon_default.png">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Images/ja-jp80-icon_default.png" />
    </bt:Image>
  </bt:Images>
  <bt:Urls>
    <bt:Url id="residDesktopFuncUrl" DefaultValue="https://www.contoso.com/Pages/Home.aspx">
      <bt:Override Locale="ja-jp" Value="https://www.contoso.com/Pages/Home.aspx" />
    </bt:Url>
  </bt:Urls>
  <bt:ShortStrings>
    <bt:String id="residLabel" DefaultValue="GetData">
      <bt:Override Locale="ja-jp" Value="JA-JP-GetData" />
    </bt:String>
  </bt:ShortStrings>
  <bt:LongStrings>
    <bt:String id="residToolTip" DefaultValue="Get data for your document.">
      <bt:Override Locale="ja-jp" Value="JA-JP - Get data for your document." />
    </bt:String>
  </bt:LongStrings>
</Resources>

注:

Image 要素と <URL 要素内のすべての URL には、Secure Sockets Layer (SSL) を>使用する<必要があります。>

Outlook のサポートに関する注意事項

アドインコマンドは、次の Outlook バージョンで使用できます。

Windows 用 Outlook 2013 以降
Mac 用 Outlook 2016 以降
Outlook on iOS
Outlook on Android
Outlook on the web (Exchange 2016 以降用)
Microsoft 365 および Outlook.com のOutlook on the web
新しい Outlook on Windows (プレビュー)

Exchange 2016 のアドインコマンドのサポートでは、累積的な更新プログラム 5 が必要です。

アドインで XML マニフェストを使用する場合、アドインコマンドは、ItemHasAttachment、ItemHasKnownEntity、ItemHasRegularExpressionMatch ルールを使用しないアドインでのみ使用でき、アクティブ化する項目の種類を制限します。ただし、コンテキストアドインは、現在選択されているアイテムがメッセージか予定かに応じて異なるコマンドを表示でき、読み取りまたは作成のシナリオで表示するかを選択できます。可能な場合はアドインコマンドを使用するのがベストプラクティスです。

XML マニフェストを使用してアドインコマンドを作成する

サンプルコマンド

アドインコマンドの重要な部分

手順 1: VersionOverrides 要素を追加する

手順 2: ホスト、ホスト、および DesktopFormFactor 要素を追加する

手順 3: FunctionFile 要素を追加する

Outlook の通知

手順 4: ExtensionPoint 要素を追加する

手順 5: コントロール要素を追加する

Button コントロール

Menu コントロール

手順 6: Resources 要素を追加する

Outlook のサポートに関する注意事項

関連項目

フィードバック

その他のリソース

XML マニフェストを使用してアドイン コマンドを作成する

サンプル コマンド

アドイン コマンドの重要な部分

手順 1: VersionOverrides 要素を追加する

手順 2: ホスト、ホスト、および DesktopFormFactor 要素を追加する

手順 3: FunctionFile 要素を追加する

Outlook の通知

手順 4: ExtensionPoint 要素を追加する

手順 5: コントロール要素を追加する

Button コントロール

Menu コントロール

手順 6: Resources 要素を追加する

Outlook のサポートに関する注意事項

関連項目

フィードバック

その他のリソース

XML マニフェストを使用してアドインコマンドを作成する

サンプルコマンド

アドインコマンドの重要な部分