SharePoint Framework 把你的客戶端web部件連線到SharePoint

Justin-Liu發表於2016-10-30
Framework客戶端Web
部落格地址：http://blog.csdn.net/FoxDave

把你的web部件連線到SharePoint來訪問SharePoint中的功能和資料，為終端使用者提供更完整的體驗。本篇會基於之前構建的hello world的web部件繼續改進。

執行gulp serve

不多數，這步還是首要的，否則沒法進行除錯的。確保你已經在命令列中執行了gulp serve這個命令。

訪問頁面上下文

當本地工作臺被承載起來的時候，你是無法獲得SharePoint頁面上下文的，當然你仍然能用許多不同的方式測試你的web部件。比如，你可以專注於構建web部件的UX（使用者體驗），使用假資料去模擬與SharePoint的互動。

但是當工作臺在SharePoint中承載時，你就可以訪問頁面上下文了，上下文提供了很多關鍵的屬性，如：

>網站標題

>網站絕對URL

>網站相對URL

>使用者登入名

你可以在web部件類中使用下面的變數訪問頁面上下文：

this.context.pageContext
切換到Visual Studio code（或者是你喜歡的IDE），開啟檔案src\webparts\helloWorld\HelloWorldWebPart.ts。

在render方法中，用下面的程式碼替換程式碼塊中的innerHTML部分：

this.domElement.innerHTML = `
<div class='${styles.helloWorld}'>
    <div class='${styles.container}'>
        <div class='ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}'>
        <div class='ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1'>
            <span class='ms-font-xl ms-fontColor-white'>Welcome to SharePoint!</span>
            <p class='ms-font-l ms-fontColor-white'>Customize SharePoint experiences using Web Parts.</p>
            <p class='ms-font-l ms-fontColor-white'>${this.properties.description}</p>
            <p class='ms-font-l ms-fontColor-white'>Loading from ${this.context.pageContext.web.title}</p>
            <a href='https://github.com/SharePoint/sp-dev-docs/wiki' class='ms-Button ${styles.button}'>
                <span class='ms-Button-label'>Learn more</span>
            </a>
        </div>
        </div>
</div>
</div>`;

注意一下${ }是如何被用來在HTML塊中輸出變數的。一個額外的HTML的P標籤用來顯示this.context.pageContext.web.title屬性。由於這個web部件現在是從本地環境載入的，標題會顯示為Local Workbench。

儲存檔案，執行著的gulp serve會發現儲存操作並：

>自動編譯和打包更新的程式碼。

>重新整理你的本地工作臺頁面（因為web部件程式碼需要重新載入）。

你可以將Visual Studio Code和命令列窗體左右排列放在一起，就能發現上述的機制。

在你的瀏覽器中，訪問本地的workbench.html，連結為：http://localhost:4321/temp/workbench.html，如下圖。

下面我們們訪問SharePoint的workbench.aspx，完整的URL是這樣的格式，具體的domain自行修改：https://your-sharepoint-site-url/Shared%20Documents/workbench.aspx。

我們仍然用Chrome去看一下效果，如下圖，可以看到能夠讀取到網站的標題了。

定義列表模型

你需要一個列表模型去開始跟SharePoint列表資料互動，你需要兩個模型來獲取列表。

切換到Visual Studio Code，開啟檔案src\webparts\helloWorld\HelloWorldWebPart.ts。

在HelloWorldWebPart類的上方定義如下的介面模型：

export interface ISPLists {
    value: ISPList[];
}

export interface ISPList {
    Title: string;
    Id: string;
}

新增完程式碼的檔案如下圖所示，ISPList介面用來掌管我們要連線的SharePoint列表資訊。

從模擬儲存獲取列表

你需要一個假的儲存去返回假的資料來測試本地的工作臺。

在src\webparts\helloWorld路徑建立一個名為MockHttpClient.ts的新檔案，在專案結構上的helloWorld節點右鍵，選擇New File。

然後在新建的檔案中輸入以下程式碼：

import { ISPList } from './HelloWorldWebPart';

export default class MockHttpClient {

    private static _items: ISPList[] = [{ Title: 'Mock List', Id: '1' }];
    
    public static get(restUrl: string, options?: any): Promise<ISPList[]> {
    return new Promise<ISPList[]>((resolve) => {
            resolve(MockHttpClient._items);
        });
    }
}

關於上面的程式碼需要知道以下幾點：

>由於在HelloWorldWebPart.ts檔案中有很多匯出，特定的一個匯入使用大括號｛｝指定了。在這裡，只需要匯入資料模型ISPList。

>當從預設模組匯入時（這裡是HelloWorldWebPart），你不需要輸入檔案的副檔名。

>它將MockHttpClient類匯出為預設模組，這可以在其他檔案被匯入。

>它編譯初始的ISPList模擬陣列並返回。

儲存檔案，現在你可以在HelloWorldWebPart類中使用MockHttpClient類了。首先你需要匯入MockHttpClient模組。

開啟HelloWorldWebPart.ts檔案。

在程式碼import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';的下面貼上下面的程式碼：

import MockHttpClient from './MockHttpClient';

在HelloWorldWebPart類中新增下面的私有方法來模擬獲取列表的操作。

private _getMockListData(): Promise<ISPLists> {
    return MockHttpClient.get(this.context.pageContext.web.absoluteUrl)
        .then((data: ISPList[]) => {
             var listData: ISPLists = { value: data };
             return listData;
         }) as Promise<ISPLists>;
}

儲存檔案，新增完程式碼之後的檔案如下圖：

從SharePoint網站獲取列表

接下來你需要從當前SharePoint網站獲取列表。你將會使用SharePoint REST API來從網站獲取列表資料，該操作的地址為https://yourtenantprefix.sharepoint.com/_api/web/lists。

在HelloWorldWebPart類中新增下面的方法來從SharePoint中獲取列表資料：

private _getListData(): Promise<ISPLists> {
return this.context.httpClient.get(this.context.pageContext.web.absoluteUrl + `/_api/web/lists?$filter=Hidden eq false`)
        .then((response: Response) => {
        return response.json();
        });
}

該方法使用了一個httpClient幫助類，這個類在SharePoint客戶端平臺上可用來執行REST API。上面的程式碼中它使用ISPLists模型並應用了不獲取隱藏列表的篩選條件。

儲存檔案，切換到執行gulp serve的命令列視窗看看是否有錯誤發生。如果有錯誤發生的話需要先修復錯誤再往後繼續。

新增新的樣式

SharePoint Framework使用Sass作為CSS前處理器，特別使用了SCSS語法，該語法完全符合正常的CSS語法。Sass擴充套件了CSS語言，允許你使用像變數、巢狀規則和內聯匯入等功能來為你的web部件組織和建立高效的樣式表。SharePoint Framework裡面已經提供了SCSS編輯器，它可以將你的Sass檔案轉換成正常的CSS檔案，同時還在開發過程中提供了型別的版本。

要想新增新的樣式，開啟檔案HelloWorld.module.scss，在這個SCSS檔案中定義你自己的樣式。

預設情況下，樣式的範圍是你的web部件，你可以看到定義在.helloWorld下的樣式。

在.button樣式下新增下面的樣式：

.list {
    color: #333333;
    font-family: 'Segoe UI Regular WestEuropean', 'Segoe UI', Tahoma, Arial, sans-serif;
    font-size: 14px;
    font-weight: normal;
    box-sizing: border-box;
    margin: 10;
    padding: 10;
    line-height: 50px;
    list-style-type: none;
    box-shadow: 0 4px 4px 0 rgba(0, 0, 0, 0.2), 0 25px 50px 0 rgba(0, 0, 0, 0.1);
}

.listItem {
    color: #333333;
    vertical-align: center;
    font-family: 'Segoe UI Regular WestEuropean', 'Segoe UI', Tahoma, Arial, sans-serif;
    font-size: 14px;
    font-weight: normal;
    box-sizing: border-box;
    margin: 0;
    padding: 0;
    box-shadow: none;
    *zoom: 1;
    padding: 9px 28px 3px;
    position: relative;
}

儲存檔案，gulp會馬上將程式碼重新編譯，這也會在HelloWorld.module.scss.ts檔案中同時生成相應的型別。一旦編譯為typescript，你就能在你的web部件程式碼中匯入並引用這些樣式了。

你可以看到web部件中的render方法。

<div class="${styles.container}">

獲取展示列表資訊的方法

開啟HelloWorldWebPart類檔案。SharePoint工作臺提供了足夠的靈活性，使你可以在本地環境和SharePoint中測試web部件。SharePoint Framework旨在藉助這種能力通過使用EnvironmentType模組幫助你瞭解你的web部件執行在哪個環境。

你首先需要從@microsoft/sp-client-base包中匯入EnvironmentType模組，將下面的程式碼新增到匯入部分：

import { EnvironmentType } from '@microsoft/sp-client-base';

將下面的私有方法新增到HelloWorldWebPart類中去呼叫各自的方法獲取列表資料：

private _renderListAsync(): void {
    // Local environment
    if (this.context.environment.type === EnvironmentType.Local) {
        this._getMockListData().then((response) => {
        this._renderList(response.value);
        }); }
        else {
        this._getListData()
        .then((response) => {
            this._renderList(response.value);
        });
    }
}

關於_renderListAsync方法中承載型別的說明：

>this.context.environment.type屬性會幫助你檢查當前是處在本地環境還是SharePoint環境。

>呼叫哪個方法取決於你的工作臺在哪承載。

>目前會提示_renderList找不到，不要著急，下面會補全。

儲存檔案，現在你需要將從REST API獲取到的列表資料展示出來。將下面的私有方法新增到HelloWorldWebPart類中：

private _renderList(items: ISPList[]): void {
    let html: string = '';
    items.forEach((item: ISPList) => {
        html += `
        <ul class="${styles.list}">
            <li class="${styles.listItem}">
                <span class="ms-font-l">${item.Title}</span>
            </li>
        </ul>`;
    });

    const listContainer: Element = this.domElement.querySelector('#spListContainer');
    listContainer.innerHTML = html;
}

該方法通過styles這個變數引用了之前新新增的CSS樣式，儲存檔案，沒有問題的話會彈出一個編譯成功的提示。

獲取列表資料

定位到render方法，然後用下面的程式碼替換原來的內容：

this.domElement.innerHTML = `
<div class="${styles.helloWorld}">
    <div class="${styles.container}">
        <div class="ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}">
            <div class="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
                <span class="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>
                <p class="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>
                <p class="ms-font-l ms-fontColor-white">${this.properties.description}</p>
                <p class="ms-font-l ms-fontColor-white">${this.properties.test2}</p>
                <p class='ms-font-l ms-fontColor-white'>Loading from ${this.context.pageContext.web.title}</p>
                <a href="https://github.com/SharePoint/sp-dev-docs/wiki" class="ms-Button ${styles.button}">
                    <span class="ms-Button-label">Learn more</span>
                </a>
            </div>
        </div>
    <div id="spListContainer" />
    </div>
</div>`;

this._renderListAsync();

儲存檔案，同樣gulp serve會自動進行編譯，確保沒有發生任何錯誤。

切換到你的本地工作臺，新增HelloWorld的web部件，你會看到返回的模擬資料，如下圖：

接下來訪問SharePoint承載的工作臺，效果如下圖：

現在你可以暫時停止gulp serve的執行了，切換到命令列，用Ctrl+C來中斷gulp task。

下一步

恭喜你成功地在你的web部件中連線了SharePoint的資料。在下一講我們將繼續深入講解，如何將web部件部署到一個傳統的SharePoint服務端頁面。

相關文章