SharePoint Framework 把你的客户端web部件连接到SharePoint

博客地址：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服务端页面。