Office.CustomProperties interface

包:

outlook

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

若要详细了解 CustomProperties，请参阅 获取和设置 Outlook 外接程序的外接程序元数据。

注解

[ API set： Mailbox 1.1 ]

在外接程序中使用自定义属性时，请记住：

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

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

• Mac 版 Outlook 不缓存自定义属性。 如果用户的网络出现故障，邮件加载项无法访问其自定义属性。

最低权限级别： 读取项

适用的 Outlook 模式：撰写或阅读

方法

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 方法将创建一个新的属性；否则现有值将替换为新值。 参数可以是任何类型；但是始终作为字符串传递给服务器。

方法详细信息

get(name)

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

get(name: string): any;

参数

name

string

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

返回

any

指定的自定义属性的值。

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 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 = $("#propertyName").val();
const propertyValue = customProps.get(propertyName);
$("#propertyValue").val(propertyValue);
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 set： Mailbox 1.9 ]

最低权限级别： 读取项

适用的 Outlook 模式：撰写或阅读

remove(name)

从自定义属性集合中移除指定的属性。

若要永久删除属性，必须调用 saveAsync 对象的 方法 CustomProperties 。

remove(name: string): void;

参数

name

string

name要删除的属性的 。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 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 = $("#propertyName").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

注解

[ API set： Mailbox 1.1 ]

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

最低权限级别： 读取项

适用的 Outlook 模式：撰写或阅读

示例

// The following JavaScript code sample shows how to asynchronously use
// the loadCustomPropertiesAsync method to load custom properties that
// are specific to the current item, and the saveAsync method to save
// these to the mail item. After loading the custom properties,
// the code sample uses the get method to read the custom property myProp,
// the set method to write the custom property myProp, and then finally
// calls the saveAsync method to save the custom properties.

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        const item = Office.context.mailbox.item;
        item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");
    console.log("myProp: " + myProp); // First run on current item will return `undefined`.

    // Set myProp custom property.
    customProps.set("myProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);
    }
    else {
        // Async call to save custom properties completed.
        // Proceed to do the appropriate for your add-in.
    }
}

saveAsync(asyncContext)

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

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

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

saveAsync(asyncContext?: any): void;

参数

asyncContext

any

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

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：撰写或阅读

set(name, value)

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

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

如果尚不存在指定属性，set 方法将创建一个新的属性；否则现有值将替换为新值。 参数可以是任何类型；但是始终作为字符串传递给服务器。

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

参数

name

string

要设置的属性的名称。

value

string

要设置的属性的值。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 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 = $("#propertyName").val();
const propertyValue = $("#propertyValue").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);