次の方法で共有

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

  • [アーティクル]

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

開いているドキュメント間でユーザー設定を追跡するなど、ドキュメント間で状態を保持する必要がある場合は、別の方法を使用する必要があります。 たとえば、 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 」および 「Word.SettingCollection」を参照してください。

次の例は、Excel で設定を作成してアクセスする方法を示しています。 このプロセスは Word で機能的に同等であり、Workbook.settingsではなく Document.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 には、CustomXmlPartsの一覧であるCustomXmlPartCollectionが含まれています。 これにより、XML 文字列と対応する一意の ID へのアクセスが提供されます。 これらの ID を設定として保管することにより、アドインはセッション間で XML パーツへのキーを保持できます。

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

注:

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 設定と永続化

Common 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"
}

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

重要

アドインの現在のセッション中に行われた追加、更新、または削除をストレージの場所に保持するには、その種類の設定を操作するために使用する対応するオブジェクトの saveAsync メソッドを呼び出す必要があります。 get、set、および remove メソッドは、settings プロパティ バッグのメモリ内コピーでのみ動作します。 saveAsyncを呼び出さずにアドインを閉じると、そのセッション中に設定に加えられた変更は失われます。

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

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

Settings オブジェクトは Document オブジェクトの一部として自動的に読み込まれ、作業ウィンドウまたはコンテンツ アドインがアクティブになると使用できます。 Document オブジェクトがインスタンス化されたら、Document オブジェクトの settings プロパティを使用して、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');

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 パーツは、構造化文字を持つ情報を格納する場合や、アドインのインスタンス間でデータにアクセスできるようにする必要がある場合に使用できるストレージ オプションです。 この方法で格納されたデータには、他のアドインからもアクセスできることに注意してください。Word 用の作業ウィンドウ アドイン (および Excel および Word の場合は、前の段落で説明したようにアプリケーション固有の API を使用) にカスタム 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);
               }
           );
       }
   );
}

関連項目