Office.CustomProperties interface
对象 CustomProperties 表示特定于特定邮件项目和特定于 Outlook 加载项的自定义属性。 例如，加载项可能需要保存一些特定于激活加载项的当前消息的数据。 如果用户将来重新访问同一消息并再次激活加载项，则外接程序将能够检索已保存为自定义属性的数据。
若要详细了解 CustomProperties，请参阅 获取和设置 Outlook 外接程序的外接程序元数据。
注解
在外接程序中使用自定义属性时，请记住：
在撰写模式下保存的自定义属性不会传输给邮件项目的收件人。 发送具有自定义属性的邮件或约会时，可以从“已发送邮件”文件夹中的项访问其属性。 如果要使自定义数据可供收件人访问，请考虑改用 InternetHeaders 。
JSON 对象的最大长度
CustomProperties为 2500 个字符。Mac 版 Outlook 不缓存自定义属性。 如果用户的网络出现故障，邮件加载项无法访问其自定义属性。
最低权限级别： 读取项
适用的 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)
从自定义属性集合中移除指定的属性。
若要永久删除属性，必须调用 saveAsync 对象的 方法 CustomProperties 。
remove(name: string): void;参数
- name
-
string
name要删除的属性的 。
返回
void
注解
最低权限级别： 读取项
适用的 Outlook 模式：Compose或读取
重要提示：当前 remove 使用 loadItemByIdAsync 方法加载的消息不支持方法。 有关详细信息，请参阅 在多条消息上激活 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 = $("#remove-property-name").val();
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);
saveAsync(callback, asyncContext)
将自定义属性保存到邮件或约会。
必须调用 方法才能 saveAsync 保留对 set 方法或 remove 对象的 方法 CustomProperties 所做的任何更改。 保存操作是异步操作。
最好让回调函数检查并从 中处理错误saveAsync。 尤其要注意的是，当用户在阅读窗体中处于连接状态时，可以激活阅读外接程序，随后用户将断开连接。 如果外接程序在断开状态下调用 saveAsync，saveAsync 将返回错误。 回调函数应相应地处理此错误。
saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;参数
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
方法完成后，使用类型的Office.AsyncResult单个参数调用在 参数中callback传递的函数。
- 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 方法或 remove 对象的 方法 CustomProperties 所做的任何更改。 保存操作是异步操作。
最好让回调函数检查并从 中处理错误saveAsync。 尤其要注意的是，当用户在阅读窗体中处于连接状态时，可以激活阅读外接程序，随后用户将断开连接。 如果外接程序在断开状态下调用 saveAsync，saveAsync 将返回错误。 回调函数应相应地处理此错误。
saveAsync(asyncContext?: any): void;参数
- asyncContext
-
any
可选。 传递给回调函数的任何状态数据。
返回
void
注解
最低权限级别： 读取项
适用的 Outlook 模式：Compose或读取
set(name, value)
将指定属性设置为指定值。
set 方法将指定属性设置为指定值。 若要确保设置属性和值保留在邮件项上，必须调用 saveAsync 方法。
如果指定的属性尚不存在，则 set 方法将创建一个新属性;否则，现有值将替换为新值。 参数 value 可以是任何类型的;但是，它始终作为字符串传递给服务器。
set(name: string, value: string): void;参数
- name
-
string
要设置的属性的名称。
- value
-
string
要设置的属性的值。
返回
void
注解
最低权限级别： 读取项
适用的 Outlook 模式：Compose或读取
重要提示：当前 set 使用 loadItemByIdAsync 方法加载的消息不支持方法。 有关详细信息，请参阅 在多条消息上激活 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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);