Office.CustomProperties interface

包:

outlook

CustomProperties对象表示特定于特定邮件项目和特定于 Outlook 加载项的自定义属性。 例如，加载项可能需要保存激活该加载项的当前邮件特定的某些数据。 如果用户将来再次访问相同的消息并再次激活加载项，则加载项将能够检索已保存为自定义属性的数据。

若要了解有关此文件的 CustomProperties详细信息，请参阅 获取和设置 Outlook 加载项的加载项元数据。

注解

API 集：邮箱 1.1

在加载项中使用自定义属性时，请记住：

• 在撰写模式下保存的自定义属性不会传输给邮件项目的收件人。 发送具有自定义属性的邮件或约会时，可以从“已发送项目”文件夹中的项目访问其属性。 如果要使收件人可以访问自定义数据，请考虑改用 InternetHeaders 。

• JSON 对象的最大 CustomProperties 长度是 2500 个字符。

• Mac 上的 Outlook 不会缓存自定义属性。 如果用户的网络关闭，邮件加载项将无法访问其自定义属性。

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

使用方

• 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)	从自定义属性集合中移除指定的属性。 要使该属性的删除永久化，必须调用 saveAsync 对象的方法 CustomProperties 。
saveAsync(callback, asyncContext)	将自定义属性保存到邮件或约会。 必须调用该 saveAsync 方法以保留对该 set 方法或 remove 对象方法 CustomProperties 所做的任何更改。 保存操作是异步操作。 让回调函数检查和处理来自 的错误saveAsync是一个很好的做法。 尤其要注意的是，当用户在阅读窗体中处于连接状态时，可以激活阅读外接程序，随后用户将断开连接。 如果外接程序在断开状态下调用 saveAsync，saveAsync 将返回错误。 回调函数应相应地处理此错误。
saveAsync(asyncContext)	将自定义属性保存到邮件或约会。 必须调用该 saveAsync 方法以保留对该 set 方法或 remove 对象方法 CustomProperties 所做的任何更改。 保存操作是异步操作。 让回调函数检查和处理来自 的错误saveAsync是一个很好的做法。 尤其要注意的是，当用户在阅读窗体中处于连接状态时，可以激活阅读外接程序，随后用户将断开连接。 如果外接程序在断开状态下调用 saveAsync，saveAsync 将返回错误。 回调函数应相应地处理此错误。
set(name, value)	将指定属性设置为指定值。 set 方法将指定属性设置为指定值。 要确保设置的属性和值在邮件项上持久存在，必须调用该 saveAsync 方法。 如果指定的属性尚不存在，则该 set 方法会创建新属性;否则，现有值将替换为新值。 value参数可以是任何类型;但是，它始终以字符串的形式传递到服务器。

方法详细信息

get(name)

返回指定自定义属性的值。

get(name: string): any;

参数

name

string

要返回的自定义属性的名称。

返回

any

指定的自定义属性的值。

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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 或 Read

示例

// 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

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要提示： 当前使用该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)

将自定义属性保存到邮件或约会。

必须调用该 saveAsync 方法以保留对该 set 方法或 remove 对象方法 CustomProperties 所做的任何更改。 保存操作是异步操作。

让回调函数检查和处理来自 的错误saveAsync是一个很好的做法。 尤其要注意的是，当用户在阅读窗体中处于连接状态时，可以激活阅读外接程序，随后用户将断开连接。 如果外接程序在断开状态下调用 saveAsync，saveAsync 将返回错误。 回调函数应相应地处理此错误。

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

参数

callback

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

当该方法完成时， callback 将使用类型 Office.AsyncResult为 .

asyncContext

any

可选。 传递到回调函数的任何状态数据。

返回

void

注解

API 集：邮箱 1.1

重要提示： 在 Windows 版 Outlook 中，在撰写模式下保存的自定义属性仅在正在撰写的项目关闭或被调用后 Office.context.mailbox.item.saveAsync 保留。

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

set(name, value)

将指定属性设置为指定值。

set 方法将指定属性设置为指定值。 要确保设置的属性和值在邮件项上持久存在，必须调用该 saveAsync 方法。

如果指定的属性尚不存在，则该 set 方法会创建新属性;否则，现有值将替换为新值。 value参数可以是任何类型;但是，它始终以字符串的形式传递到服务器。

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

参数

name

string

要设置的属性的名称。

value

string

要设置的属性的值。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要提示： 当前使用该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}".`);