2015年8月1日 星期六

[開發Office Add-Ins] Task Pane Add-Ins專案內容(4)

不管你是透過NAPA 或是Visual Studio來開發Office Add-Ins,建構出的Task Pane Add-Ins專案,在App Body的部分,結構都是底下這樣:

clip_image002

我們前面曾經提過,進入點Home.html是從manifest檔案那邊設定的,你當然可以改變這個設定。

整個App都是透過HTML與JavaScript撰寫,我們先來看Home.html部分。

Home.html

我們開啟Home.html,你會發現頁面結構如下:

clip_image004

你會發現主畫面<Body>標記裡面被兩個<div>區分,分別是content-header,以及content-main。(上圖)

content-header的部分是標題,呈現出來向是底下的『歡迎』部分:

clip_image006

而content-main則是上圖除了藍色的歡迎區塊以外的其他內容。一般來說我們把App主程式放在content-main當中。

前面說過,這個Home.html是app的進入點,是在Manifest當中設置的,當然,你也可以在專案中新增一個或多個HTML Page,我會建議你直接在Visual Studio當中複製Home.html即可:

clip_image008當然,複製完後你要修改一下檔名(例如Page2.html)。接著,我們來修改一下Home.html的內容:

clip_image010

我們加上了一行程式碼:

<button onclick="javascript: location.href = 'Page2.html';">跳到Page2</button>

你會發現,主頁面上多了一個Button,並且,點選之後會跳到另一個Page2.html:

clip_image002[6]

這沒什麼,就是網頁的基本行為,對於常寫JavaScript的開發人員來,就是家常便飯一般。

不過,從這邊你就看的出來,我們的Task Pane Add-Ins,基本上就是一個Html page,而上面可以運行JavaScript,必要時我們可以撰寫多個html,透過JavaScript在多個頁面中切換。

Home.js

緊接著,我們來看看Home.js這個檔案,從Home.html的頁面上我們發現,這是該Page所引入的唯一一個直屬javascript file(另外兩個是office.js與App.js)。

該檔案內容如下:

clip_image004[7]

沒了,就這樣,簡單到不行。

其中第一個部分,是在Document Ready時,做一個hook按鈕『get-data-from-selection』的Click事件的動作:

當按鈕『get-data-from-selection』被按下,則getDataFromSelection會被觸發。

而getDataFromSelection的內容是:

留意getSelectedDataAsync這個Method,它是由Office.context.document.而來的,依照慣例,微軟掛上『Async』字尾的Method,都是非同步的API,因此一定會有一個call back函式,上面例子中,就是後面的這一段function:

function (result) {
    if (result.status === Office.AsyncResultStatus.Succeeded) {
        app.showNotification('選取的文字為:', '"' + result.value + '"');
    } else {
        app.showNotification('錯誤:', result.error.message);
    }
}

getSelectedDataAsync這個Method,是取得當前文件上的被選取區段,取得之後,就調用上面這個function,將取得的物件以result這個名稱傳入,傳入後,可由result.status判斷剛才的動作是否成功,如果成功,則把取得的用戶選取區域的內容(result.value)顯示出來:

app.showNotification('選取的文字為:', '"' + result.value + '"')

程式碼就這樣而已,很單純。

上面的『app.showNotification』,是在add-in的下方呈現出一個訊息顯示區塊,有這區塊可用,是app.js的功勞:

clip_image002[8]

1-1-1 App.js

如果我們開啟App.js,不難發現其中的內容,就是幫我們建構一塊訊息顯示區域,並提供API讓我們可以藉以調用,顯示出訊息:

clip_image004[9]

上面這一段code中的app.initialize,則是在home.js當中被叫用的:

clip_image006[6]

到這邊為止,您應該已經很瞭解整個Task Pane Add-Ins的架構了,後面,我們要來看幾個常見的API。

沒有留言: