Office アドインを開発する
ヒント
この記事を読む前に、「Office Add-ins platform overview (Office アドイン プラットフォームの概要)」をご覧ください。
すべての Office アドインは、Office アドイン プラットフォーム上で構築します。 どのようなアドインを構築する場合でも、アプリケーションやプラットフォームの可用性、Office JavaScript API のプログラミング パターン、アドインの設定と機能をマニフェスト ファイル上で指定する方法、マニフェストファイルのcapabilities、UIとユーザーエクスペリエンスをデザインする方法など、重要な概念を理解する必要があります。 開発に関するこれらの中心概念については、ドキュメントの開発ライフサイクル>開発セクションを参照してください。 構築するアドインに対応するアプリケーション固有のドキュメント (たとえば、 Excel) を詳しく見る前に、ここに記載される情報を確認してください。
Office アドインを作成する
Office アドインは、Office アドイン、Visual Studio、または Teams Toolkit の Yeoman ジェネレーターを使用して作成できます。
Yeoman ジェネレーター
Office アドイン用の Yeoman ジェネレーターを使用することで、Visual Studio Code やその他のエディターで管理することができる、Node.js Office アドイン プロジェクトを作成できます。 ジェネレーターでは、次のいずれのホスト用の Office アドインも作成できます。
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Excel のカスタム関数
HTML、CSS、JavaScript (または TypeScript) を使用するか、Reactを使用してプロジェクトを作成します。 Reactを選択した場合は、JavaScript と Typescript のどちらかを選択することもできます。 Yeoman ジェネレーターを使用してアドインを作成する方法については、「Office アドイン用の Yeoman ジェネレーター」を参照してください。
Visual Studio
Visual Studio は、Excel、Outlook、Word、および PowerPoint 用の Office アドインの作成に使用できます。 Office アドイン プロジェクトは Visual Studio ソリューションの一部として作成され、HTML、CSS、および JavaScript が使用されます。 Visual Studio を使用してアドインを作成する方法については、「Visual Studio を使用して Office アドインを開発する」を参照してください。
注:
Visual Studio を使用して Office アドインを作成することは可能ですが、Yeoman ジェネレーターを使用すると、いくつかの注目すべき方法で開発者のエクスペリエンスが向上します。
Yeoman ジェネレーターは、Visual Studio が Office アドイン プロジェクト用に提供するよりも幅広いプロジェクトの種類、フレームワーク、および言語のオプションを提供します。
Yeoman ジェネレーターのプロジェクト テンプレートは、Visual Studio のプロジェクト テンプレートよりも頻繁に更新されます。
Teams ツールキット
Teams ツールキットを使用すると、ほぼすべての種類の Teams アプリを作成できます。これは、Teams アプリケーションを拡張しない拡張機能を含む、Microsoft 365 のすべての拡張機能を含む用語です。 アドインの作成の詳細については、「Teams Toolkit を使用した Office アドイン プロジェクトの作成」を参照してください。
Office アドインの 2 つの部分について理解する
Office アドインは、2 つの部分から構成されます。
アドインの設定と機能を定義するアドイン マニフェスト。
作業ウィンドウ、コンテンツ アドイン、ダイアログ ボックスなど、アドインの UI と機能を定義する Web アプリケーション。
Web アプリケーションでは、Office JavaScript API を使用することで、アドインが実行されている Office ドキュメント内のコンテンツを操作します。 アドインは、外部 Web サービスの呼び出しやユーザー認証の要求など、Web ページが一般的に行うその他の機能も実行することができます。
アドインの設定と機能を定義する
Office アドインのマニフェストは、アドインの設定と機能を定義します。 次のような要素を定義するには、マニフェストを構成します。
- アドインを説明するメタデータ (ID、バージョン、説明、表示名、既定のロケールなど)。
- アドインが実行される Office アプリケーション。
- アドインに必要なアクセス許可。
- アドインが作成するカスタム UI (カスタム タブやカスタム リボン ボタンなど) を含む、アドインと Office の統合方法。
- ブランドおよびコマンドの図像としてアドインで使用される画像の場所。
- アドインの寸法 (例: コンテンツ アドインの寸法、Outlook アドインに対して要求される高さなど)。
- メッセージや予定のコンテキストでアドインをアクティブにさせるタイミングを指定するルール (Outlook アドインのみ)。
- キーボード ショートカット (Excel のみ)。
マニフェストの詳細については、「 Office アドイン マニフェスト」を参照してください。
Office ドキュメント内のコンテンツを操作する
Office アドインでは、Office JavaScript API を使用することで、アドインが実行されている Office ドキュメント内のコンテンツを操作できます。
Office JavaScript API ライブラリへのアクセス
Office JavaScript API ライブラリには、https://appsforoffice.microsoft.com/lib/1/hosted/office.js にある Office JS コンテンツ配信ネットワーク (CDN) を経由してアクセスできます。 アドインの Web ページで Office JavaScript API を使用するには、ページの <head> タグにある <script> タグに含まれている CDN を参照する必要があります。
<head>
...
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
</head>
注:
プレビュー API を使用するには、CDN (https://appsforoffice.microsoft.com/lib/beta/hosted/office.js) にある Office JavaScript API ライブラリのプレビュー バージョンを参照します。
IntelliSense の入手方法など、Office JavaScript API ライブラリにアクセスする方法の詳細については、「Office JavaScript API ライブラリをそのコンテンツ配信ネットワーク (CDN) から参照する」をご覧ください。
API モデル
Office JavaScript API には、2 つの異なるモデルがあります。
アプリケーション固有 API では、特定の Office アプリケーションにネイティブなオブジェクトを操作するために使用できる、厳密に型指定されたオブジェクトが提供されます。 たとえば、Excel JavaScript API を使用して、ワークシート、範囲、テーブル、グラフなどにアクセスすることができます。 現在、アプリケーション固有の API は、次の Office アプリケーションで使用できます。
この API モデルでは Promise が使用され、Office アプリケーションに送信する各要求で複数の操作を指定することが可能です。 この方法によるバッチ操作を行うと、Web 上の Office アプリケーションのパフォーマンスが大幅に向上します。 Office 2016 では、アプリケーション固有の API が導入されました。
注:
Visio 用のアプリケーション固有の API もありますが、SharePoint Online ページでのみ使用して、ページに埋め込まれている Visio ダイアグラムを操作できます。 Office Web アドインは Visio ではサポートされていません。
この API モデルの詳細については、「アプリケーション固有の API モデルの使用」を参照してください。
共通 API を使用すると、複数の種類の Office アプリケーション間で共通の UI、ダイアログ、クライアント設定などの機能にアクセスすることができます。 この API モデルでは コールバック が使用され、Office アプリケーションに送信する各要求で 1 つの操作のみを指定できます。 一般的な API は Office 2013 で導入され、サポートされている Office アプリケーションとの対話に使用できます。 Outlook、PowerPoint、Project を操作するための API を含む、共通 API オブジェクト モデルの詳細については、「共通 JavaScript API オブジェクト モデル」を参照してください。
注:
共有ランタイムのないカスタム関数は、計算の実行を優先する JavaScript 専用ランタイムで実行されます。 これらの関数は、少し異なるプログラミング モデルを使用します。
API 要件セット
要件セットは、API メンバーの名前付きグループです。 要件セットは、ExcelApi 1.7 要件セット (Excel でのみ使用可能な API のセット) などのように Office アプリケーションに固有の場合もあれば、DialogApi 1.1 要求セット (ダイアログ API がサポートされているすべての Office アプリケーションで使用できる API セット) などのように複数のアプリケーションで共通の場合もあります。
アドインは、要求セットを使用することで、アドインが使用する必要がある API メンバーが Office アプリケーションでサポートされているかどうかを判別できます。 詳細については、「Office アプリケーションと API 要件を指定する」を参照してください。
要件セットのサポートは、Office アプリケーション、バージョン、プラットフォームごとに異なります。 各 Office アプリケーションでサポートされているプラットフォーム、要求セット、および共通 API の詳細については、「Office アドインの Office クライアント アプリケーションとプラットフォームの可用性」を参照してください。
Script Lab を使用して API を調べる
Script Lab は、Excel や Word などの Office プログラムでの作業中に Office JavaScript API を調査し、コード スニペットを実行できるようにするアドインです。 これは、AppSource から無料で利用でき、アドインで必要な機能のプロトタイプを作成したり検証したりする場合に、開発ツールキットに含めておくと便利なツールです。 Script Lab では、組み込みのサンプルのライブラリにアクセスして、簡単に API を試すことができます。また、独自のコードの開始点としてサンプルを使用することもできます。
次の 1 分間のビデオで、Script Lab の実際の動作をご覧ください。
Script Lab の詳細については、「Script Lab を使用して Office JavaScript API を調べる」を参照してください。
Office UI をカスタマイズする
Office アドインは、作業ウィンドウ、コンテンツ アドイン、ダイアログ ボックスなど、アドイン コマンドや HTML コンテナーを使用 Office UI を拡張することができます。
アドイン コマンド を使用すると、Office の既定のリボンにカスタム タブ、ボタン、メニューを追加したり、ユーザーが Office ドキュメント内のテキストまたは Excel 内のオブジェクトを右クリックした際に表示される既定のコンテキスト メニューを拡張したりすることができます。 ユーザーがアドイン コマンドを選択すると、アドイン コマンドで指定されているタスク (JavaScript コードの実行、作業ウィンドウを開く、ダイアログ ボックスの起動など) が実行されます。
作業ウィンドウ、コンテンツ アドイン、ダイアログ ボックスなどの HTML コンテナーを使用すると、カスタム UI を表示させたり Office アプリケーション内で追加機能を表示させたりすることができます。 各作業ウィンドウ、コンテンツ アドイン、またはダイアログ ボックスのコンテンツと機能は、指定した Web ページに由来します。 これらの Web ページでは、Office JavaScript API を使用することで、アドインが実行されている Office ドキュメントのコンテンツを操作できます。また、外部 Web サービスの呼び出しやユーザー認証の要求など、Web ページが一般的に行うその他の機能も実行できます。
次の図は、リボンのアドイン コマンド、ドキュメントの右側にある作業ウィンドウ、ドキュメント上のダイアログ ボックスまたはコンテンツ アドインを示しています。
Office UI の拡張とアドインのUXのデザインに関する詳細については、「Office アドイン用の Office UI 要素」を参照してください。
次の手順
この記事では、Office アドインの異なる作成方法を説明し、 アドインがOffice UIを拡張する方法やAPIセットの説明、Office JavaScript APIの探索をするための有益なツールとしてScript Labを紹介し、アドイン機能のプロトタイプ作成の説明を行いました。 初歩的な情報の説明は以上になります。Office アドインの行程を先に進むには、 次の手順を実行してください。
Office アドインを作成する
5 分間のクイック スタートを完了することで、Excel、OneNote、Outlook、PowerPoint、Project、または Word 用の基本的なアドインを簡単に作成することができます。 以前にクイック スタートを完了している場合で、より複雑なアドインを作成したい場合は、チュートリアルを試してみてください。
詳細情報
Office アドインの開発、テスト、公開の詳細については、このドキュメントを参照してください。
ヒント
どのようなアドインを構築する場合でも、このドキュメントの 「開発ライフサイクル」セクションに記載する情報に加え、構築するアドインの種類に対応するアプリケーション固有のセクション (たとえば、Excel) に記載する情報を使用してください。
関連項目
Office Add-ins
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示