SharePoint Framework系列(七)-构建第一个webpart(连接到SharePoint)

连接你的web part到SharePoint去访问SharePoint中的功能和数据，并且为终端用户提供更多的体验。本文继续上篇文章，进行讲解。

运行Gulp Serve

确认你上篇文章中的gulp serve命令还在运行，如果没有运行，请使用命令行切换到hello-world工程目录中，然后运行如命令：

gulp serve

访问Page Context

当 workbench在本地运行的时候，你没有SharePoint页面的上下文，但是你还是可以通过其他的方式测试你的web part。例如：你可以在没有SharePoint环境中先集中开发web part的界面，然后使用mock数据的方式模拟SharePoint数据。

但是当workbench在本地运行的时候，你还是可以访问pageContext的几个关键的属性，例如：

• Web title
• Web absolute URL
• Web server-relative URL
• User login name

你可以使用如下code获得pageContext:

this.context.pageContext

切换到Visual Studio code(或者你喜欢的IDE)，然后打开src\webparts\helloWorld\HelloWorldWebPart.ts。把render方法中替换成如下的code：

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代码块中输出变量值的时候使用的，一个额外的p用于显示this.context.pageContext.web.title，因为你的web part是在本地的环境中运行的，所以title的值是Local WorkBench。

保存文件，运行gulp serve的命令窗口会自动检测是否有保存操作并且执行如下命令：

• 自动打包合并更改的code
• 刷新你本地的workbench页面(因为web part 代码需要重新加载)

在浏览器中访问workbench.html，如果你的窗口已经关闭，那个URL是https://localhost:4321/temp/workbench.html，你将会看到如下的web part样式：

进入SharePoint中的workbench.aspx页面，全路径应该是：https://your-sharepoint-site-url/Shared%20Documents/workbench.aspx.

注意：如果你没有安装SPFx 开发者证书workbench会提示当前不运行加载本地的JavaScript，执行gulp trust-dev-cert命令可以安装开发者证书。

在SharePoint中的workbench中你可以看到如下界面，此时说明page context在web part中已经是可用的。

定义list的模型

要想显示 SharePoint中的数据，你需要先定义一个数据结构，如果要加载站点中的列表，你需要如下两个model，在Visual Studio Code中打开src\webparts\helloWorld\HelloWorldWebPart.ts文件，在HelloWorldWebPart类上面 定义如下两个接口

export interface ISPLists {
    value: ISPList[];
}

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

ISPList用于存储SharePoint中的list信息。

从mock store中加载list信息

要想在本地的workbech中进行测试 ，你需要一个mock store用于返回mock数据。在scr\webparts\helloWorld文件夹中创建一个叫做MockHttpClient.ts的文件，然后把如下code复制到这个文件中

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);
        });
    }
}

code介绍：

• 因为在HelloWorldWebPart.ts文件中定义了很多个exports model，所以在Import的时候需要使用{}，在上面的例子中只有ISPList model是需要引入的。
• 在Import的时候，不需要指定文件的扩展名，在本例中是HelloWorldWebPart。
• 设置MockHttpClient是default model。
• 定义了ISPList数组，并用于返回。

保存文件，现在你可以再HelloWorldWebPart文件中使用MockHttpClient类了，但是你首先需要引入MockHttpClient这个model。打开HelloWorldWebPart.ts文件，复制如下的code到 import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';下面。

import MockHttpClient from './MockHttpClient';

在HelloWorldWebPart中添加如下私有方法，这个方法是用于MockList数据使用的

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站点中加载list信息

下一步你需要从当前sharepoint站点中加载list信息，你需要使用SharePoint REST API从站点中加载数据，REST API URL是https://yourtenantprefix.sharepoint.com/_api/web/lists.

在HelloWorldWebPart类中添加如下方法：

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();
        });
}

上面的code使用了一个在SharePoint client-side 平台中的工具类httpClient去执行的SharePoint REST API，它使用了ISPLists model并且读取SharePoint站点中的非hidden list.。保存文件。

切换到运行gulp serve命令的窗口，检查是否存在错误信息，gulp会在命令行窗口报出错误信息，如果有错误你需要进行相应的处理

添加新的样式

SharePoint Framework使用 Sass作为CSS的预处理器，明确的使用了和普通CSS语法有区别的SCSS的语法，Sass扩展了CSS的语法，可以让你使用新的功能（例如：变量，嵌套规则等等）来开发你的web part样式。SharePoint Framework已经包含了SCSS的编译器，它可以把Sass文件转换成普通的CSS文件。要添加新的样式，请打开HelloWorld.module.scss文件，这个文件是用于定义你的样式的，默认情况下样式 是定义在你的web part范围的，你可以看到你的样式都是定义在.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会 自动rebuild，它会在HelloWorld.module.scss.ts文件中自动生成对应的标签，一旦编译成typescript，你可以在你的web part导入并且引用这些样式。

你可以看render方法中如何使用样式的：

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

render list信息的方法

打开HelloWorldWebPart类。

SharePoint Framework提供了非常灵活的测试web part的方法，你可以在本地进行测试也可以在SharePoint站点中进行测试，SPFx使用EnvironmentType module帮助你了解当前运行的是什么环境，要使用这个module，你需要先从@microsoft/sp-client-base中引入EnvironmentType，在代码中添加 如下code:

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

添加如下的私有方法去调用各自的方法去获取list数据：

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);
        });
    }
}

以上code的描述

• this.context.environment.type属性可以帮助你判断是本地环境还是SharePoint环境
• 你workbench寄宿在哪个环境会决定你调用哪个方法

保存文件。

现在你需要在页面中render list数据，在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;
}

上面的方法中引用了新之前新添加的CSS样式，保存文件。

Retrieve list数据

切换到render方法，使用如下的代码替换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();

切换到你本地的workbench然后添加HelloWorld web part，你将会看到如下的效果

切换到你的SharePoint中的workbench，刷新页面然后添加HelloWorld web part你将会看大如下效果

至此已经开发完毕，你可以切换到命令行窗口，停止gulp serve，可以使用Control +C去停止gulp task。

注意：SharePoint Framework目前正处于Preview阶段，随时会进行一些更改。SharePoint Framework Client-side web parts在Office 365的生产环境中暂时不支持。