Office.CustomProperties interface

パッケージ:

outlook

CustomProperties オブジェクトは、特定のメール アイテムおよび Outlook アドインに固有のカスタム プロパティを表します。 たとえば、アドインをアクティブにした現在のメッセージに固有のデータをアドインで保存する必要がある場合があります。 ユーザーが後で同じメッセージに再度アクセスしてアドインを再度アクティブ化した場合、アドインはカスタム プロパティとして保存されたデータを取得できます。

CustomProperties の詳細については、「Outlook アドインのアドイン メタデータを取得して設定する」を参照してください。

注釈

API セット: メールボックス 1.1

アドインでカスタム プロパティを使用する場合は、次の点に注意してください。

• 作成モードで保存されたカスタム プロパティは、メール アイテムの受信者には送信されません。 カスタム プロパティを使用してメッセージや予定を送信すると、[送信済みアイテム] フォルダー内のアイテムからそのプロパティにアクセスできます。 受信者がカスタム データにアクセスできるようにする場合は、代わりに InternetHeaders の使用を検討してください。

• CustomProperties JSON オブジェクトの最大文字数は 2500 文字です。

• Outlook on Mac では、カスタム プロパティはキャッシュされません。 ユーザーのネットワークがダウンした場合、メール アドインはカスタム プロパティにアクセスできなくなります。

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

使用元

• Office.AppointmentCompose: loadCustomPropertiesAsync
• Office.AppointmentRead: loadCustomPropertiesAsync
• Office.LoadedMessageCompose: loadCustomPropertiesAsync
• Office.LoadedMessageRead: loadCustomPropertiesAsync
• Office.MessageCompose: loadCustomPropertiesAsync
• Office.MessageRead: loadCustomPropertiesAsync

メソッド

get(name)	指定したカスタム プロパティの値を返します。
getAll()	名前と値のペアのコレクションで、すべてのカスタム プロパティを含むオブジェクトを返します。 以下は同等です。 customProps.get("name") var dictionary = customProps.getAll(); dictionary["name"] ディクショナリ オブジェクトを反復処理して、すべての names と valuesを検出できます。
remove(name)	カスタム プロパティ コレクションから指定のプロパティを削除します。 プロパティの削除を永続的にするには、CustomProperties オブジェクトの saveAsync メソッドを呼び出す必要があります。
saveAsync(callback, asyncContext)	メッセージまたは予定にカスタム プロパティを保存します。 CustomProperties オブジェクトの set メソッドまたは remove メソッドで行われた変更を保持するには、saveAsync メソッドを呼び出す必要があります。 保存操作は非同期です。 コールバック関数でsaveAsyncからのエラーをチェックして処理することをお勧めします。 特に、ユーザーが表示フォームの接続状態時に、読み取り用のアドインがアクティブ化され、その後ユーザーが切断されます。 切断状態でアドインが saveAsync を呼び出す場合、saveAsync はエラーを返します。 コールバック関数は、このエラーを適切に処理する必要があります。
saveAsync(asyncContext)	メッセージまたは予定にカスタム プロパティを保存します。 CustomProperties オブジェクトの set メソッドまたは remove メソッドで行われた変更を保持するには、saveAsync メソッドを呼び出す必要があります。 保存操作は非同期です。 コールバック関数でsaveAsyncからのエラーをチェックして処理することをお勧めします。 特に、ユーザーが表示フォームの接続状態時に、読み取り用のアドインがアクティブ化され、その後ユーザーが切断されます。 切断状態でアドインが saveAsync を呼び出す場合、saveAsync はエラーを返します。 コールバック関数は、このエラーを適切に処理する必要があります。
set(name, value)	指定のプロパティを指定の値に設定します。 set メソッドは、指定のプロパティを指定の値に設定します。 設定されたプロパティと値がメール アイテムで確実に保持されるようにするには、 saveAsync メソッドを呼び出す必要があります。 set メソッドは、指定したプロパティがまだ存在しない場合は新しいプロパティを作成します。それ以外の場合は、既存の値が新しい値に置き換えられます。 value パラメーターは任意の型にできますが、常に文字列としてサーバーに渡されます。

メソッドの詳細

get(name)

指定したカスタム プロパティの値を返します。

get(name: string): any;

パラメーター

name

string

取得するカスタム プロパティの名前。

返品

any

指定したカスタム プロパティの値。

注釈

API セット: メールボックス 1.1

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = (document.getElementById("get-property-name") as HTMLInputElement).value;
const propertyValue = customProps.get(propertyName);
console.log(`The value of custom property "${propertyName}" is "${propertyValue}".`);

getAll()

名前と値のペアのコレクションで、すべてのカスタム プロパティを含むオブジェクトを返します。 以下は同等です。

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

ディクショナリ オブジェクトを反復処理して、すべての names と valuesを検出できます。

getAll(): any;

返品

any

名前と値のペアのコレクション内のすべてのカスタム プロパティを持つオブジェクト。

注釈

API セット: メールボックス 1.9

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

let allCustomProps;
if (Office.context.requirements.isSetSupported("Mailbox", "1.9")) {
  allCustomProps = customProps.getAll();
} else {
  allCustomProps = customProps["rawData"];
}

console.log(allCustomProps);

remove(name)

カスタム プロパティ コレクションから指定のプロパティを削除します。

プロパティの削除を永続的にするには、CustomProperties オブジェクトの saveAsync メソッドを呼び出す必要があります。

remove(name: string): void;

パラメーター

name

string

削除するプロパティの name 。

返品

void

注釈

API セット: メールボックス 1.1

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

重要: 現在loadItemByIdAsync メソッドを使用して読み込まれているメッセージでは、remove メソッドはサポートされていません。 詳細については、「 複数のメッセージに対して Outlook アドインをアクティブ化する」を参照してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = (document.getElementById("remove-property-name") as HTMLInputElement).value;
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);

saveAsync(callback, asyncContext)

メッセージまたは予定にカスタム プロパティを保存します。

CustomProperties オブジェクトの set メソッドまたは remove メソッドで行われた変更を保持するには、saveAsync メソッドを呼び出す必要があります。 保存操作は非同期です。

コールバック関数でsaveAsyncからのエラーをチェックして処理することをお勧めします。 特に、ユーザーが表示フォームの接続状態時に、読み取り用のアドインがアクティブ化され、その後ユーザーが切断されます。 切断状態でアドインが saveAsync を呼び出す場合、saveAsync はエラーを返します。 コールバック関数は、このエラーを適切に処理する必要があります。

saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;

パラメーター

callback

(asyncResult: Office.AsyncResult<void>) => void

メソッドが完了すると、 callback パラメーターで渡された関数が型 Office.AsyncResult の 1 つのパラメーターで呼び出されます。

asyncContext

any

省略可能。 コールバック関数に渡される状態データ。

返品

void

注釈

API セット: メールボックス 1.1

重要: Outlook on Windows では、作成モードのときに保存されたカスタム プロパティは、作成中のアイテムが閉じられた後、または Office.context.mailbox.item.saveAsync が呼び出された後にのみ保持されます。

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

customProps.saveAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`saveAsync failed with message ${result.error.message}`);
    return;
  }

  console.log(`Custom properties saved with status: ${result.status}`);
});

saveAsync(asyncContext)

メッセージまたは予定にカスタム プロパティを保存します。

CustomProperties オブジェクトの set メソッドまたは remove メソッドで行われた変更を保持するには、saveAsync メソッドを呼び出す必要があります。 保存操作は非同期です。

コールバック関数でsaveAsyncからのエラーをチェックして処理することをお勧めします。 特に、ユーザーが表示フォームの接続状態時に、読み取り用のアドインがアクティブ化され、その後ユーザーが切断されます。 切断状態でアドインが saveAsync を呼び出す場合、saveAsync はエラーを返します。 コールバック関数は、このエラーを適切に処理する必要があります。

saveAsync(asyncContext?: any): void;

パラメーター

asyncContext

any

省略可能。 コールバック関数に渡される状態データ。

返品

void

注釈

API セット: メールボックス 1.1

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

set(name, value)

指定のプロパティを指定の値に設定します。

set メソッドは、指定のプロパティを指定の値に設定します。 設定されたプロパティと値がメール アイテムで確実に保持されるようにするには、 saveAsync メソッドを呼び出す必要があります。

set メソッドは、指定したプロパティがまだ存在しない場合は新しいプロパティを作成します。それ以外の場合は、既存の値が新しい値に置き換えられます。 value パラメーターは任意の型にできますが、常に文字列としてサーバーに渡されます。

set(name: string, value: string): void;

パラメーター

name

string

設定するプロパティの名前。

value

string

設定するプロパティの値。

返品

void

注釈

API セット: メールボックス 1.1

最小アクセス許可レベル: 項目の読み取り

適用可能な Outlook モード: Composeまたは読み取り

重要: 現在loadItemByIdAsync メソッドを使用して読み込まれているメッセージでは、set メソッドはサポートされていません。 詳細については、「 複数のメッセージに対して Outlook アドインをアクティブ化する」を参照してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = (document.getElementById("set-property-name") as HTMLInputElement).value;
const propertyValue = (document.getElementById("property-value") as HTMLInputElement).value;
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);