Office.CustomProperties interface
CustomProperties オブジェクトは、特定のメール アイテムに固有で、Outlook アドインに固有のカスタム プロパティを表します。 たとえば、アドインがアドインをアクティブ化した現在のメッセージに固有のデータを保存する必要がある場合があります。 ユーザーが今後同じメッセージを再び確認し、アドインをもう一度アクティブ化すると、アドインはカスタム プロパティとして保存されたデータを取得できるようになります。
CustomProperties
の詳細については、「Outlook アドインのアドイン メタデータを取得して設定する」を参照してください。
注釈
アドインでカスタム プロパティを使用する場合は、次の点に注意してください。
新規作成モードで保存されたカスタム プロパティは、メール アイテムの受信者に送信されません。 カスタム プロパティを含むメッセージまたは予定を送信すると、そのプロパティに [送信済みアイテム] フォルダー内のアイテムからアクセスできます。 受信者がカスタム データにアクセスできるようにする場合は、代わりに InternetHeaders を使用することを検討してください。
CustomPropertiesJSON オブジェクトの最大長は 2500 文字です。Outlook on Mac では、カスタム プロパティはキャッシュされません。 ユーザーのネットワークがダウンした場合、メール アドインはカスタム プロパティにアクセスできません。
最小アクセス許可レベル: 読み取り項目
適用できる Outlook モード: Composeまたは読み取り
メソッド
| get(name) | 指定したカスタム プロパティの値を返します。 |
| get |
名前と値のペアのコレクション内のすべてのカスタム プロパティを持つオブジェクトを返します。 以下は同等です。
ディクショナリ オブジェクトを反復処理して、すべての |
| remove(name) | カスタム プロパティ コレクションから指定のプロパティを削除します。 プロパティを永続的に削除するには、 |
| save |
カスタム プロパティをメッセージまたは予定に保存します。
コールバック関数をチェックし、 |
| save |
カスタム プロパティをメッセージまたは予定に保存します。
コールバック関数をチェックし、 |
| set(name, value) | 指定のプロパティを指定の値に設定します。
指定したプロパティがまだ存在しない場合は、 |
メソッドの詳細
get(name)
指定したカスタム プロパティの値を返します。
get(name: string): any;パラメーター
- name
-
string
取得するカスタム プロパティの名前。
戻り値
any
指定したカスタム プロパティの値。
注釈
最小アクセス許可レベル: 読み取り項目
適用できる 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 = $("#get-property-name").val();
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
名前と値のペアのコレクション内のすべてのカスタム プロパティを持つオブジェクト。
注釈
最小アクセス許可レベル: 読み取り項目
適用できる 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
注釈
最小アクセス許可レベル: 読み取り項目
適用できる 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 = $("#remove-property-name").val();
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);
saveAsync(callback, asyncContext)
カスタム プロパティをメッセージまたは予定に保存します。
saveAsync メソッドを呼び出して、set メソッドまたは CustomProperties オブジェクトの remove メソッドで行われた変更を保持する必要があります。 保存操作は非同期です。
コールバック関数をチェックし、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
注釈
重要: 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)
カスタム プロパティをメッセージまたは予定に保存します。
saveAsync メソッドを呼び出して、set メソッドまたは CustomProperties オブジェクトの remove メソッドで行われた変更を保持する必要があります。 保存操作は非同期です。
コールバック関数をチェックし、saveAsyncからのエラーを処理することをお勧めします。 特に、ユーザーが表示フォームの接続状態時に、読み取り用のアドインがアクティブ化され、その後ユーザーが切断されます。 切断状態でアドインが saveAsync を呼び出す場合、saveAsync はエラーを返します。 コールバック関数は、それに応じてこのエラーを処理する必要があります。
saveAsync(asyncContext?: any): void;パラメーター
- asyncContext
-
any
省略可能。 コールバック関数に渡される状態データ。
戻り値
void
注釈
最小アクセス許可レベル: 読み取り項目
適用できる Outlook モード: Composeまたは読み取り
set(name, value)
指定のプロパティを指定の値に設定します。
set メソッドは、指定のプロパティを指定の値に設定します。 set プロパティと値がメール アイテムに保持されるようにするには、 saveAsync メソッドを呼び出す必要があります。
指定したプロパティがまだ存在しない場合は、 set メソッドによって新しいプロパティが作成されます。それ以外の場合は、既存の値が新しい値に置き換えられます。
value パラメーターは任意の型にすることができます。ただし、常に文字列としてサーバーに渡されます。
set(name: string, value: string): void;パラメーター
- name
-
string
設定するプロパティの名前。
- value
-
string
設定するプロパティの値。
戻り値
void
注釈
最小アクセス許可レベル: 読み取り項目
適用できる 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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);
Office Add-ins