アドインの状態と設定を保持する

Office アドインは、基本的にブラウザー iframe または Webview コントロールのステートレス環境で実行される Web アプリケーションです。 (後で簡潔にするために、この記事では "ブラウザー コントロール" を使用して "ブラウザーまたは Webview コントロール" を意味します)。使用中のアドインでは、セッション間で特定の操作または機能の継続性を維持するためにデータを保持する必要がある場合があります。 たとえば、アドインには、ユーザーの優先ビューや既定の場所など、アドインで保存しておき、アドインが次回初期化されたときにリロードする必要があるカスタム設定または他の値が含まれる場合があります。 その場合は、次のようにします。

• 基になるブラウザー コントロールによって提供される手法を使用します。
• Excel、Word、およびデータを格納する Outlook 用のアプリケーション固有の Office JavaScript API を使用します。

開いているドキュメント間でユーザー設定を追跡するなど、ドキュメント間で状態を保持する必要がある場合は、別の方法を使用する必要があります。 たとえば、 SSO を 使用してユーザー ID を取得し、ユーザー ID とその設定をオンライン データベースに保存できます。

ブラウザー ストレージ

ブラウザー Cookie や HTML5 Web ストレージ (localStorage または sessionStorage) などの基になるブラウザー コントロールのツールを使用して、アドイン インスタンス間でデータを保持します。

ブラウザーまたはユーザーのブラウザー設定によっては、ブラウザー ベースのストレージ手法がブロックされる場合があります。 「Web Storage API の使用」に記載されているように、可用性をテストする必要があります。

ストレージのパーティション分割

ベスト プラクティスとして、プライベート データはパーティション分割された localStorageに格納する必要があります。 Office.context.partitionKey には、ローカル ストレージで使用するためのキーが用意されています。 これにより、ローカル ストレージに格納されているデータが同じコンテキストでのみ使用できるようになります。 次の例は、 でパーティション キーを使用する方法を localStorage示しています。 パーティションキーは、Windows アプリケーションのブラウザー コントロールなど、パーティション分割を行わない環境では未定義であることに注意してください。

// 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 の代わりにこれらを使用します。

Excel とWordの設定

Excel および Word 用のアプリケーション固有の JavaScript API は、カスタム設定へのアクセスも提供します。 設定は、1 つの Excel ファイルとアドインのペアリングに固有です。 詳細については、「Excel.SettingCollection and Word」を参照してください。SettingCollection。

次の例は、Excel で設定を作成してアクセスする方法を示しています。 このプロセスは、 の代わりに Document.settings を使用するWordで機能的に同等ですWorkbook.settings。

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 ファイル形式を使用すると、アドインでカスタム XML データを Excel ブックまたは Word ドキュメントに埋め込むことができます。 このデータは、アドインとは関係なく、ファイルと共に保持されます。

Word。Document と Excel.Workbook には、 のCustomXmlPartCollectionCustomXmlParts一覧である が含まれています。 これにより、XML 文字列と対応する一意の ID へのアクセスが提供されます。 これらの ID を設定として保管することにより、アドインはセッション間で XML パーツへのキーを保持できます。

次のサンプルは、Excel ブックでカスタム XML パーツを使用する方法を示しています。 最初のコード ブロックは、XML データを埋め込む方法を示しています。 レビュー担当者のリストを保管してから、ブックの設定を使用して XML の id を保存して、後から取得できるようにします。 2 番目のブロックでは、後からその XML にアクセスする方法が示されています。 "ContosoReviewXmlPartId" 設定がロードされ、ブックの customXmlParts に渡されます。 それから、XML データがコンソールに出力されます。 このプロセスは、 の代わりに Document.customXmlParts を使用するWordで機能的に同等ですWorkbook.customXmlParts。

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);
});

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"
});

Outlook アドインに設定を保存する方法

Outlook アドインに設定を保存する方法の詳細については、「Outlook アドインのアドイン メタデータを取得して設定する」および「Outlook アドインのメッセージにインターネット ヘッダーを取得して設定する」を参照してください。

一般的な API 設定と永続化

Common API には、セッション間でアドインの状態を保存するオブジェクトが用意されています。 保存された設定値は、それらを作成したアドインの ID に関連付けられます。 内部的には、、CustomProperties、または RoamingSettings オブジェクトでSettingsアクセスされるデータは、名前と値のペアを含むシリアル化された JavaScript Object Notation (JSON) オブジェクトとして格納されます。 各値の名前 (キー) は であるstring必要があり、格納される値には JavaScriptstring、、numberdateまたは objectを指定できますが、関数は使用できません。

このプロパティ バッグ構造体の例には、 という名前firstNamelocationの 3 つの定義された文字列値がdefaultView含まれています。

{
    "firstName":"Erik",
    "location":"98052",
    "defaultView":"basic"
}

設定プロパティ バッグは、前のアドイン セッション中に保存された後、アドインが初期化されるとき、またはその後はいつでも、アドインの現行セッション中は読み込むことができます。 セッション中、設定は、作成する設定の種類 (設定、CustomProperties、または RoamingSettings) に対応する オブジェクトの メソッドを使用してgetsetremove、完全にメモリ内で管理されます。

コンテンツ アドインおよび作業ウィンドウ アドインで、ドキュメントごとにアドインの状態と設定を保存する方法

Word、Excel、または PowerPoint のコンテンツアドインまたは作業ウィンドウ アドインの状態またはカスタム設定を保持するには、Settings オブジェクトとそのメソッドを使用します。 オブジェクトの Settings メソッドで作成されたプロパティ バッグは、オブジェクトを作成したコンテンツアドインまたは作業ウィンドウ アドインのインスタンスでのみ使用でき、保存されているドキュメントからのみ使用できます。

オブジェクトは SettingsDocument オブジェクトの一部として自動的に読み込まれ、作業ウィンドウまたはコンテンツ アドインがアクティブになったときに使用できます。 オブジェクトが Document インスタンス化された後、オブジェクトの Settingssettings プロパティを使用して オブジェクトに Document アクセスできます。 セッションの有効期間中は、 メソッド、、および Settings.remove メソッドをSettings.setSettings.get使用して、プロパティ バッグのメモリ内コピーから永続化された設定とアドインの状態を読み取り、書き込み、または削除できます。

set メソッドと remove メソッドは、設定プロパティ バッグのメモリ内コピーにのみ対して動作するため、アドインが関連付けられているドキュメントに新しい設定または変更された設定を保存するには、 Settings.saveAsync メソッドを呼び出す必要があります。

設定値を作成または更新する

次のコード例では、Settings.set メソッドを使用して 'themeColor' という名前の設定を作成し、値 'green' を指定する方法を説明します。 set メソッドの最初のパラメーターは、設定または作成する設定の大文字と小文字を区別する 名前 (ID) です。 2 番目のパラメーターは、設定の value です。

Office.context.document.settings.set('themeColor', 'green');

The setting with the specified name is created if it doesn't already exist, or its value is updated if it does exist. メソッドを 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 パーツは、構造化文字を持つ情報を格納する場合や、アドインのインスタンス間でデータにアクセスできるようにする必要がある場合に使用できるストレージ オプションです。 この方法で格納されたデータには、他のアドインからもアクセスできることに注意してください。前の段落で説明したように、アプリケーション固有の API を使用して、Word用 (および 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 パーツを作成する場合は、XML パーツの ID を設定としてすぐに格納し、思い出に残るキーを指定することをお勧めします。 次のメソッドは、この方法を示してます

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 JavaScript API について
• Outlook アドイン
• Outlook アドインのアドイン メタデータを取得および設定する
• Outlook アドインのメッセージに対するインターネット ヘッダーの取得と設定
• Excel-Add-in-JavaScript-PersistCustomSettings