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

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

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

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

ヒント

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 アプリケーションで同じアドインコマンドを表示するには、各 <Host> 内の子要素を複製する必要があります。

<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 を介して行う必要があります。通知の処理は、マニフェストの FunctionFile ノードで指定された別の HTML ファイルでも定義する必要があります。

手順 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 バージョンで使用できます。

Outlook on the web for Microsoft 365 and Outlook.com
Outlook on the web (Exchange 2016 以降用)
新しい Outlook on Windows
Windows での Outlook 2016 以降
Outlook on Mac
Outlook on Android
Outlook on iOS

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

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

次の方法で共有

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

サンプルコマンド

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

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

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

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

Outlook の通知

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

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

Button コントロール

Menu コントロール

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

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

関連項目

その他のリソース

次の方法で共有

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

サンプル コマンド

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

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

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

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

Outlook の通知

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

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

Button コントロール

Menu コントロール

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

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

関連項目

その他のリソース

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

サンプルコマンド

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