Office JavaScript API ライブラリの参照

Office JavaScript API ライブラリは、アドインが Office アプリケーションと対話するために使用できる API を提供します。 このライブラリを参照する最も簡単な方法は、HTML ページの<head>セクション内に次の <script> タグを追加して、コンテンツ配信ネットワーク (CDN) を使用することです。

<head>
    ...
    <script src="https://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>
</head>

この方法では、アドインを初めて読み込むときに、Office JavaScript API ファイルをダウンロードしてキャッシュします。 これにより、アドインが、指定したバージョン用の Office.js とそれに関連するファイルの最新実装が使用されるようになります。

CDN では、Microsoft 365 アプリとサービスの統合ドメインの一部として officeapis.public.onecdn.static.microsoft ドメインが使用されます。

Office.js 固有の Web API の動作

Office.js では、replaceState および pushState の既定の Window.history メソッドが null に置き換えられます。 アドインがこれらのメソッドに依存している場合は、Office.js ライブラリ参照を次の回避策に置き換えます。

<script type="text/javascript">
    // Cache the history method values.
    window._historyCache = {
        replaceState: window.history.replaceState,
        pushState: window.history.pushState
    };
</script>

<script type="text/javascript" src="https://officeapis.public.onecdn.static.microsoft/1/office.js"></script>

<script type="text/javascript">
    // Restore the history method values after loading Office.js
    window.history.replaceState = window._historyCache.replaceState;
    window.history.pushState = window._historyCache.pushState;
</script>

この回避策を提案し検証してくださった @stepper と Stack Overflow コミュニティ に感謝します。

API のバージョン管理と下位互換性

前の HTML スニペットでは、CDN URL の前のoffice.js/1/が、Office.js のバージョン 1 内の最新の増分リリースを指定します。 Office JavaScript API は下位互換性を維持するため、最新リリースでは、バージョン 1 の初期に導入された API メンバーが引き続きサポートされます。

Office アドインを Microsoft Marketplace に公開する場合は、この CDN リファレンスを使用する必要があります。 ローカル参照は、内部、開発、およびデバッグのシナリオにのみ使用してください。

TypeScript プロジェクトでの IntelliSense の有効化

前述のように Office JavaScript API を参照する以外に、 DefinitelyTyped のタイプ定義を使用して TypeScript アドイン プロジェクトで IntelliSense を有効にすることもできます。 これを行うには、プロジェクト フォルダーのルートから Node 対応のシステム プロンプト (または git bash ウィンドウ) で次のコマンドを実行します。 (npm を含む) Node.js をインストールしておく必要があります。

npm install --save-dev @types/office-js

プレビュー API

Microsoft は、新しい JavaScript API を "プレビュー" で最初に導入します。十分なテストとユーザー フィードバックの後、API は特定の番号付き要件セットの一部になります。

他の Microsoft 365 環境の CDN 参照

21Vianet は、ライセンスを取得した Microsoft テクノロジを搭載した Office 365 サービスを運営および管理し、現地の法律および規制に準拠した中国向けの Office 365 サービスを提供しています。 このクラウド環境内で使用するために開発されたアドインは、対応する CDN を使用する必要があります。 標準 CDN リファレンスの代わりに https://appsforoffice.cdn.partner.office365.cn/appsforoffice/lib/1/hosted/office.js を使用します。 これにより、継続的なコンプライアンスが確保され、アドインのパフォーマンスが向上します。

従来の CDN エンドポイントを更新する

以前は、Office.js ライブラリは https://appsforoffice.microsoft.com/lib/1/hosted/office.js エンドポイントから提供されていました。 新しい Office.js CDN エンドポイントに切り替えるには、各アドイン ページの Office.js スクリプト参照を https://appsforoffice.microsoft.com/lib/1/hosted/office.js から https://officeapis.public.onecdn.static.microsoft/1/office.js に更新します。 新しいエンドポイントは、現在の Office.js リリースと同じように機能しますが、追加のセキュリティで保護された既定値を有効にします。 切り替え前:

• アドインが、以前に自動的に読み込まれた Microsoft Ajax グローバル Office.js 依存している場合は、その依存関係をサポートされている代替ライブラリに置き換えるか、必要なライブラリを直接読み込んで管理します。
• アドインで ExecuteFunction コマンドを使用している場合は、 Office.actions.associate(...)を使用してすべてのコマンド ハンドラーを登録します。
• アドインまたはorganizationで制限的なコンテンツ セキュリティ ポリシーまたは信頼できる種類の設定を使用している場合は、新しいエンドポイントと Office.js 信頼できる種類のポリシーが許可されていることを確認します。
• *.static.microsoft該当するネットワーク許可リストで許可されていることを確認します。
• アクティブ化、コマンド、ダイアログなど、サポートされている Office アプリケーションと環境でアドインをテストします。

関連項目

• Office JavaScript API について
• Office の JavaScript API
• 政府機関向けクラウドへの Office アドインの展開に関するガイダンス
• Microsoft Office JavaScript (Office.js) API ライブラリに関するマイクロソフト ソフトウェア ライセンス条項