基本的に Office アドインは、ブラウザーの iframe または webview コントロールのステートレス環境で実行される Web アプリケーションです。 簡潔にするために、この記事では "ブラウザー コントロール" を "ブラウザーまたは Webview コントロール" という意味で使用します。 アドインを使用する場合は、セッション間で特定の操作または機能の継続性を維持するために、データを保持する必要がある場合があります。 たとえば、ユーザーの優先するビューや既定の場所など、次に初期化するときに保存して再読み込みする必要があるカスタム設定や他の値がアドインにある場合があります。 データを永続化するには、次の操作を行います。
- 基になるブラウザー コントロールによって提供される手法を使用します。
- データを格納する Excel、Word、および Outlook 用のアプリケーション固有の Office JavaScript API を使用します。
アドインでユーザー設定や会話履歴などのユーザー レベルのデータを保持する必要がある場合は、ブラウザー ストレージだけに依存するのではなく、ユーザーの ID に関連付けられたオンライン データベースを使用します。 この方法では、ローカル ブラウザー ストレージがクリアされたり使用できなくなったりした場合でも、セッションやドキュメント間でデータを使用できるようになります。 たとえば、 SSO を使用してユーザーの ID を取得し、データベース内のユーザーのセーブ データとその ID を関連付けることができます。
注:
この記事は、同じ Office アプリケーションで状態を保持することにのみ適用されます。 Office アプリケーション間で状態を保持または共有するために、Cookie やlocalStorageを使用しないでください (たとえば、データを Word に保存して Excel で読み取ろうとしないでください)。 アプリ間の永続化はサポートされておらず、どのプラットフォームでも動作することが保証されていません。
ブラウザーのストレージ
ブラウザーの Cookie や HTML5 Web ストレージ (localStorage または sessionStorage) など、基になるブラウザー コントロールのツールを使用して、アドイン インスタンス間でデータを保持します。
注:
ブラウザーのストレージは、ブラウザーまたは webview プロファイルに関連付けられており、Office アドインのキャッシュ消去操作を使用するなど、ユーザーがクリアできます。 これは、重要なユーザー データの唯一の永続的なコピーではなく、一時データまたは回復可能なデータ、またはローカル キャッシュに使用します。
一部のブラウザーまたはユーザーのブラウザー設定によって、ブラウザー ベースのストレージ手法がブロックされる場合があります。 「Web Storage API の使用」に記載されているように、可用性をテストします。
記憶域のパーティション分割
プライベート データはパーティション分割された localStorageに格納します。
Office.context.partitionKey をローカル ストレージのキーとして使用します。 この方法により、ローカル ストレージに格納されているデータは同じコンテキストでのみ使用できるようになります。
注:
パーティション キーは、Windows 上の Office の webview コントロールなど、パーティション分割のない環境では定義されていません。 パーティション キーが定義されている場合、パーティション キーは次の 2 つのドメインのハッシュです。
- トップレベル ブラウザー ウィンドウがあるドメイン (Excel on the web の場合は
excel.cloud.microsoftなど)。 - アドインのドメイン (
myAddin.contoso.comなど)。
したがって、次の組み合わせごとに異なるパーティションが作成されます。
excel.cloud.microsoft+myAddin.contoso.comword.cloud.microsoft+myAddin.contoso.comword.cloud.microsoft+myOtherAddin.contoso.com
次の例は、 localStorage でパーティション キーを使用する方法を示しています。
// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");
// ...
// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);
// ...
function setInLocalStorage(key: string, value: string) {
const myPartitionKey = Office.context.partitionKey;
// Check if local storage is partitioned.
// If so, use the partition to ensure the data is only accessible by your add-in.
if (myPartitionKey) {
localStorage.setItem(myPartitionKey + key, value);
} else {
localStorage.setItem(key, value);
}
}
function getFromLocalStorage(key: string) {
const myPartitionKey = Office.context.partitionKey;
// Check if local storage is partitioned.
if (myPartitionKey) {
return localStorage.getItem(myPartitionKey + key);
} else {
return localStorage.getItem(key);
}
}
Chrome や Edge など、Chromium ベースのブラウザーのバージョン 115 以降では、特定のサイドチャネルクロスサイト追跡を防ぐためにストレージのパーティション分割が有効になっています (Microsoft Edge ブラウザー ポリシーも参照してください)。 Office キーベースのパーティション分割と同様に、ローカル ストレージなどのストレージ API によって格納されたデータは、同じ生成元および同じトップレベル サイトのコンテキストでのみ使用できます。
アプリケーション固有の設定と永続化
Excel、Word、および Outlook には、設定やその他のデータを保存するためのアプリケーション固有の API が用意されています。 アドインが一貫したパターンに従い、対象のアプリケーション用に最適化されるように、 この記事で後述する一般的な API ではなく、これらの API を使用します。
Excel と Word の設定
Excel と Word 用のアプリケーション固有の JavaScript API も、カスタム設定へのアクセスを提供します。 設定は、1 つの Excel ファイルとアドインのペアリングに固有です。 詳細については、「Excel.SettingCollection」および「Word」を参照してください。SettingCollection.
次の例は、Excel で設定を作成してアクセスする方法を示しています。 このプロセスは、Workbook.settings ではなく Document.settings を使用する Word でも機能的に同等です。
await Excel.run(async (context) => {
const settings = context.workbook.settings;
settings.add("NeedsReview", true);
const needsReview = settings.getItem("NeedsReview");
needsReview.load("value");
await context.sync();
console.log("Workbook needs review : " + needsReview.value);
});
Excel および Word のカスタム XML データ
Open XML .xlsx および .docx ファイル形式を使用すると、アドインで Excel ブックまたは Word ドキュメントにカスタム XML データを埋め込むことができます。 このデータは、アドインとは関係なくファイルと共に保持されます。
A Word.ドキュメントと Excel.Workbook には、CustomXmlPartsの一覧であるCustomXmlPartCollectionが含まれています。 これにより、XML 文字列と対応する一意の ID へのアクセスが提供されます。 これらの ID を設定として保管することにより、アドインはセッション間で XML パーツへのキーを保持できます。
次のサンプルでは、Excel ブックでカスタム XML パーツを使用する方法を示します。 最初のコード ブロックでは、XML データを埋め込む方法を示します。 レビュー担当者のリストを保管してから、ブックの設定を使用して XML の id を保存して、後から取得できるようにします。 2 番目のブロックでは、後からその XML にアクセスする方法が示されています。 "ContosoReviewXmlPartId" 設定がロードされ、ブックの customXmlParts に渡されます。 それから、XML データがコンソールに出力されます。 このプロセスは、Workbook.customXmlParts ではなく Document.customXmlParts を使用する Word でも機能的に同等です。
await Excel.run(async (context) => {
// Add reviewer data to the document as XML
const originalXml = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
const customXmlPart = context.workbook.customXmlParts.add(originalXml);
customXmlPart.load("id");
await context.sync();
// Store the XML part's ID in a setting
const settings = context.workbook.settings;
settings.add("ContosoReviewXmlPartId", customXmlPart.id);
});
注:
CustomXMLPart.namespaceUri にデータが入れられるのは、トップレベルのカスタム XML 要素に xmlns 属性が含まれている場合に限ります。
Excel と Word のカスタム プロパティ
Excel.DocumentProperties.custom と Word.DocumentProperties.customProperties プロパティは、ユーザー定義プロパティのキーと値のペアのコレクションを表します。 次の Excel の例は、値 "Hello" を持つ Introduction という名前のカスタム プロパティを作成して取得する方法を示しています。
await Excel.run(async (context) => {
const customDocProperties = context.workbook.properties.custom;
customDocProperties.add("Introduction", "Hello");
await context.sync();
});
// ...
await Excel.run(async (context) => {
const customDocProperties = context.workbook.properties.custom;
const customProperty = customDocProperties.getItem("Introduction");
customProperty.load(["key", "value"]);
await context.sync();
console.log("Custom key : " + customProperty.key); // "Introduction"
console.log("Custom value : " + customProperty.value); // "Hello"
});
ヒント
Excel では、 Worksheet.customProperties プロパティを使用してワークシート レベルでカスタム プロパティを設定することもできます。 これらのプロパティはドキュメント レベルのカスタム プロパティに似ていますが、同じキーを異なるワークシートで繰り返すことができる点が異なります。
Outlook アドインの設定を保存する方法
Outlook アドインの設定を保存する方法の詳細については、「 Outlook アドインのアドイン メタデータを取得して設定する」 および「 Outlook アドインでメッセージのインターネット ヘッダーを取得して設定する」を参照してください。
一般的な API 設定と永続化
共通 API には、セッション間でアドインの状態を保存するオブジェクトが用意されています。 保存された設定値は、それを作成したアドインの ID に関連付けられます。 内部的には、 Settings、 CustomProperties、および RoamingSettings オブジェクトは、名前と値のペアを含むシリアル化された JavaScript Object Notation (JSON) オブジェクトとしてデータを格納します。 各値の名前 (キー) は stringである必要があります。 格納されている値は、JavaScript string、 number、 date、または object にすることができますが、 関数は指定できません。
このプロパティ バッグ構造体の例には、firstName、location、および defaultView という名前の 3 つの定義済み文字列値が含まれています。
{
"firstName":"Erik",
"location":"98052",
"defaultView":"basic"
}
前のアドイン セッション中に設定プロパティ バッグを保存すると、アドインは、アドインの初期化時、またはその後のアドインの現在のセッション中の任意の時点で設定を読み込むことができます。 セッション中、アドインは、作成しようとしている設定の種類 (Settings、CustomProperties、または RoamingSettings) に対応するオブジェクトの get、set、および remove メソッドを使用して、メモリ内の設定を完全に管理します。
重要
アドインの現在のセッション中に行われた追加、更新、または削除を保存場所に保持するには、その種類の設定の操作に使用される対応するオブジェクトの saveAsync メソッドを呼び出します。
get、set、および remove メソッドは、設定プロパティ バッグのメモリ内コピーでのみ動作します。
saveAsync を呼び出さずにアドインを閉じると、そのセッションで設定を変更した内容は失われます。
コンテンツ アドインおよび作業ウィンドウ アドインで、ドキュメントごとにアドインの状態と設定を保存する方法
Word、Excel、または PowerPoint のコンテンツまたは作業ウィンドウ アドインの状態またはカスタム設定を保持するには、Settings オブジェクトとそのメソッドを使用します。
Settings オブジェクトのメソッドを使用して作成するプロパティ バッグは、それを作成したコンテンツまたは作業ウィンドウ アドインのインスタンスのみで、それを保存したドキュメントからのみ使用できます。
Settings オブジェクトは Document オブジェクトの一部として自動的に読み込まれ、作業ウィンドウまたはコンテンツ アドインがアクティブ化されている場合に使用できます。
Document オブジェクトをインスタンス化した後、Document オブジェクトの設定プロパティを使用してSettings オブジェクトにアクセスできます。 セッションの有効期間中は、 Settings.get、 Settings.set、および Settings.remove メソッドを使用して、永続化された設定とアドイン状態をプロパティ バッグのメモリ内コピーから読み取り、書き込み、または削除します。
set メソッドと remove メソッドは、設定プロパティ バッグのメモリ内コピーに対してのみ動作するため、アドインが関連付けられているドキュメントに新しい設定または変更された設定を保存するには、 Settings.saveAsync メソッドを呼び出す必要があります。
設定値を作成または更新する
次のコード例では、Settings.set メソッドを使用して 'themeColor' という名前の設定を作成し、値 'green' を指定する方法を説明します。 set メソッドの最初のパラメーターは、設定または作成する設定の大文字と小文字を区別する 名前 (ID) です。 2 番目のパラメーターは、設定の value です。
Office.context.document.settings.set('themeColor', 'green');
指定した名前の設定が既に存在しない場合は作成されるか、存在する場合はその値が更新されます。
Settings.saveAsync メソッドを使用して、新規または更新された設定をドキュメントに保持します。
設定の値を取得する
次の例では、Settings.get メソッドを使用して "themeColor" という名前の設定値を取得する方法を示します。
get メソッドの唯一のパラメーターは、設定の大文字と小文字を区別する名前です。
write('Current value for mySetting: ' + Office.context.document.settings.get('themeColor'));
// Function that writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
get メソッドは、渡された設定名に対して以前に保存された値を返します。 設定が存在しない場合、メソッドは null を返します。
設定を削除する
次の例では、Settings.remove メソッドを使用して、"themeColor" という名前の設定を削除する方法を示します。
remove メソッドの唯一のパラメーターは、設定の大文字と小文字を区別する名前です。
Office.context.document.settings.remove('themeColor');
設定が存在しない場合は何も起こりません。 ドキュメントから設定の削除を保持するには、 Settings.saveAsync メソッドを使用します。
設定を保存する
現在のセッション中に、設定プロパティ バッグのメモリ内コピーに対して行われた追加、変更、または削除を保存するには、 Settings.saveAsync メソッドを呼び出してドキュメントに保存します。
saveAsync メソッドの唯一のパラメーターは callback です。これは、1 つのパラメーターを持つコールバック関数です。
Office.context.document.settings.saveAsync(function (asyncResult) {
if (asyncResult.status == Office.AsyncResultStatus.Failed) {
write('Settings save failed. Error: ' + asyncResult.error.message);
} else {
write('Settings saved.');
}
});
// Function that writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
操作が完了したときに、コールバック パラメーターとして saveAsync メソッドに渡される匿名関数。 コールバックの asyncResult パラメーターを使用すると、操作の状態を含む AsyncResult オブジェクトにアクセスできます。 次の例では、関数は AsyncResult.status プロパティをチェックして保存操作が成功したか失敗したかを確認し、アドインのページに結果を表示します。
ドキュメントにカスタム XML を保存する方法
構造化された文字を持つ情報を格納する場合は、またはアドインのインスタンス間でデータにアクセスできるようにする必要がある場合は、カスタム XML パーツを使用します。 他のアドインは、この方法によって保存されたデータにもアクセスできます。 Word (および前の段落で説明したように、アプリケーション固有の API を使用して Excel および Word) の作業ウィンドウ アドインにカスタム XML マークアップを保持できます。 Word では、CustomXmlPart オブジェクトとそのメソッドを使用できます。 次のコードでは、カスタム XML パーツを作成して、その ID とコンテンツをページの div に表示します。 XML 文字列には xmlns 属性を含める必要があります。
function createCustomXmlPart() {
const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
Office.context.document.customXmlParts.addAsync(xmlString,
(asyncResult) => {
$("#xml-id").text("Your new XML part's ID: " + asyncResult.value.id);
asyncResult.value.getXmlAsync(
(asyncResult) => {
$("#xml-blob").text(asyncResult.value);
}
);
}
);
}
カスタム XML パーツを取得するには、 getByIdAsync メソッドを使用します。 ID は XML パーツの作成時に生成される GUID なので、コーディング時には ID はわかりません。 そのため、XML パーツの ID を設定として格納し、XML パーツを作成するときに覚えやすいキーを付けてください。 次のメソッドは、この方法を示してます
function createCustomXmlPartAndStoreId() {
const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
Office.context.document.customXmlParts.addAsync(xmlString,
(asyncResult) => {
Office.context.document.settings.set('ReviewersID', asyncResult.value.id);
Office.context.document.settings.saveAsync();
}
);
}
次のコードは、最初に設定から ID を取得することで、XML 部分を取得する方法を示しています。
function getReviewers() {
const reviewersXmlId = Office.context.document.settings.get('ReviewersID');
Office.context.document.customXmlParts.getByIdAsync(reviewersXmlId,
(asyncResult) => {
asyncResult.value.getXmlAsync(
(asyncResult) => {
$("#xml-blob").text(asyncResult.value);
}
);
}
);
}
関連項目
Office Add-ins