[開發Office Add-Ins]常用API - setSelectedDataAsync(5)

先前我們談到，我們在開發Office Add-Ins(特別是Task Pane與Content Add-in)時，大部分的API都從『Office.context.document…』而來，而這個從Office開頭的API，來源就是我們在html頁面上所引入的Office.js，請注意，Office.js並非一個檔案，而是一整組 office.js ，這是一大組 javaScript files的集合，如果你透過Visual Studio開發的話，可以看到專案目錄下有許多檔案:
其中的細節我們後面有機會再討論，先來看看我們常用的兩個API。getSelectedDataAsync與setSelectedDataAsync這兩個方法。

設定(填入)選取區域

我們先看setSelectedDataAsync這個方法的定義：

範例：

Office.context.document.setSelectedDataAsync(data [, options], callback);

其中data參數的可用內容如下：

參數	內容	備註
data	string (Office.CoercionType.Text)	Excel、 Excel Online、 PowerPoint、 PowerPoint Online、 Word，以及只Word Online
	array的陣列 (Office.CoercionType.Matrix)	Excel、 Word，以及只Word Online
	TableData (Office.CoercionType.Table)	Access、 Excel、 Word、 僅限Word Online
	html	Word，並只Word Online
	Office Open XML	僅限Word

基本上setSelectedDataAsync的功能就是將特定的文字或物件，填入當前用戶在文件當中的選取區域。 例如，底下這段很簡單的程式碼，可將特定文字填入文件當中： // 從目前文件選取範圍讀取資料，並且顯示通知
function FillText() {
    //調用API填入文字
    Office.context.document.setSelectedDataAsync("測試填入文字",
    //call back
    function (asyncResult) {
        var error = asyncResult.error;
        //如果失敗
        if (asyncResult.status == "failed") {
            //顯示失敗訊息
            app.showNotification(error.name + ": " + error.message);
        }
        else {
            //顯示成功訊息
            app.showNotification('成功!');
        }
    });
}
按下Button之後，執行結果如下： 當然，可以填入的不僅僅是文字而已，試試看底下這段程式碼： function FillTable() {
    //調用API填入文字
    Office.context.document.setSelectedDataAsync([['張三', '李四', '王五'], ['A', 'B', 'C'], ['123', '456', '789']],
    //call back
    function (asyncResult) {
        var error = asyncResult.error;
        //如果失敗
        if (asyncResult.status == "failed") {
            //顯示失敗訊息
            app.showNotification(error.name + ": " + error.message);
        }
        else {
            //顯示成功訊息
            app.showNotification('成功!');
        }
    });
}
執行的結果如下： 你會發現，setSelectedDataAsync除可以填入文字之外，如果你填入陣列類型的資料，在Word當中則會變成表格，在Excel當中自然就是直接變成儲存格內容了：
非常簡單的API，是吧? 我們後面再來看我們用過多次的getSelectedDataAsync。