JavaScript API for Office Outlook Add-in - “一頁紙文檔“

本文轉載自查看原文 2015-08-19 10:36 1965 Office Add-in 開發/ Office Add-In Model/ Office 2013 Apps/ Apps for Office/ Office 開發

上一篇文章 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）、郵箱地址、用戶本地時區。

屬性(Property)	類型	描述
displayName	字符串(string)	用於顯示的用戶名.
emailAddress	字符串(string)	SMTP email address.
timeZone	字符串(string)	Host 當前 add-in 的應用程序（ Outlook richlient，或 OWA 等）中設置的時區信息。

代碼示例：

// 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 包含的方法和屬性分別有：

方法（Method）	Outlook 模式	描述	在什么版本引入
loadCustomPropertiesAsync	撰寫、讀郵件(Compose or read)	為某個特定的郵件條目提供自定義的屬性集合，這些屬性集合可以自由地添加或刪除，他們保存在郵件服務器上。適用於存儲一些針對於郵件條目的相關信息（可理解為郵件的 Property Bag）。	Version 1.0
getSelectedDataAsync	撰寫、讀郵件(Compose or read)	獲得郵件主題或郵件正文中被選中的數據。	Version 1.2
setSelectedDataAsync	撰寫、讀郵件(Compose or read)	插入數據到郵件主題或正文中的當前選中區域中。	Version 1.2
close	撰寫郵件(Compose)	關閉正在編輯的郵件，關於如何處理未保存的郵件，請參考該函數頁面的具體描述。	Version 1.3
saveAsync	撰寫郵件(Compose)	保存當前條目到草稿箱中。官網上說讀郵件(Read)模式下也可用，但是個人理解，這個函數應該只是在撰寫郵件模式下才可能調用。	Version 1.3

屬性（Property）	Outlook 模式	描述	在什么版本引入
dateTimeCreated	讀郵件(Read)	獲得當前郵件條目創建的日期和時間。	Version 1.0
dateTimeModified	讀郵件(Read)	獲得當前郵件條目最后被修改的日期和時間。	Version 1.0
itemClass	讀郵件(Read)	獲得當前郵件條目的類別。對於郵件約會條目，只有一個類別 IPM.Appointment；對於郵件信息條目，有如下幾種類別： IPM.Note IPM.Schedule.Meeting.Request IPM.Schedule.Meeting.Neg IPM.Schedule.Meeting.Pos IPM.Schedule.Meeting.Tent IPM.Schedule.Meeting.Canceled	Version 1.0
itemId	讀郵件(Read)	Gets the unique identifier for the item.	Version 1.0
itemType	撰寫、讀郵件(Compose or read)	Gets the type of the item.	Version 1.0

Item Object 是一個 base Object，其他的“表示特定條目的Object”（如 Appointment 和 Message ）都是它的擴展，可以根據 itemType 屬性來判斷是 Appointment 還是 Message。

Item type	Object
Meeting	Appointment
Message	Message

關於 Appointment 和 Message，以及 MettingRequest Object 它們分別特有的方法、屬性，可以參考如下鏈接，接下來一一羅列。

Appointment Object 表示當前約會條目

其包含的方法與屬性如下：

屬性名	Outlook 模式	描述	從什么版本開始引入
attachments	讀郵件（Read）	獲得郵件會議或約會的附件信息，下文也有針對 Office.context.mailbox.item.attachments 的介紹。	Version 1.0
body	撰寫郵件（Compose）	Gets a Body object that provides access the body text of the appointment.	Version 1.1
end	Compose or read	Gets a Date object that contains or a Time object that provides access to the date and time that the appointment is to end.	Version 1.0
location	Compose or read	Gets a string that contains or a Location object that provides access to the location of the appointment.	Version 1.0
normalizedSubject	Read	Gets the subject of the appointment, with all prefixes removed (including "RE:" and "FWD:").	Version 1.0
notificationMessages	Compose or read	Gets the notification messages for an appointment.	Version 1.3
optionalAttendees	Compose or read	Gets an EmailAddressDetails object that contains or a Recipients object that provides access to optional attendees.	Version 1.0
organizer	Read	Gets an EmailAddressDetails object that contains the organizer of the appointment.	Version 1.0
requiredAttendees	Compose or read	Gets an EmailAddressDetails object that contains or a Recipients object that provides access to required attendees.	Version 1.0
resources	Read	Gets an EmailAddressDetails object that contains a list of resources required for the meeting.	Version 1.0
start	Compose or read	Gets a Date object that contains or a Time object that provides access to the date and time that the appointment is to begin.	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 appointment with all prefixes.	Version 1.0

Method name	Outlook mode	Description	Introduced in
addFileAttachmentAsync	Compose	Adds files as attachments to the appointment.	Version 1.1
addItemAttachmentAsync displayReplyAllForm displayReplyForm	Compose Read Read	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.	Version 1.0

Method name	Outlook mode	Description	Introduced in
addFileAttachmentAsync	Compose	Adds files as attachments to the message.	Version 1.1
addItemAttachmentAsync displayReplyAllForm displayReplyForm	Compose Read Read	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.	Version 1.0
start	Read	Gets the time that the meeting is to start.	Version 1.0

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 表示當前郵件條目中包含的附件信息，它封裝了如下屬性：

屬性(Property)	類型	描述
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.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 表示當前郵件信息或約會條目的正文內容，它提供了一些方法來為郵件信息或約會條目增加/更新正文內容，如下表所示。

方法（Method）	描述
getAsync	以指定的格式（"html" 或 "text" ）獲得當前用戶在郵件主題或正文中選擇的數據，該API 從 Office.js v1.3 版本引入，在撰寫郵件、讀郵件(Compose or Read) 兩種模式下均可調用。
getTypeAsync	獲得郵件正文內容格式，取值可以為 "html" 或 "text"。 V1.1 中引入。
prependAsync	在郵件正文的前面添加指定的內容，This method was introduced in version 1.1.
setAsync	利用指定的內容替換掉郵件原有內容，在 v1.3 中引入。
setSelectedDataAsync	利用指定的內容替換掉正文中選中部分，v1.1 引入。

代碼示例：

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 提供用於獲得或設置郵件主題的方法：

方法（Method）	描述
getAsync	獲得郵件信息或約會的主題。
setAsync	設置郵件信息或約會的主題，overrides 原有的主題，但是原來的“轉發”、“Fwd：”、“Re：”將會保留。

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，它提供了方法用來獲取或設置會議起（或止）的時間：

方法（Method）	描述
getAsync	Gets the value of a start or end time
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.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，它提供了方法用來獲取或設置會議的地址：

方法（Method）	描述
getAsync	Gets the location of an appointment.
setAsync	Sets the location of an appointment.

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 提供的方法有：

方法（Method）	描述
addAsync	Adds recipients to the item.
getAsync	Gets the recipients of an item.
setAsync	Sets the recipients of an item.

代碼示例：

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() 取出來這樣一組信息集合，集合中包括如下幾種類型的屬性：

屬性名	Outlook 模式	描述	從什么版本開始引入
addresses	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條地理位置信息；如果不存在，返回 null。	Version 1.0
contacts	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條聯系人信息；如果不存在，返回 null。	Version 1.0
emailAddresses	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條 SMTP 郵箱信息；如果不存在，返回 null。	Version 1.0
meetingSuggestions	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條“會議建議”信息；如果不存在，返回 null。	Version 1.0
phoneNumbers	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條電話號碼；如果不存在，返回 null。	Version 1.0
taskSuggestions	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條“任務建議”；如果不存在，返回 null。	Version 1.0
urls	讀郵件（Read）	Exchange Server 2013 服務在郵件條目中檢測到的一條或多條 Internet Urls；如果不存在，返回 null。	Version 1.0

代碼示例：

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 的主要屬性如下：

Property name	Outlook mode	Description	Introduced in
hostName	Compose or read	Gets a string that represents the name of the host application for the mail app.	Version 1.0
hostVersion	Compose or read	Gets a string that represents the version of either the host application or the Exchange Server.	Version 1.0
OWAView	Compose or read	Gets a string that represents the current view of Outlook Web App.	Version 1.0

代碼示例：

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

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 Office Add-in 架構和入門在Visual Studio 中開發Office Add-in 詳解Office Add-in 清單文件一頁紙學習法 Office Add-in 設計規范與最佳實踐在Visual Studio Code中開發Office Add-in 在Office Add-in中實現單點登陸（SSO）一頁紙需求的應對方法 —— 五步法一頁打印4張PPT並鋪滿整個A4紙 width,height為多少px時，A4紙打印時剛好一頁?