Office JavaScript API を理解する

21 分

このユニットでは、Excel、Outlook、Word 用の Office アドインのプログラミングモデル、開発者ツール、Office JavaScript API の機能について説明します。

Office アドインプログラミングモデルを理解する

Office アドインプログラミングモデルは 2 つの JavaScript オブジェクトモデルに基づいています。

ホスト固有の JavaScript API - Excel および Word 用のホスト固有の API には、ホストアプリケーション内の特定の要素へのアクセスに使用できる、型指定されたオブジェクトが用意されています。たとえば、Excel API には、ワークシート、範囲、テーブル、グラフなどを表すオブジェクトが含まれています。
共通 API - Office 2013 で導入された共通 API では、次のような機能にアクセスできます。
- UI
- ダイアログ
- 複数の種類の Office アプリケーションに共通するクライアント設定

カスタム関数では少し異なるプログラミングモデルを使用します。これについては後のユニットで説明します。

Office JavaScript API の要件セット

ユーザーがインストールしている Office のバージョンを制御できない場合があります。使用している Office およびそれが実行されているプラットフォームのバージョンによって、アドインでサポートされる API や機能は異なります。たとえば、Office 2016 は Office 2013 よりも多くの機能をサポートしています。このような状況に対処するため、Office アドインで必要な機能を Office ホストがサポートしているかどうかを判別するのに役立つ、要件セットが用意されています。

要件セットは、ExcelApi 1.7 のように Office ホストに固有のものもあれば、ダイアログ API のように複数のホストに共通のものもあります。要件セットのサポートは、Office ホストとホストのバージョンごとに異なります。

isSetSupported を使用すると、使用しているアドインの Office ホストで要件セットがサポートされているかどうかをプログラムから確認できます。要件セットがサポートされる場合、isSetSupported は true を返し、アドインは、その要件セットにある API メンバーを使用する追加コードを実行できます。 Office ホストで要件セットがサポートされない場合、isSetSupported は false を返し、追加コードは実行されません。次のコードは isSetSupported と共に使用する構文を示しています。

if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion)) {
  // Code that uses API members from RequirementSetName.
}

注:

Office Insider プログラム

すべての Office ホストに対する変更をいち早く知り、あるいは毎月の変更を入手するには、Office Insider プログラムに参加します。このプログラムは Windows PC 専用であり、Microsoft 365 サブスクリプションが必要です。いずれかの Office アプリケーションで、[ファイル]>[アカウント]>[Office Insider] を選択すると、プログラムにすぐに参加できます。

Office JavaScript API を使用する

これらの API を使用するには、通常、次のコードステートメントのいずれかをページの <head> タグに追加することにより、Office.js コンテンツ配信ネットワーク (CDN) でその API を参照します。

<!-- Reference the production APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

<!-- Reference the beta/preview APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js" type="text/javascript"></script>

任意の CDN リンクを追加するのに加えて、すべての Office アドインは Office.onReady() の呼び出しを必要とします。アドインコードをこのメソッドに追加すると、Office.js ライブラリが初期化された後にそのメソッドが呼び出されます。 onReady() メソッドの内部では、Office.HostType 列挙値 (Excel、Word など) をチェックすることで、アドインがどのホストで実行されているかを確認できます。 Office.PlatformType 列挙値 (PC や Mac) を使用すると、アドインが実行されているプラットフォームを確認できます。

独自の初期化ハンドラーやテストを含む他の JavaScript フレームワークを使用している場合、そのようなフレームワークは Office.onReady() への応答内に配置される必要があります。たとえば次のコード例のように、jQuery の $(document).ready() 関数を参照します。

Office.onReady(function() {
  // Office is ready.
  $(document).ready(function () {
    // The document is ready.
  });
});

プロキシオブジェクトを使用して非同期呼び出しを行う

ドキュメントを操作するとき、要求される読み取りアクションや書き込みアクションは、プロキシオブジェクトを使用してバッチ処理されます。 sync() メソッドを呼び出すまでは、API 呼び出しにより元のドキュメントが実際に読み取られたり更新されたりすることはありません。

セキュリティを強化するために、アドインは、ドキュメントやその他のアドインに直接アクセスできないサンドボックス化された JavaScript 環境で実行されます。Office アドインのプラットフォームには、ドキュメント (ワークシート、範囲、テーブルなど) を表すプロキシオブジェクトを提供する RequestContext オブジェクトが用意されています。通常、RequestContext は、context という名前のパラメーターとしてコードに渡されます。 context オブジェクトを使用して、ドキュメントで作業する必要があるプロキシオブジェクトを取得できます。

プロキシオブジェクトのプロパティを読み取るには、まず Office ドキュメントからプロキシオブジェクトとデータを入力するプロパティを読み込む必要があります。これを行うには、必要なプロパティのプロキシオブジェクトに対して load() メソッドを呼び出します。次に context.sync() メソッドを呼び出して、要求されたすべてのプロパティを読み込みます。たとえば、Excel ワークシートの選択範囲を操作するプロキシオブジェクトを作成してから選択範囲の address プロパティを読み取る場合、読み取る前に address プロパティを読み込む必要があります。読み込むプロキシオブジェクトのプロパティを要求するには、オブジェクトに対して load() メソッドを呼び出し、読み込むプロパティを指定します。

次の例は、ローカルプロキシオブジェクト (selectedRange) を定義して、そのオブジェクトの address プロパティを読み込み、context.sync() を呼び出す関数を示しています。 context.sync() の promise が解決されると、コードから address プロパティを読み取れます。関数の実行時にプラットフォームの動作に影響を与えるプロパティを読み込むには、その特定のホスト用の Excel.run が必要です。すべてのホストに run 呼び出しが含まれているわけではありません。

Excel.run(function (context) {
  var selectedRange = context.workbook.getSelectedRange();
  selectedRange.load('address');
  return context.sync()
    .then(function () {
    console.log('The selected range is: ' + selectedRange.address);
  });
}).catch(function (error) {
  console.log('error: ' + error);
  if (error instanceof OfficeExtension.Error) {
    console.log('Debug info: ' + JSON.stringify(error.debugInfo));
  }
});

Office アドインの開発者ツールを理解する

Office アドインの開発者ツールを使用して、Office アドインを作成したり、Office の JavaScript API を利用したり、Office アドインマニフェストファイルを検証したりできます。このユニットでは、次のツールについて説明します。

Office アドイン用の Yeoman ジェネレーター
Visual Studio
Script Lab
マニフェストの検証

Office アドインの作成

Office アドイン用の Yeoman ジェネレーターまたは Visual Studio を使用して Office アドインを作成することができます。

ヒント

Office アドイン用の Yeoman ジェネレーターのインストールと詳細情報については、github.com/OfficeDev/generator-office を参照してください。

Office アドイン用の Yeoman ジェネレーター

Office アドイン用の Yeoman ジェネレーターを使用することで、Visual Studio Code やその他のエディターで管理することができる、Node.js Office アドインプロジェクトを作成できます。このジェネレーターは、次のような Office アドインを作成できます。

Excel
OneNote
Outlook
PowerPoint
Project
Word
Excel のカスタム関数

プロジェクトを作成するのに、HTML、CSS、および JavaScript を使用するのか、Angular または React を使用するのかを選択できます。 TypeScript も選択できます。

Yeoman ジェネレーターを使用して Office アドインプロジェクトを作成するには、次の手順を実行します。

ノードパッケージマネージャー (npm) を使用して、Yeoman と Office アドイン用の Yeoman ジェネレーターをグローバルにインストールするには、次のコマンドを実行します。
```
npm install -g yo generator-office
```
Yeoman ジェネレーターを使用してアドインプロジェクトを作成するには、次のコマンドを実行します。
```
yo office
```

Visual Studio

Visual Studio は、Excel、Word、PowerPoint、Outlook 用の Office アドインの作成に使用できます。 Office アドインプロジェクトは Visual Studio ソリューションの一部として作成されているため、ユーザーは Visual Studio の機能を使用できます。たとえば、[開始] や [F5] を選択して、アドインを IIS 上でローカルに自動的に実行できます。 Visual Studio を使用して作成した Office アドインプロジェクトは、HTML、CSS、JavaScript を使用します。

Visual Studio を使用して Office アドインを作成するには、新しい C# または Visual Basic プロジェクトを作成し、次のいずれかのプロジェクトの種類を選択します。

Excel Web アドイン
Outlook Web アドイン
PowerPoint Web アドイン
Word Web アドイン

Script Lab を使用して API を確認する

Script Lab は、Excel や Word などの Office プログラムで作業しているときに Office JavaScript スニペットを実行できるようにするアドインです。これは、AppSource から無料で利用でき、アドインで必要な機能のプロトタイプを作成したり検証したりする場合に、開発ツールキットに含めておくと便利なツールです。 Script Lab では、組み込みのサンプルのライブラリにアクセスして、簡単に API を試すことができます。また、独自のコードの開始点としてサンプルを使用することもできます。

次のビデオでは、Script Lab の実際の動作を紹介します。

Office アドインのマニフェストファイルの検証

Office アドインマニフェストの検証ツールは、アドインのマニフェストファイルを調べ、正確性と完全性を判断します。 Office アドイン用の Yeoman ジェネレーター (バージョン 1.1.17 以降) を使用してアドインプロジェクトを作成した場合は、そのプロジェクトのルートディレクトリで次のコマンドを実行してマニフェストを検証できます。

npm run validate

アドインプロジェクトの作成に Yeoman ジェネレーターを使用しなかった場合は、次の手順を実行してマニフェストを検証できます。

Node.js. をインストールします。
プロジェクトのルートディレクトリから次のコマンドを実行します。

重要

{{MANIFEST_FILE}} をマニフェストファイルの名前に置き換えます。
```
npx office-addin-manifest validate {{MANIFEST_FILE}}
```

Excel JavaScript API の機能を理解する

Excel JavaScript API を使用して、アドインの Excel ドキュメントへのアクセスを許可します。 Excel アドインで、ワークブックまたはスプレッドシートのコンテンツ、書式設定、および構造を管理できます。

Outlook JavaScript API の機能を理解する

Outlook JavaScript API は、アドインがユーザーのメールボックス、メッセージ、および Outlook の予定にアクセスできるようにします。 Outlook アドインは、メッセージまたは予定のコンテンツとプロパティを取得できます。アドインは、作成中のメッセージまたは予定のコンテンツ、書式設定、および構造も管理できます。

オブジェクトモデル

Outlook API を理解するには、まずメールボックスの主要なコンポーネントが互いにどのように関連しているかを確認します。

メールボックス オブジェクトを使用すると、認証の処理、選択したアイテムの管理、ユーザープロファイルの詳細の表示を行うことができます。
アイテム オブジェクトは、ユーザーが読んでいる、または作成している選択したメッセージまたは予定を表します。

Outlook API を使用して、電子メールまたは予定の多くのプロパティを管理できます。 API の多くは、ユーザーがいるモードを中心に編成されています。次の表は、アイテムの種類とモードをマップしています。

アイテムの種類	モード
メッセージ	読み取り作成
予定/会議	出席者 (読み取り) 開催者 (作成)

主な機能

作業ウィンドウアドインに加えて、コンテキストアドインとモジュールアドインを作成できます。このセクションでは、Outlook API のいくつかの主要な機能について説明します。

認証オプション
コンテキストアドイン
モジュールアドイン

認証

Outlook アドインは、インターネット上のどこからでも情報にアクセスできます。いくつかの例には、アドイン、内部ネットワーク、またはクラウド内の他の場所をホストするサーバーが含まれます。その情報が保護されている場合、アドインにはユーザーを認証する方法が必要になります。 Outlook アドインは、特定のシナリオに応じて、さまざまな認証メソッドを提供します。

Exchange のユーザー ID トークン

Exchange のユーザー ID トークンは、アドインがユーザーの ID を確立する方法を提供します。ユーザーの ID を確認することで、システムでユーザーを 1 回認証し、将来の要求に対する認証としてユーザー ID トークンを使用することができます。アドインが主に Exchange のオンプレミスのユーザーによって使用される場合、または管理する Microsoft 以外のサービスへのアクセスが必要な場合は、ユーザー ID トークンの使用を検討してください。アドインでは、getUserIdentityTokenAsync() を呼び出して Exchange のユーザー ID トークンを取得できます。

OAuth2 フローを使用してアクセストークンを取得する

アドインは、OAuth2 をサポートするサードパーティのサービスにアクセスして承認することもできます。アドインが制御外のサードパーティサービスにアクセスする必要がある場合は、OAuth2 トークンの使用を検討してください。このメソッドを使用すると、アドインは、たとえば displayDialogAsync() メソッドを使用して OAuth2 フローを初期化することにより、ユーザーにサービスへのサインインを求めます。

コールバックトークン

コールバックトークンは、Exchange Web サービス (EWS) または Outlook REST API を使用した、サーバーからユーザーのメールボックスへのアドインのアクセスを提供します。アドインは、getCallbackTokenAsync() メソッドの 1 つを使用して、コールバックトークンを取得します。アクセスのレベルは、アドインマニフェストで指定されたアクセス許可によって制御されます。

認証の概要

次の表は、各種類のアクセストークンをいつ使用するかをまとめたものです。

アクセストークン	アドインの使用
Exchange のユーザー ID トークン	主に Exchange のオンプレミスのユーザーが使用します。ユーザーが制御する Microsoft 以外のサービスにアクセスする必要があります。
OAuth2 アクセストークン	ユーザーの制御外のサードパーティサービスにアクセスする必要があります。
コールバックトークン	サーバーからユーザーのメールボックスにアクセスする必要があります。

コンテキストアドイン

コンテキストアドインは、メッセージまたは予定のテキストに基づいてアクティブ化する Outlook アドインです。 Bing マップや会議の候補など、Outlook で既定のコンテキストアドインを見たことがあるかもしれません。コンテキストアドインを使用すると、ユーザーはメッセージ自体から移動しなくてもそのメッセージに関連したタスクを開始できます。それにより、操作が簡単になると同時にユーザーエクスペリエンスが豊かになります。

次の表に、ユーザーの選択に基づくいくつかのタスク例を示します。

ユーザーの選択…	コンテキストアドインの操作
アドレス	その場所のマップを開きます。
文字列	会議の候補のアドインを開きます。
電話番号	連絡先に番号を追加します。

注:

現在、Android および iOS 用の Outlook では、コンテキストアドインをご利用いただけません。

次の画像は、Outlook に表示されるコンテキストアドインを示しています。

Outlook に表示されるコンテキストアドインの例のスクリーンショット。

Outlook に表示されるコンテキストアドイン

コンテキストアドインのマニフェストには、xsi:type 属性が DetectedEntity に設定されている ExtensionPoint 要素が含まれている必要があります。 ExtensionPoint 要素内で、アドインはアクティブ化できるエンティティまたは正規表現を指定します。エンティティを指定する場合、そのエンティティは Entities オブジェクトのどのプロパティであってもかまいません。

そのため、アドインマニフェストには種類 ItemHasKnownEntity または ItemHasRegularExpressionMatch のルールが含まれている必要があります。次の例では、アドインが電話番号を検出したときにメッセージをアクティブ化にするように指定する方法を示しています。

<ExtensionPoint xsi:type="DetectedEntity">
  <Label resid="contextLabel" />
  <SourceLocation resid="detectedEntityURL" />
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="PhoneNumber" Highlight="all" />
  </Rule>
</ExtensionPoint>

コンテキストアドインをアカウントに関連付けると、強調表示された状態のエンティティまたは正規表現をユーザーがクリックするとコンテキストアプリが自動的に起動します。

ユーザーは、既知のエンティティまたは開発者の正規表現のどちらかで、テキストを通じてコンテキストアドインを起動します。通常、ユーザーはエンティティが強調表示されていることでコンテキストアドインを特定します。

モジュールアドイン

モジュールアドインは、Outlook のナビゲーションバーのメール、タスク、および予定表の横に表示されます。アドインでは Outlook JavaScript API のすべての機能を使用できます。また、Outlook のリボンにコマンドボタンを作成することで、ユーザーはアドインの内容を操作できます。

注:

モジュールアドインは、Windows 用 Outlook 2016 以降でのみサポートされています。

次の画像は、モジュール拡張機能アドインの例を示しています。

Windows 上の Outlook のモジュールアドインの例のスクリーンショット。

Windows 上の Outlook のモジュールアドインの例

モジュールアドインを作成するには、アドインのマニフェストファイルにモジュール拡張機能のポイントを含めます。次の例は、モジュール拡張機能を定義するために調整されたマニフェストファイルのスニペットを示しています。

...
<!-- Add Outlook module extension point. -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides"
                  xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
                    xsi:type="VersionOverridesV1_1">

    <!-- Begin override of existing elements. -->
    <Description resid="residVersionOverrideDesc" />

    <Requirements>
      <bt:Sets DefaultMinVersion="1.3">
        <bt:Set Name="Mailbox" />
      </bt:Sets>
    </Requirements>
    <!-- End override of existing elements. -->

    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <!-- Set the URL of the file that contains the
               JavaScript function that controls the extension. -->
          <FunctionFile resid="residFunctionFileUrl" />

          <!-- Module extension point for a ModuleApp -->
          <ExtensionPoint xsi:type="Module">
            <SourceLocation resid="residExtensionPointUrl" />
            <Label resid="residExtensionPointLabel" />

            <CommandSurface>
              <CustomTab id="idTab">
                <Group id="idGroup">
                  <Label resid="residGroupLabel" />

                  <Control xsi:type="Button" id="group.changeToAssociate">
                    <Label resid="residChangeToAssociateLabel" />
                    <Supertip>
                      <Title resid="residChangeToAssociateLabel" />
                      <Description resid="residChangeToAssociateDesc" />
                    </Supertip>
                    <Icon>
                      <bt:Image size="16" resid="residAssociateIcon16" />
                      <bt:Image size="32" resid="residAssociateIcon32" />
                      <bt:Image size="80" resid="residAssociateIcon80" />
                    </Icon>
                    <Action xsi:type="ExecuteFunction">
                      <FunctionName>changeToAssociateRate</FunctionName>
                    </Action>
                  </Control>
                </Group>
                <Label resid="residCustomTabLabel" />
              </CustomTab>
            </CommandSurface>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>

    <Resources>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Outlook アドインの開発の開始

Outlook アドインを開発するには、次のものを使用します。

Office アドイン用の Yeoman ジェネレーター
Visual Studio

テンプレートをベースとして使用し、機能を追加できます。

Word JavaScript API の機能を理解する

Word JavaScript API を使用して、アドインの Word ドキュメントへのアクセスを許可します。 Word アドインで、ドキュメントのコンテンツ、書式設定、および構造を管理できます。

オブジェクトモデル

Word API を理解するには、ドキュメントの主要なコンポーネントが互いにどのように関連しているかを確認する必要があります。

ドキュメントには本文と少なくとも 1 つのセクションが含まれます。
本文には次のものが含まれます。
- 段落 (1 つ以上)
- 表 (1 つ以上)
- リスト (1 つ以上)
- テキスト
- 画像やリストなどのオブジェクト
セクションでは、その本体、ヘッダー、およびフッターへアクセスできます。

重要なシナリオ

このセクションでは、Word API のいくつかの重要なシナリオについて説明します。

ドキュメントのテキストを操作する
検索

注:

Office.js API を使用して、既存のドキュメント全体に簡単な書式設定を適用できます。ただし、複雑な書式設定を適用する場合やリッチコンテンツオブジェクトを使用する場合は、Office Open XML (OOXML) を使用してこれらの効果を作成できます。 OOXML の機能の例には、テキストまたは画像に影を付ける、テキストボックスを図形に強制する、Excel グラフを Word ドキュメントにライブグラフとして挿入することが含まれます。これはより高度なスキルなので、このトピック全体を網羅するのではなく、OOXML に精通した開発者向けに説明します。

ドキュメントテキストの操作

Word アドインは、Office.onReady() イベントハンドラーを使用して開始します。アドインが Word 2016 以降を対象とする場合、Word.run() メソッドを呼び出して Word JavaScript API を実行します。アドインは、コンテキストオブジェクトがパラメータとして渡されることを待つ関数を Word.run() に渡す必要があります。コンテキストオブジェクトを使用すると、アドインが Word ドキュメントを操作できます。コンテキストオブジェクトを使用して、Word ドキュメントに必要なプロキシオブジェクトを作成し、使用する任意のプロパティをプロキシに読み込むことができます。これらのプロパティを使用して実行する操作をプログラムすることもできます。いつものように、context.sync() コマンドはプロキシオブジェクトと Word ドキュメント内のオブジェクト間の状態を同期します。

次の例は、Word ドキュメントの本文テキストの後にテキストを挿入するコードを示しています。簡単にするために、このサンプルでは Office.onReady() コードを省略し、Word.run() コードブロック内のコードに重点を置きます。

// Run a batch operation against the Word JavaScript API.
Word.run(function (context) {
  // Create a proxy object for the document body.
  var body = context.document.body;

  // Queue a command to load the text property of the proxy body object.
  body.load("text");

  // Queue a command to insert text into the end of the Word document body.
  body.insertText('This is text inserted after loading the body.text property',
                  Word.InsertLocation.end);

  // Synchronize the document state by executing the queued commands,
  // and return a promise to indicate task completion.
  return context.sync().then(function () {
    console.log("Body contents: " + body.text);
  });
})

検索

API を使用して、基準を満たすテキストをドキュメントで検索できます。また、特定の種類のコンテンツ (段落や表など) に検索範囲を設定することもできます。

次のコード例では、「video you (ビデオあなた)」というテキストを検索して句読点を無視します。テキストが見つかった場合、一致は太字で表示され、黄色で強調表示され、フォントの色は紫色に設定されます。

// Run a batch operation against the Word object model.
Word.run(function (context) {
  // Queue a command to search the document and ignore punctuation.
  var searchResults = context.document.body.search('video you', {ignorePunct: true});

  // Queue a command to load the search results and get the font property values.
  context.load(searchResults, 'font');

  // Synchronize the document state by executing the queued commands,
  // and return a promise to indicate task completion.
  return context.sync().then(function () {
      console.log('Found count: ' + searchResults.items.length);

      // Queue a set of commands to change the font for each found item.
      for (var i = 0; i < searchResults.items.length; i++) {
        searchResults.items[i].font.color = 'purple';
        searchResults.items[i].font.highlightColor = '#FFFF00'; // Yellow
        searchResults.items[i].font.bold = true;
      }

      // Synchronize the document state by executing the queued commands,
      // and return a promise to indicate task completion.
      return context.sync();
  });
})
.catch(function (error) {
  console.log('Error: ' + JSON.stringify(error));
  if (error instanceof OfficeExtension.Error) {
    console.log('Debug info: ' + JSON.stringify(error.debugInfo));
  }
});

Word アドインの開発の開始

Word アドインを開発するには、次を使用します。

Office アドイン用の Yeoman ジェネレーター
Visual Studio

API の詳細については、Script Lab のアドインをお勧めします。そこでは、多くの TypeScript および JavaScript スニペットが表示され、アドイン全体を作成することなく Word ドキュメントを試すことができます。

カスタム関数の機能を理解する

カスタム関数は、作業ウィンドウ同様、他のアドインの操作とは別のランタイムで実行されるので、固有の機能と制限があります。

カスタム関数の機能

SUM() などの組み込み Excel 関数のようにアクセスできるカスタム JavaScript 関数または TypeScript 関数を作成できます。また、タイマーに基づいて値を返す、ストリーミングカスタム関数も作成できます。たとえば、セルの現在の時刻値を、1 秒ごとに更新できます。同様に、カスタム関数を使用してネットワークを呼び出すこともできます。

カスタム関数 JavaScript の例

次のコード例では、2 つの数値を受け取り、その合計を返すカスタム関数 add() を定義します。

/**
 * Adds two numbers.
 * @customfunction
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

JSDoc コードのコメントの説明

コードコメントの JSDoc タグは、Excel にカスタム関数を記述する JSON メタデータファイルを生成するために使用されます。 JSON メタデータファイルによって、Excel はユーザーに正確な情報を提示し、想定されるパラメーターをカスタム関数に渡すことができます。

@customfunction: 最初に宣言され、そのカスタム関数を指定します。必須です。
@param: パラメーターを記述します。関数によって定義される各パラメーターに含まれます。
@returns: 関数の出力内容を記述します。

注:

コメントの説明 "Adds two numbers."も Excel の JSON メタデータファイルに追加され、ユーザーがカスタム関数を表示したときに、表示されるようになります。

カスタム関数ランタイムの制限

カスタム関数ランタイムは JavaScript のみを実行します。ブラウザーベースの JavaScript ランタイム環境とは異なり、ドキュメントオブジェクトモデル (DOM) やローカルストレージはありません。つまり、jQuery などの DOM を使用するライブラリを読み込むことはできません。また、作業ウィンドウからドキュメントを操作するように、Office.js API にアクセスしてドキュメントを操作することはできません。代わりに、カスタム関数ランタイムは、迅速な計算を実行するなどのタスクに合わせて最適化されています。通常、Excel の書式設定ツールなどの Office.js API を使用する必要はありません。

カスタム関数には、カスタム関数ランタイムを読み込むページがあります。カスタム関数ランタイムには UI が用意されていないため、Web ページは表示されません。カスタム関数ランタイムのライブラリを読み込む Web ページには、次のスクリプトタグがあります。

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>

通常、カスタム関数は同じアドインで作業ウィンドウに結合されます。 Office アドイン用の Yeoman ジェネレーターを使用してアドインプロジェクトを作成する場合、プロジェクトにはカスタム関数用の Web ページと、作業ウィンドウ用の UI を含む Web ページが用意されます。

ストレージ API を使用して作業ウィンドウを操作する

カスタム関数コードと作業ウィンドウコード (Office.js を使用) は、お互いに直接呼び出しやデータのやりとりを行うことはできません。ただし、ストレージ API を使用してデータを共有できます。ストレージ API を使用する場合の一般的なシナリオは、アドインがセキュリティで保護されたネットワークリソースにアクセスするために、セキュリティトークンを共有する必要がある場合です。ユーザーは最初にユーザーがサインインする必要があるカスタム関数を呼び出す可能性があります。認証が完了すると、セキュリティトークンが送信されます。そして、後でユーザーが作業ウィンドウを開くときに、もう一度サインインする必要がないように、ストレージ API を使用してセキュリティトークンを共有します。

代わりに、ユーザーが最初に作業ウィンドウを開く可能性もあります。この場合、作業ウィンドウでユーザーはサインインし、ストレージ API を介してセキュリティトークンを共有します。後でカスタム関数を使用する場合は、カスタム関数がストレージ API を通じてセキュリティトークンを取得します。

ストレージ API の使用例

次のコード例は、ユーザーによって作成された値の格納と取得方法を示しています。

/**
 * @customfunction
 * @description Stores a value in OfficeRuntime.storage.
 * @param {any} key Key in the key-value pair you will store.
 * @param {any} value Value in the key-value pair you will store.
 */
function storeValue(key, value) {
  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
    return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
    return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

/**
 * @customfunction
 * @description Gets value from OfficeRuntime.storage.
 * @param {any} key Key of item you intend to get.
 */
function getValue(key) {
  return OfficeRuntime.storage.getItem(key);
}

ダイアログ API

カスタム関数は Office.js API にアクセスできないので、独自のダイアログ API が用意されています。ただし、機能は似ています。最も一般的なシナリオでは、ユーザーがサインインするダイアログを開き、セキュリティトークンを受け取ります。

次のコード例は、カスタム関数から Web ダイアログを表示する方法を示しています。

OfficeRuntime.displayWebDialog('https://myDomain/myDialog.html', {height: 30, width: 20});

カスタム関数プロジェクトの作成

Office アドイン用の Yeoman ジェネレーターを使用して、カスタム関数プロジェクトを作成できます。yo office を実行してジェネレーターを開始し、[Excel Custom Functions add-in project] (Excel カスタム関数のアドインプロジェクト) オプションを選択します。作成されたプロジェクトには、作業ウィンドウのソースファイル用の /src/taskpane/ フォルダーと、カスタム関数ソースファイル用の /src/functions フォルダーが含まれます。

注:

Visual Studio でカスタム関数プロジェクトを作成することはできません。

まとめ

このユニットでは、Excel、Outlook、Word 用の Office アドインのプログラミングモデル、開発者ツール、Office JavaScript API の機能について説明しました。

Office アドインプログラミングモデルと Office JavaScript API

続行

Office アドイン プログラミング モデルを理解する

Office JavaScript API の要件セット

Office JavaScript API を使用する

プロキシ オブジェクトを使用して非同期呼び出しを行う

Office アドインの開発者ツールを理解する

Office アドインの作成

Office アドイン用の Yeoman ジェネレーター

Visual Studio

Script Lab を使用して API を確認する

Office アドインのマニフェスト ファイルの検証

Excel JavaScript API の機能を理解する

Outlook JavaScript API の機能を理解する

オブジェクト モデル

主な機能

認証

Exchange のユーザー ID トークン

OAuth2 フローを使用してアクセス トークンを取得する

コールバック トークン

認証の概要

コンテキスト アドイン

モジュール アドイン

Outlook アドインの開発の開始

Word JavaScript API の機能を理解する

オブジェクト モデル

重要なシナリオ

ドキュメント テキストの操作

検索

Word アドインの開発の開始

カスタム関数の機能を理解する

カスタム関数の機能

カスタム関数 JavaScript の例

JSDoc コードのコメントの説明

カスタム関数ランタイムの制限

ストレージ API を使用して作業ウィンドウを操作する

ストレージ API の使用例

ダイアログ API

カスタム関数プロジェクトの作成

まとめ

Office アドイン プログラミング モデルと Office JavaScript API

フィードバック

Office アドインプログラミングモデルを理解する

プロキシオブジェクトを使用して非同期呼び出しを行う

Office アドインのマニフェストファイルの検証

オブジェクトモデル

OAuth2 フローを使用してアクセストークンを取得する

コールバックトークン

コンテキストアドイン

モジュールアドイン

オブジェクトモデル

ドキュメントテキストの操作

Office アドインプログラミングモデルと Office JavaScript API