探討JavaScript API for Office：郵件應用程式

本文是深入探討 JavaScript API for Office 的第四部分，重點討 論 Outlook 和 Outlook Web 應用程式所支援的郵件應用程式的可用 API 部分。 假設您對於 Office 的應用程式已有基本瞭解。如果有疑問，閱讀開發人員中心 文檔頁上的“用於 Office 的應用程式概述”(bit.ly/12nBWHG) 可以獲得相關知識。本系 列第一部分，“探索新的 JavaScript API for Office”(msdn.microsoft.com/m agazine/jj891051) 高度概述了以 Office 對象為根對象的物件模型。 Office.context 中的 Mailbox 對象為物件模型中絕大多數郵件應用程式專用功 能提供了入口，我將從這裡開始討論。

本文的主題是向開發人員介紹 JavaScript API for Office 在郵件應用程式中的應用。我還在以下地址提供了 一篇線上姊妹篇文章，其中對一個郵件應用程式樣本進行了剖析，並提供了源代 碼：msdn.microsoft.com/m agazine/dn205107。現在我要討論 JavaScript API for Office 的各種功能 ，我們先從較基本的常用技巧開始，然後介紹比較高深的概念。

JavaScript API for Office 的準系統

Mailbox 對象提供對 使用者設定檔、使用者當前選擇的項目、顯示項目的表單和操控電子郵箱中項目和 檔案夾的 Exchange Web Services (EWS) 子集的訪問。Item 對象表示選定的郵 件或約會項。通過該對象，可以進一步訪問內建屬性、自訂屬性和該項目的附 件。

根據項類型控制啟用 可以在清單中定義規則，用以確定何時啟用郵 件應用程式。使用者當前選定並由 Mailbox.item 指定的項可以是一個“郵件”（ 包括會議邀請、響應和取消通知）對象或“約會”對象。根據具體方案，可以限 制郵件應用程式，使其只啟用特定類型的項。以下 XML 樣本顯示的是一個 ItemIs 啟用規則，用來限制郵件應用程式，使其只啟用訊息類項：

 

<Rule xsi:type="ItemIs" ItemType="Message" />

使用 JavaScript API for Office，可以利用 itemType 屬性確 認選定項的類型：

             Office.context.mailbox.item.itemType            

項訪問和屬性 郵件應用程式提供的一個準系統是訪問當 前選定的項及其內建屬性。

以下 JavaScript 樣本顯示如何訪問選定的項 及其內建屬性 subject：

          // The initialize function is required for all apps.          Office.initialize = function () {  // Check for the DOM to load.          $(document).ready(function () {    var item = Office.context.mailbox.item;    var subject = item.subject;    // Continue processing the subject.          });}

已知實體 無論您是否使用實體啟用郵件應用程式，Exchange Server 都能識別可用的部分實體。 如果實體存在於選定項的主題或本文內，Outlook 和 Outlook Web App 會提取它們，並通過以下 JavaScript API 方法使其可用：

   getEntities 方法    getEntitiesByType(entityType) 方法    getFilteredEntitiesByName(name) 方法

所支援的實體包 括地址、連絡人、電子郵件地址等。

請注意，無論應用程式資訊清單中指定何 種預設區域設定，Outlook 和 Outlook Web App 都只能提取英文字串。 它們 不能提取“已發送郵件”檔案夾中的實體。 它們能提取訊息類型的會議建議，不 能提取約會類型的建議。

擷取可產生上下文啟用的匹配項 可以指定依賴 於Regex匹配（ItemHasRegularExpressionMatch 規則）或選定項中實體匹 配（ItemHasKnownEntity 規則）的啟用規則。 可以使用以下方法擷取正則表達 式匹配： 這些方法在父級 Item 對象中可用，而該對象可以是訊息類型或約會類 型的：

   getRegExMatches 方法    getRegExMatchesByName(name) 方法

可以使用“已知實體 ”部分列出的方法擷取特定實體匹配。 請注意，無論郵件應用程式使用何種類型 的啟用規則，始終可以使用這些方法擷取任何實體匹配。

樣本 以下是一 個名為 VideoURL 的 ItemHasRegularExpressionMatch 規則樣本，如果選定的項 是一封郵件且郵件內文包含 YouTube 上某個視頻的 URL，則它會啟用郵件應用程 序：

          <Rule xsi:type="RuleCollection" Mode="And">  <Rule xsi:type="ItemIs" ItemType="Message"/>  <Rule xsi:type="ItemHasRegularExpressionMatch"    RegExName="VideoURL"    RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}"    PropertyName="Body"/></Rule>

以下 JavaScript 程式碼範例顯示如何使用 Item.getRegExMatches 方法擷取 前面 VideoURL Regex的匹配項：

          Office.initialize = function () {  // Check for the DOM to load.          $(document).ready(function () {    // Get an array of string matches for the regular expression VideoURL,    // as specified in the manifest.          var matches = Office.context.mailbox.item.getRegExMatches().VideoURL;    // Continue processing the matches for the regular expression.          });}