Script Lab 05：Office JavaScript API助手，Excel 基礎操作（3）

準備工作

上一期内容中，為了建立一個工作表，曾用到一個 forceCreateSheet 的函數，是由 OfficeHelpers  命名空間下的 ExcelUtilities 類所提供的。本期我們就來講講 OfficeHelpers  的故事，這是 OfficeJS 提供的一個 Office JavaScript API 助手（office-js-helpers），用以簡化 WebAdd-ins 的開發。

這是一個開源項目，官網位址如下：

https://github.com/OfficeDev/office-js-helpers

OfficeHelpers

【功能】

OfficeHelpers 命名空間下，提供了一組幫助程式，用于簡化 Office 附加元件和 Microsoft Teams 頁籤的開發。這些幫助程式将功能作為存儲管理，身份驗證，對話和其他有用的實用程式等，比如最常用的錯誤記錄：

OfficeHelpers.UI.notifyerror);
OfficeHelpers.Utilities.log(error);      

認證主要包括了以下五個子產品：

1. 認證
2. 對話框
3. 錯誤記錄
4. 存儲助手
5. 字典

【用法】

在資源庫中，引用以下代碼：

https://appsforoffice.microsoft.com/lib/1/hosted/office.js
@types/office-js      

【示例】

從功能性來講，其最重要的功能之一便是認證（Authenticator）。Authentication helper 是為符合标準的 OAuth Implicit Flow 而建構的。開箱即用，可以友善接入 Microsoft、AzureAD、Google 和 Facebook 等身份驗證的內建。以 Microsoft 認證為例：

$("#run").click(() => tryCatch(run));

async function run() {
    await Excel.run(async (context) => {
        //
        var auth = new OfficeHelpers.Authenticator();
        //
        auth.endpoints.registerMicrosoftAuth('6bab39d1-c5a8-4da9-90f9-66f358362e50', {
            redirectUrl: 'https://script-lab.azureedge.net',
            scope: 'api://6bab39d1-c5a8-4da9-90f9-66f358362e50/access_as_user'
        });
        //
        auth.authenticate(OfficeHelpers.DefaultEndpoints.Microsoft)
            .then(tokenHandler)
            .catch(OfficeHelpers.Utilities.log);
        await context.sync();
    });
}

function tokenHandler(token: OfficeHelpers.IToken) {
    console.log(JSON.stringify(token, null, 4));
}

async function tryCatch(callback) {
    try {
        await callback();
    }
    catch (error) {
        OfficeHelpers.UI.notify(error);
        OfficeHelpers.Utilities.log(error);
    }
}      

其它可用認證的示例，還包括了：

// register Microsoft (Azure AD 2.0 Converged auth) endpoint using
authenticator.endpoints.registerMicrosoftAuth('client id here');


// register Azure AD 1.0 endpoint using
authenticator.endpoints.registerAzureADAuth('client id here', 'tenant here');


// register Google endpoint using
authenticator.endpoints.registerGoogleAuth('client id here');


// register Facebook endpoint using
authenticator.endpoints.registerFacebookAuth('client id here');


// register any 3rd-Party OAuth Implicit Provider using
authenticator.endpoints.add('Name of provider', { /* Endpoint Configuration - see office-js-helpers/src/authentication/endpoint.manager.ts */ })


// register Microsoft endpoint by overriding default values
authenticator.endpoints.registerMicrosoftAuth('client id here', {
    redirectUrl: 'redirect url here',
    scope: 'list of valid scopes here'
});      

【小技巧】

gist.github.com 被牆無法通路解決辦法：

windows下 打開C:\Windows\System32\drivers\etc\hosts檔案   

編輯器打開，在最後行添加192.30.253.118 gist.github.com

後記

小技巧中提到一個方法，此法小編親自測試有效，未來給大家分享代碼以及友善擷取代碼都用得上。這個還挺重要的，這為以後使用和建立代碼共享機制，提供了一個方向。小編未來可以很友善的把教程相關的代碼，直接分享到GITHUB上，友善大家一鍵獲到（通過一個gist連結即可）。

從今天開始，代碼和相關資源，都将分享在以下的QQ學習群上，友善大家自取。而代碼 yaml 格式進行分享。

 目錄索引

Script Lab 01：快速 Office 365 開發工具

Script Lab 02：Script Lab，知識儲備

Script Lab 03：Script Lab，啟動函數，Excel 基礎操作（1）

Script Lab 04：Script Lab，九九乘法表，Excel 基礎操作（2）

Script Lab 05：Office JavaScript API助手，Excel 基礎操作（3）

Script Lab 06：事件處理，Excel 基礎操作（4）

Script Lab 07：單詞“卡拉OK”，Word 基礎操作

Script Lab 08：異步調用函數，PowerPoint 基礎操作

Script Lab 09：為 Officejs 開發配置 VSCode 環境

Script Lab 10：OIfficeJS 的三種調試方式