Office Add-in Model 为 Mail Add-in 提供的 JavaScript API 介绍

Office

表示Add-in的一个实例，它是调用其它API相关的object（如Context等）的入口。

Office.js版本：

Introduced in v1.0

Last changed in v1.1

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

N/A

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp142234.aspx

Context

Add-in的运行时环境信息，并提供调用关键Object上 API的入口

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

N/A

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

Mailbox

为office   add-in Object Model 提供访问入口

(Provides access to the app   for Office object model for Microsoft Outlook 2013 and Microsoft Outlook Web   App.)

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadWriteMailbox,   but some members accessible with lesser permissions

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142162.aspx

UserProfile

用来获取通过当前邮件使用mailbox add-in的用户的信息，它有如下几个属性：

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件(Compose   or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp161126.aspx

Item

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

Item object 是一个base Object，其他的“表示特定条目的Object”（如Appointment和Message）都是它的扩展。

1. Appointment   Object表示当前约会条目
2. Message Object 表示当前邮件信息
3. MeetingRequest Object 扩展了 Message Object，表示一个会议邀请。（The MeetingRequest object is returned as the item property of the Mailbox object. The MeetingRequest   object extends the Message object. Represents a request to attend a   meeting.）

注意: 下面介绍的 Office.context.mailbox.item

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

Office.js版本：

Introduced in v1.0

Last changed in v1.3

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

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

AttachmentDetails

当前条目中包含的附件信息

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/jj984592.aspx

Body

当前信息或约会条目的正文内容

(该类型提供了针对邮件正文的方法，如setSelectedDataAsync)

Office.js版本：

Introduced in v1.1

Latest changed in v 1.3

在如下 Outlook 模式中可用：

撰写邮件

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/dn482486.aspx

Subject

提供用来获取和设置邮件主题的方法

(Provides methods to get and set the   subject of a meeting or message)

在撰写邮件（Compose）模式下：

Office.context.mailbox.item.subject 返回邮件会议或邮件信息的Subject对象，它提供了两种方法----- setAsync 和 getAsync。

SetAsync发送通过向 Exchange server 异步发送请求设置邮件会议或邮件信息的主题。设置主题时，会overrides原有的主题，但是原来的“转发”、“Fwd：”、“Re：”将会保留。

getAsync则可用来获得邮件主题。

在读邮件（Read）模式下：

Office.context.mailbox.item.subject 返回邮件会议或者邮件信息的主题（字符串）

撰写邮件模式下：

SetAsync具体使用，请参照官方文档https://msdn.microsoft.com/en-us/library/office/dn482531.aspx。

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

读邮件模式下：

Office.context.mailbox.item.subject 返回邮件的主题（字符串）

Office.js版本：

Introduced   in v1.1

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose  or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482528.aspx

Time

提供用于获取和设置会议起止时间的方法

仅仅适用于邮件会议或约会，即 Appointment才有start或end属性。

在撰写邮件（Compose）模式下：

Office.context.mailbox.item.start（或end）

返回一个Time   object，Time 对象提供了方法用来获取或设置会议起（或止）的时间。

在读邮件（Read）模式下：

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

Office.context.mailbox.item.start

https://msdn.microsoft.com/en-us/library/office/fp161129.aspx

Office.context.mailbox.item.end

https://msdn.microsoft.com/en-us/library/office/fp142183.aspx

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件会议或约会（Compose）、读邮件会议或约会（Read）

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482538.aspx

CustomProperties

为某个特定的邮件条目提供自定义的属性集合

Office.js版本：

Introduces in v1.0

在如下 Outlook 模式中可用：

？？？？

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142138.aspx

RoamingSettings

用来存储per   user，per add-in的custom settings

不同于CustomProperties，RoamingSettings中的值只能被创建该值的用户所访问，并且只能在被创建该值的add-in中访问到。

Setting的key是字符串类型的，value的类型则可以是string、number、boolean、null、object或者array。

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

（The settings created   by using the methods of the RoamingSettings object   are saved per app and per user. That is, they are available only to the app   that created them, and only from the user‘s mail box in which they are saved.）

The RoamingSettings   object is automatically loaded as part of the Context object, and is available by calling the roamingSettings property of that object when the add-in is   activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to   save the settings in the user‘s mailbox.

// 从setting中获得值：
_settings = Office.context.roamingSettings;
_customerName = _settings.get("customerName");

// 添加新的key/value pair：
_settings.set("cookie", Date());
_settings.saveAsync(saveMyAppSettingsCallback);

更多的实例，请参考官方文档https://msdn.microsoft.com/en-us/library/office/fp161171.aspx。

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件(Compose or read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/en-us/library/office/jj220079.aspx

Entities

Exchange Server 2013 server在邮件信息或约会中找到的entity集合，包括addresses，contacts，emailAddresses等等。

Entity集合中包含的内容详见下文中另一个表格

getEntities()

Entity 的识别依赖于自然语言的识别，而后者又要基于大量数据做机器学习才能做到，总的来说，entity的识别结果并不完全准确，识别的成功率很大程度上依赖于邮件中包含的特定语境信息。

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

(Read)

最低权限要求：

ReadItem   but some properties accessible with Restricted.

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp160984.aspx

Location

该Object为会议或约会地点提供了get和set方法

Office.context.mailbox.item.location

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

写邮件

(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/dn482502.aspx

Recipients

利用该Object可以取得或者设置收件人。

如下Object的列出的各属性值均是Recipients 类型。

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件

(Compose)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482517.aspx

Diagnostics

提供用于troubleshooting的信息

Office.context.mailbox.diagnostics

Office.js版本：

Introduced in V1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/jj715287.aspx

Error

异步数据操作出错时的返回信息

(Provides specific information about an   error that occurred during an asynchronous data operation.)

asyncResult.error

Office.js版本：

Intro in v1.0

Changed in   v1.1

在如下 Outlook 模式中可用：

?

最低权限要求：N/A

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp161033.aspx

EmailAddressDetails

邮件地址详细信息

(该类型只是几个字段的封装，并不提供API调用)

Recipients.addAsync 方法可接受 EmailAddressDetails 类型的数组

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp161105.aspx

EmailUser

基于Exchange   Server 2013 的邮箱服务器上的邮箱账号（Represents an email account on an Exchange   Server 2013 server.）

(该类型只是几个字段的封装，并不提供API调用)

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

（Read）

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142187.aspx

Contacts

Exchange Server 2013 服务在邮件信息或约会条目中找到的联系人数组。

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

Introduced in v1.0

读邮件(Read)

Restricted

https://msdn.microsoft.com/EN-US/library/office/fp142242.aspx

MeetingSuggestion

Exchange Server 2013 服务在邮件信息或约会条目中找到的会议提议

(Represents a suggested meeting found in   an item.)

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

Office.context.mailbox.item.getEntitiesByType

(Office.MailboxEnums.EntityType.MeetingSuggestion).meetingSuggestions;

Intro   in1.0

读邮件(Read)

ReadItem

https://msdn.microsoft.com/EN-US/library/office/fp142141.aspx

PhoneNumber

Exchange Server 2013 服务在邮件信息或约会条目中找到的电话号码

Represents a phone number   identified in an item.

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

Introduced in v1.0

读邮件(Read)

Restricted

https://msdn.microsoft.com/en-us/library/office/fp142244.aspx

TaskSuggestion

Exchange Server 2013 服务在邮件信息或约会条目中找到的任务分配建议

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

Office.context.mailbox.item.

getEntitiesByType(EntityType.TaskSuggestion).taskSuggestions;

Introduced   in v1.0

读邮件(Read)

ReadItem

https://msdn.microsoft.com/en-us/library/office/fp160979.aspx

addresses

Exchange Server 2013 服务在邮件信息或约会条目中找到的地理位置

To be recognized   as an address, the string must contain a United States postal address that   has at least a subset of the elements of a street number, street name, city,   state, and zip code.

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

Introduced in v1.0

读邮件(Read)

Restricted

https://msdn.microsoft.com/EN-US/library/office/fp160959.aspx

emailAddresses

Exchange Server 2013 服务在邮件信息或约会条目中找到的SMTP邮件地址。

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

Introduced   in v1.0

读邮件(Read)

ReadItem

https://msdn.microsoft.com/EN-US/library/office/fp161123.aspx

urls

Exchange Server 2013 服务在邮件信息或约会条目中找到的internet URL.

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

Introduced in v1.0

读邮件(Read)

Restricted

https://msdn.microsoft.com/EN-US/library/office/fp142254.aspx