JavaScript API for Office Outlook Add-in - “一页纸文档“

上一篇文章 Office Add-in Model 为 Outlook Mail Add-in 提供的 JavaScript API 介绍 ，简单地在表格中列出了所有的 Object 定义，但是个人感觉表格仅适合列一些简单的内容，太多的话就不再直观了。本文沿着上篇的骨骼，对每个 Object 及 API 进行了扩展， 多数的东西都来自于官方文档（ 尽量把分散在各地的补充说明归纳起来），我写这篇博文的目的并不是想把所有的 Object、方法、属性都涵盖，更多地是从 agile 开发的角度出发，这样我们在开发 Outlook Mail Add-in 的时候就能更快地找到合适的 API 及其定义了。

本文将从 Object Model 的角度更详细的罗列出 Mail Add-in 中可以访问的 Object 以及它所提供的方法和属性。

Office

Office Object 表示 Add-in 的一个实例, 它是调用其它API相关的 Object (如Context等) 的入口。

代码示例（本文中所有代码示例如无特殊注明，均为 JavaScript 代码）：

Office

Office.js版本：此 Object 在 Office.js v1.0 中引入， 最后一次更新是在 v1.1中。

在哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： N/A

官方文档：https://msdn.microsoft.com/en-us/library/office/fp142234.aspx

Office.context

Context Object 表示 Add-in 的运行时环境信息，并提供调用关键 Object（如 Mailbox) 上 API 的入口

代码示例：

Office.context

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： N/A

官方文档： https://msdn.microsoft.com/EN-US/library/office/fp161104.aspx

Office.context.roamingSettings

RoamingSettings Object 用来存储per user，per add-in的custom settings。RoamingSettings 中的值只能被创建该值的用户所访问 （ 这也是 RoamingSettings 和 下文提到的 Office.context.mailbox.item.loadCustomPropertiesAsync()不同的地方），并且只能在被创建该值的 add-in 中访问到。Setting 的key是字符串类型的， value 的类型则可以是string、number、boolean、null、object或者array。

RoamingSettings Object是作为 Context 对象的一部分自动加载的， 当 add-in 被激活后，便可以通过访问 roamingSettings 来获得或设置其中的值。

代码示例：

var _settings;
var _customerName;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run

        // Initialize instance variables to access API objects.
        _settings = Office.context.roamingSettings;

        // Set new settings
        _settings.set("customerName", "Paul");
        _settings.saveAsync(saveMyAppSettingsCallback);

        // Load existing settings.
        _customerName = _settings.get("customerName");

        // Remove an existing setting.
        _settings.remove("customerName");
        _settings.saveAsync(saveMyAppSettingsCallback);
    });
}

// Callback method after saving custom application roaming settings.
function saveMyAppSettingsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
}

Office.js版本：此 Object 在 Office.js v1.0 中引入， 后续无更新。

哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： Restricted

官方文档：https://msdn.microsoft.com/en-us/library/office/jj220079.aspx

一些实例：Persist metadata for the same mailbox by using roaming settings

Office.context.mailbox

Mailbox Object 是 Office Add-in Object Model 的入口， 所有与邮件甚至邮箱用户信息相关的操作都需要通过 Office.context.mailbox 来调用。

代码示例：

Office.context.mailbox

Office.js版本：此 Object 在 Office.js v1.0 中引入， 后续无更新。

在哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadWriteMailbox, but some members accessible with lesser permissions

官方文档：https://msdn.microsoft.com/EN-US/library/office/fp142162.aspx

Office.context.mailbox.userProfile

UserProfile Object 表示当前邮箱登录用户的信息, 它封装了用户的显示名称（Display Name）、邮箱地址、用户本地时区。

代码示例：

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, addin-specific code can run.
        var userProfile = Office.context.mailbox.userProfile;

        // The user name to use for display.
        var name = userProfile.displayName;

        // The user‘s SMTP email address.
        var emailAdrress = userProfile.emailAddress;

        // The user‘s local time zone
        var timeZone = userProfile.timeZone;
    });
}

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/fp161126.aspx

Office.context.mailbox.item

Item Object 表示 host 并激活当前 Add-in 的邮件信息条目或者约会条目。

Item Object 包含的方法和属性分别有：

Item Object 是一个 base Object，其他的“表示特定条目的Object”（如 Appointment 和 Message ）都是它的扩展， 可以根据 itemType 属性来判断是 Appointment 还是 Message。

关于 Appointment 和 Message， 以及 MettingRequest Object 它们分别特有的方法、属性，可以参考如下链接， 接下来一一罗列。

Appointment Object 表示当前约会条目

Message Object 表示当前邮件信息条目（区别于会议或约会）

MeetingRequest Object 扩展了 Message Object，表示一个会议邀请

Office.context.mailbox.item 的返回值取决于当前查看的邮件条目类型。例如，如果当前邮件条目是信息条目，返回值为一个Message Object；如果是一个约会条目，返回值为一个 Appointment Object。

注意: 下文中介绍的 Office.context.mailbox.item 的子 Object 或方法，有些是与当前邮件类型相关的。例如同样是Office.context.mailbox.item，如果当前邮件条目为约会条目，则它有 requiredAttendees 属性；而如果是邮件信息条目，则它会有 cc、to 等属性。

代码示例：

// The initialize function is required for all add-ins.
Office.initialize = function () {
    /* Checks for the DOM to load using the jQuery ready function. */
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var item = Office.context.mailbox.item;
        var subject = item.subject;
        // Continue with processing the subject of the current item, which can be a message or appointment.
    });
}

Office.js版本：此 Object 在 Office.js v1.0 中引入， 最后一次更新是在 v1.3中。

在哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：

Item object：https://msdn.microsoft.com/EN-US/library/office/fp142177.aspx

Message Object： https://msdn.microsoft.com/EN-US/library/office/fp161175.aspx

MeetingRequest Object：https://msdn.microsoft.com/EN-US/library/office/fp142237.aspx?f=255&MSPPError=-2147217396

Appointment Object： https://msdn.microsoft.com/EN-US/library/office/fp160964.aspx

Office.context.mailbox.item.attachments

AttachmentDetails Object 表示当前邮件条目中包含的附件信息，它封装了如下属性：

其中 Office.MailboxEnums.AttachmentType 是个枚举类型，可取的值包括：

代码示例：

// An array of AttachmentDetail objects is returned as the attachments property of an Item,
// Appointment, or Message objects.
Office.context.mailbox.item.attachments

Office.js版本：此 Object 在 Office.js v1.0 中引入， 后续无更新。

在哪些 Outlook 模式中可用： 读邮件 (Read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/jj984592.aspx

Office.context.mailbox.item.body

Body Object 表示当前邮件信息或约会条目的正文内容， 它提供了一些方法来为邮件信息或约会条目增加/更新正文内容，如下表所示。

代码示例：

Office.context.mailbox.item.body
TODO: 添加实例

Office.js版本：此 Object 在 Office.js v1.1 中引入， 最后一次更新是在 v1.3中。

在哪些 Outlook 模式中可用： 撰写邮件(Compose)

最低权限要求：ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/dn482486.aspx

Office.context.mailbox.item.subject

Subject Object 表示邮件信息或会议的主题。

• Compose 模式下：Office.context.mailbox.item.subject 返回邮件会议或邮件信息的Subject Object， 该 Object 提供用于获得或设置邮件主题的方法：

• Read 模式下：Office.context.mailbox.item.subject 返回邮件会议或者邮件信息的主题（字符串）。

代码示例：

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var item = Office.context.mailbox.item;

        // Get the subject of the item being composed.
        item.subject.getAsync(
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully got the subject, display it.
                    console.write(‘The subject is: ‘ + asyncResult.value);
                }
            }
        );

        // Set the subject of the item that the user is composing.
        var today = new Date();
        // Customize the subject with today‘s date.
        var subject = ‘Summary for ‘ + today.toLocaleDateString();
        item.subject.setAsync(
            subject,
            { asyncContext: { var1: 1, var2: 2 } },
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully set the subject.
                    // Do whatever appropriate for your scenario
                    // using the arguments var1 and var2 as applicable.
                }
            }
        );

    });// end $(document).ready
}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482528.aspx

Office.context.mailbox.item.start/end

Time Object 表示邮件约会的开始或结束时间，Office.context.mailbox.item.start 和 Office.context.mailbox.item.end 均是这种类型的 Object。该对象仅仅适用于邮件会议或约会，因为只有会议才有开始或结束时间，因此只有 Appointment 才有 start 或 end 属性（ Message 和 MeetingRequest 对象都没有这些属性）。

• Compose 模式下：Office.context.mailbox.item.start/end 返回一个Time object，它提供了方法用来获取或设置会议起（或止）的时间：

• Read 模式下：Office.context.mailbox.item.start（或end）返回一个 JavaScript Date object，表示会议的起（或止）的时间。

代码示例：

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var item = Office.context.mailbox.item;

        // Get the start time of the item being composed.
        item.start.getAsync(
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully got the start time, display it, first in UTC and
                    // then convert the Date object to local time and display that.
                    console.write (‘The start time in UTC is: ‘ + asyncResult.value.toString());
                    console.write (‘The start time in local time is: ‘ + asyncResult.value.toLocaleString());
                }
            }
        );

        // Set the start time of the item being composed.
        var startDate = new Date("September 27, 2012 12:30:00");
        item.start.setAsync(
            startDate,
            { asyncContext: { var1: 1, var2: 2 } },
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully set the start time.
                    // Do whatever appropriate for your scenario
                    // using the arguments var1 and var2 as applicable.
                }
            }
        );

    });// end $(document).ready
}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用： 撰写邮件会议或约会（Compose）、读邮件会议或约会（Read）

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482538.aspx

Office.context.mailbox.item.location

Location Object 表示邮件会议或约会中的地点，它提供了方法来获取并设置会议地址， 该对象仅仅适用于邮件会议或约会， 因为只有邮件会议， 也即 Appointment Object 才有这个属性。

• Compose 模式下：Office.context.mailbox.item.location 返回一个 Location object，它提供了方法用来获取或设置会议的地址：

• Read 模式下：Office.context.mailbox.item.location 返回一个表示会议地点的字符串。

代码示例：

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var item = Office.context.mailbox.item;

        // Get the location of the item that the user is composing.
        item.location.getAsync(
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully got the location, display it.
                    console.write (‘The location is: ‘ + asyncResult.value);
                }
            }
        );

        // Set the location of the item that the user is composing.
        item.location.setAsync(
            ‘Conference room A‘,
            { asyncContext: { var1: 1, var2: 2 } },
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
                else {
                    // Successfully set the location.
                    // Do whatever appropriate for your scenario
                    // using the arguments var1 and var2 as applicable.
                }
            }
        );

    });// end $(document).ready
}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or Read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/dn482502.aspx

Recipients Object

Recipients Object提供了方法获取并设置邮件或约会的收件人。

• 对于 Message Object （即邮件信息条目），它的如下三个属性均是 Recipients 类型的 Object。 Office.context.mailbox.item.to，Office.context.mailbox.item.cc，Office.context.mailbox.item.bcc
• 对于 Appointment Object（即邮件约会条目），它的如下三个属性均是 Recipients 类型的 Object。 Office.context.mailbox.item.requiredAttendees， Office.context.mailbox.item.optionalAttendees， Office.context.mailbox.item.resources

Recipients Object 提供的方法有：

代码示例：

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var item = Office.context.mailbox.item;

        // Get the email addresses of all the recipients of the composed item.
        // Local objects to point to recipients of either
        // the appointment or message that is being composed.
        // bccRecipients applies to only messages, not appointments.
        var toRecipients, ccRecipients, bccRecipients;
        // Verify if the composed item is an appointment or message.
        if (item.itemType == Office.MailboxEnums.ItemType.Appointment) {
            toRecipients = item.requiredAttendees;
            ccRecipients = item.optionalAttendees;
        }
        else { // For Message Object.
            toRecipients = item.to;
            ccRecipients = item.cc;
            bccRecipients = item.bcc;
        }

        // Use asynchronous method getAsync to get each type of recipients
        // of the composed item. Each time, this example passes an anonymous
        // callback function that doesn‘t take any parameters.
        toRecipients.getAsync(function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                console.write(asyncResult.error.message);
            }
            else {
                // Async call to get to-recipients of the item completed.
                // Display the email addresses of the to-recipients.
                console.write (‘To-recipients of the item:‘);
            }
        }); // End getAsync for to-recipients.

        // Get any cc-recipients.
        ccRecipients.getAsync(function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                console.write(asyncResult.error.message);
            }
            else {
                // Async call to get cc-recipients of the item completed.
                // Display the email addresses of the cc-recipients.
                console.write (‘Cc-recipients of the item:‘);
            }
        }); // End getAsync for cc-recipients.

        // If the item has the bcc field, i.e., item is message,
        // get any bcc-recipients.
        if (bccRecipients) {
            bccRecipients.getAsync(function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    console.write(asyncResult.error.message);
                }
            else {
                // Async call to get bcc-recipients of the item completed.
                // Display the email addresses of the bcc-recipients.
                console.write (‘Bcc-recipients of the item:‘);
            }
            }); // End getAsync for bcc-recipients.
        }

    });// end $(document).ready
}

Office.js版本：此 Object 在 Office.js v1.1。

哪些 Outlook 模式中可用： 撰写邮件(Compose)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482517.aspx

Entities

Exchange Server 可以根据邮件内容检测出地理位置、邮箱地址、联系人信息、任务分配信息等， Entity 的识别依赖于自然语言的识别，而后者又要基于大量数据做机器学习才能做到，总的来说，entity的识别结果并不完全准确，识别的成功率很大程度上依赖于邮件中包含的特定语境信息。

我们可以利用 Office.context.mailbox.item.getEntities()/getEntitiesByType()/getFilteredEntitiesByName() 取出来这样一组信息集合，集合中包括如下几种类型的属性：

代码示例：

Office.context.mailbox.item.getEntities().taskSuggestions;

Office.context.mailbox.item.getEntitiesByType(EntityType.TaskSuggestion).taskSuggestions;

Office.context.mailbox.item.getEntities().emailAddresses；

Office.js版本：此 Object 在 Office.js v1.0 中引入。

哪些 Outlook 模式中可用： 读邮件 (ead)

最低权限要求： ReadItem 或 Restricted， 具体请查看每个 Entity 链接中的定义。

官方文档：https://msdn.microsoft.com/EN-US/library/office/fp160984.aspx

Office.context.mailbox.diagnostics

Diagnostics Object 提供用于 troubleshooting 的信息， Office.context.mailbox.diagnostics 的主要属性如下：

代码示例：

Office.context.mailbox.diagnostics.hostName

Office.js版本：此 Object 在 Office.js v1.0 中引入。

哪些 Outlook 模式中可用： 撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/jj715287.aspx