上一篇文章 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 以及它所提供的方法和属性。
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.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
// 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
Adds mailbox items as attachments to the appointment.
Displays a reply form including organizer and attendees.
Displays a reply form including only the organizer.
Version 1.1
Version 1.0
Version 1.0
getEntities
Read
Returns all entities recognized in the appointment.
Version 1.0
getEntitiesByType
Read
Returns all entities of the specified type recognized in the appointment.
Version 1.0
getFilteredEntitiesByName
Read
Returns all matches recognized in the appointment that meet the requirements of the named filter.
Version 1.0
getRegExMatches
Read
Returns all regular expression matches recognized in the appointment.
Version 1.0
getRegExMatchesByName
Read
Returns all regular expression matches recognized in the appointment using the named regular expression.
Version 1.0
removeAttachmentAsync
Compose
Removes a specified or all attachments from the appointment.
Version 1.1
Message Object 表示当前邮件信息条目（区别于会议或约会）
Property name
Outlook mode
Description
Introduced in
attachments
Compose
Gets an array of attachments for the message.
Version 1.0
body
Compose
Gets a Body object that provides access the body text of the message.
Version 1.1
bcc
Compose
Gets a Recipients object that provides access to each recipient on the Bcc line of the message.
Version 1.1
cc
Compose or read
Gets a collection EmailAddressDetails object that contains or a Recipients object that provides access to each recipient on the Cc line of the message.
Version 1.0
conversationId
Compose or read
Gets the identifier for the conversation that the message is associated with.
Version 1.0
from
Read
Gets an EmailAddressDetails object for the message sender.
Version 1.0
internetMessageId
Read
Gets the unique Internet message identifier for the message.
Version 1.0
normalizedSubject
Read
Gets the subject of the message, with all prefixes removed (including "RE:" and "FWD:").
Version 1.0
notificationMessages
Compose or read
Gets the notification messages for a message.
Version 1.3
sender
Read
Gets an EmailAddressDetails object for the message sender.
Version 1.0
subject
Compose or read
Gets a string that contains or a Subject object that provides access to the complete subject of the message with all prefixes.
Version 1.0
to
Compose or read
Gets a collection EmailAddressDetails object that contains or a Recipients object that provides access to each recipient on the To line of the message.
Adds mailbox items as attachments to the message.
Displays a reply form that includes the sender and all recipients of the selected message.
Displays a reply form that includes only the sender of the selected message.
Version 1.1
Version 1.0
Version 1.0
getEntities
Read
Returns all entities found in the message.
Version 1.0
getEntitiesByType
Read
Returns all entities of the specified type found in the message.
Version 1.0
getFilteredEntitiesByName
Read
Returns all matches recognized in the message that meet the requirements of the named filter.
Version 1.0
getRegExMatches
Read
Returns all regular expression matches found in the message.
Version 1.0
getRegExMatchesByName
Read
Returns all regular expression matches recognized in the message using the named regular expression.
Version 1.0
removeAttachmentAsync
Compose
Removes a specified or all attachments from the message.
Version 1.1
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.）
Property name
Outlook mode
Description
Introduced in
end
Read
Gets the time that the meeting is to end.
Version 1.0
location
Read
Gets the location of the meeting.
Version 1.0
optionalAttendees
Read
Gets the list of optional attendees for the meeting.
Version 1.0
requiredAttendees
Read
Gets the list of required attendees for the meeting.
Version 1.0
resources
Read
Gets the list of resources needed for the meeting.
// 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.
});
}
attachmentType
Office.MailboxEnums.AttachmentType
Gets one of the AttachmentType enumeration values that indicates whether the attachment is an Exchange item or a file.
contentType
字符串(string)
Gets the MIME content type of the attachment.
id
字符串(string)
Gets the Exchange Web Services (EWS) attachment identifier for the attachment.
isInline
布尔(boolean)
Gets a value that indicates whether the attachment is an inline attachment. The isInline property indicates whether an attachment, such as an embedded image, should be displayed in the item.
name
字符串(string)
Gets the name of the attachment.
size
整型(integer)
Gets the size of the attachment in bytes. An integer that contains the size of the attachment in bytes.
其中 Office.MailboxEnums.AttachmentType 是个枚举类型，可取的值包括：
Enumeration值描述
Office.MailboxEnums.AttachmentType.File
"file"
The attachment is a file.
Office.MailboxEnums.AttachmentType.Item
"item"
The attachment is an Exchange item.
代码示例：
// An array of AttachmentDetail objects is returned as the attachments property of an Item,
// Appointment, or Message objects.
Office.context.mailbox.item.attachments
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 对象都没有这些属性）。
setAsync
Sets the value of a start or end time。 参数是一个表示 UTC 时间的 Date-Tme Object，可以利用 Mailbox.convertToUtcClientTime 获得相应的 UTC 时间
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.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
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
}
QQ群⑧：
窥视卡
雷达卡
发表于 2015-9-13 07:27:02
提升卡
置顶卡
沉默卡
喧嚣卡
变色卡
千斤顶
显身卡