SharePoint Framework系列(六)-构建第一个web part

构建你的第一个SharePoint client-side web part

client-side web part是运行在SharePoint页面上下文中的client-side组件，Client-side web part可以部署到SharePoint Online，你可以使用比较流行的JavaScript工具和类库来开发他们。

Client-side webpart支持如下：

• 使用HTML和JavaScript开发
• 支持SharePoint Online和On-premises环境

创建新的Web Part工程

在Powershell中执行如下命令创建工程的文件夹

md helloworld-webpart

进入到对应的文件夹中

cd helloworld-webpart

使用Yoeman SharePoint generator创建新的web part工程

yo @microsoft/sharepoint

之后会出现如下 提示信息：

• 使用默认的helloworld-webpart作为你的工程名称，选择回车。
• 选择是否使用当前文件夹存储工程文件。

下一步会提示一些如下信息：

• 使用默认的HelloWord作为你的webpart名称，选择回车
• 使用默认的HelloWorld description作为你的web part描述，选择回车
• 选择默认的No javascript web framework。

此时，Yoeman会安装必要的依赖文件，并且创建HelloWord web part需要的文件，这个过程大概需要几分钟。当一切创建完成，你会看到如下的提示成功的信息：

如果过程中遇到了什么问题，请见 已知问题。

使用你喜欢的代码编辑器

因为SharePoint Client-side 工程是基于HTML和TypeScript的，所以你可以使用任何你喜欢的代码编辑器或者支持client-side开发的IDE来构建你的文本web part，例如：

• Visual Studio Code
• Sublime
• Atom
• Webstorm

注意：本文将使用Visual Studio Code作为后续的列子讲解，你可以使用任何你喜欢的文本编辑器。

预览你的web part

为了预览你的web part，你需要在本地打包和运行web服务来显示web part。client-side toolchain默认是使用的HTTPS作为协议的，但是因为默认的证书没有在你的开发环境中进行配置，所以浏览器会报出证书的错误。SPFx提供了一个开发者证书用于开发webpart。

为了安装证书SPFx开发需要的证书，切换到你的命令行窗口，请确保你还在helloworld-webpart文件夹中，然后执行如下命令：

gulp trust-dev-cert

这样就安装完了证书，之后我们在命令行中输入如下命令就可以预览web part了

gulp serve

这个命令会执行一系列的gulp的任务去创建一个本地的，Node-Based的HTTPS web server，这个web server的访问地址是https://localhost:4321，并且在本地的开发环境中加载你的默认的浏览器预览你的web part。

SharePoint client-side开发工具使用 gulp作为任务执行器去去处理BUILD任务，例如：

• 合并压缩JavaScript和CSS文件。
• 在每次打包前运行tool调用捆绑和压缩的任务。
• 编译LESS和SASS成CSS。
• 编译TypeScript文件成JavaScript。

如果你对gulp很陌生，请访问 Using Gulp网站，这个网站描述了如何适应glup和Visual Studio联合起来build asp.net 5的工程。

Visual Studio Code默认已经支持了gulp和其它的task runner。在windows中使用Ctrl+Shift+B，在Mac中使用Cmd+Shift+B可以进行debug和预览你的web part。

SharePoint Workbench

SharePoint workbench是一个开发人员设计界面，他可以让你在不需要部署到SharePoint环境的时候，快速的测试和预览你的web part。SharePoint workbench包含了可以让你在测试环境中添加，删除和测试 web part的client-side 页面和client-side canvas。

如果想要添加HelloWord webpart，选择add按钮。add 按钮会打开一个工具箱，这个工具箱包含HelloWorld web part和其它开发开发环境中可用的web part。

选择HelloWorld web part然后添加到workbench中

恭喜你，你已经成功添加了你的第一个client-side web part到client-side 页面中了。

现在你可以选择左侧的铅笔图标打开Web part属性面板

属性面板是你定义自定义web part属性的地方，属性面板是client-side驱动的。

修改你的web part Description，你可以看到web part上面的文字会自动变化。

属性面板的一个新增的功能就是可以配置属性的更新方式，这个值可以设置成reactive和non-reactive，默认情况下是reactive，当你修改属性的时候你可以直接看到变化，并且这些修改会立即被保存。

Web Part工程的结构

你可以使用Visual Studio Code查看web part工程的结构

• 在命令行中进入src\webparts\helloWorld。
• 键入如下命令就会自动调用Visual Studio Code打开这个工程的code。

code .

如果你得到错误，你可能需要 install the code command in PATH

TypeScript是编写client-side web parts的首选语言，TypeScript是一些了JavaScript的超级，他可以编译成JavaScript。SharePoint client-side 开发工具是使用TypeScript的class，modules以及接口来帮助开发者构建client-side web part的。

以下是工程中几个比较重要的文件

Web part class

HelloWorldWebPart.ts定义了web part的很多属性，HelloWorldWebPart继承自BaseClientSideWebPart,任何client-side web part都应该继承自该类。

public constructor(context: IWebPartContext) {
    super(context);
}

BaseClientSideWebPart 实现了client-side web part要求的最小功能，这个类提供了多个参数去验证和访问只读的属性(例如：displayMode)，web part上下文，web part的InstanceId以及web part的HTML DOM 结构等等。

注意：这个类支持传入一个IHelloWordWebPartProps的，这是一个接口并且定义在一个独立的文件中。

export interface IHelloWorldWebPartProps {
    description: string;
}

这个接口用于定义web part的自定义属性，这部分内同会在下面的 属性面板章节中介绍。

Web part render方法

在render方法中用于生成web part的DOM 元素是可以使用的，这个方法主要用于生成web part内部的html，在HelloWord web part，DOM结构设置成了DIV。

public render(): void {
  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>
            <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>`;
}

这个方法非常灵活，以至于可以使用任何JavaScript的framework去创建数据，并且加载到DOM中。

配置web part的属性面板

属性面板定义在HelloWorldWebPart中的，propertyPaneSettings属性是你定义property pane的地方，当属性定义完成之后，你可以在的webpart中使用this.properties.<property-value>的方式访问，例如：

<p class="ms-font-l ms-fontColor-white">${this.properties.description}</p>

可以访问 Integrating property pane with a  web part 文章了解，如何配置属性面板和属性面板中的属性类型。

下面让我们添加几个额外的属性-一个checkbox,dropdown和toggle到属性面板中，我们首先需要从framework中导入各自的属性类型，返回到文件的最上面，在import from @microsoft/sp-webpart-base中添加如下的属性：

PropertyPaneCheckbox,
PropertyPaneDropdown,
PropertyPaneToggle

添加后的内容如下：

import {
  BaseClientSideWebPart,
  IPropertyPaneSettings,
  IWebPartContext,
  PropertyPaneTextField,
  PropertyPaneCheckbox,
  PropertyPaneDropdown,
  PropertyPaneToggle
} from '@microsoft/sp-webpart-base';

保存文件，下一步更新webpart的属性使其包含新的属性，主要是映射控件和类型，打开IHelloWorldWebPartProps.ts替换成如下code：

export interface IHelloWorldWebPartProps {
    description: string;
    test: string;
    test1: boolean;
    test2: string;
    test3: boolean;
}

保存文件，切换回HelloWorldWebPart.ts文件，替换propertyPaneSettings方法为如下的code，这里在属性面板中添加了新的属性，并且映射这些属性到指定的控件中。

protected get propertyPaneSettings(): IPropertyPaneSettings{
  return {
    pages: [
      {
        header: {
          description: strings.PropertyPaneDescription
        },
        groups: [
          {
            groupName: strings.BasicGroupName,
            groupFields: [
            PropertyPaneTextField('description', {
              label: 'Description'
            }),
            PropertyPaneTextField('test', {
              label: 'Multi-line Text Field',
              multiline: true
            }),
            PropertyPaneCheckbox('test1', {
              text: 'Checkbox'
            }),
            PropertyPaneDropdown('test2', {
              label: 'Dropdown',
              options: [
                { key: '1', text: 'One' },
                { key: '2', text: 'Two' },
                { key: '3', text: 'Three' },
                { key: '4', text: 'Four' }
              ]}),
            PropertyPaneToggle('test3', {
              label: 'Toggle',
              onText: 'On',
              offText: 'Off'
            })
          ]
          }
        ]
      }
    ]
  };
}

当你添加完这些属性之后，你可以通过和访问description属性一样的方式访问其他属性，例如：

<p class="ms-font-l ms-fontColor-white">${this.properties.test2}</p>

如果想要设置属性的默认值，你需要更改web part的mainfest文件的properties中的值，打开HelloWorldWebPart.mainfest.json文件并且修改如下属性：

"properties": {
  "description": "HelloWorld",
  "test": "Multi-line text field",
  "test1": true,
  "test2": "2",
  "test3": true
}

这样属性面板中的属性就会显示上面设置的默认值。

web part  mainfest

HelloWorldWebPart.mainfest.json文件定义了web part的属性，例如：版本，id，显示名，图标，描述。每一个webpart都应该包含这个mainfest文件

{
  "$schema": "../../../node_modules/@microsoft/sp-module-interfaces/lib/manifestSchemas/jsonSchemas/clientSideComponentManifestSchema.json",
  "id": "2f1ef3e2-5f37-4da8-b1ff-52c468a28ae2",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,
  "preconfiguredEntries": [
    {
      "groupId": "2f1ef3e2-5f37-4da8-b1ff-52c468a28ae2",
      "group": {
        "default": "Under Development"
      },
      "title": {
        "default": "HelloWorld"
      },
      "description": {
        "default": "HelloWorld description"
      },
      "officeFabricIconFontName": "Page",
      "properties": {
        "description": "HelloWorld",
        "test": "Multi-line text field",
        "test1": true,
        "test2": "2",
        "test3": true
      }
    }
  ]
}

在sharepoint中预览web part

SharePoint workbench是以sharepoint 为宿主，用于在开发过程中预览和测试你的webpart的，关键的优势就是你的webpart现在是运行在sharepoint上下文的，你可以和SharePoint数据进行交互。访问如下URL：'https://your-sharepoint-site/Shared%20Documents/workbench.aspx'

注意： 如果你没有安装SPFx 开发证书，workbench会提示当前设置不允许从本地加载script，执行gulp trust-dev-cert 命令就会安装对应证书。

注意：现在SharePoint Workbench已经包含了Office 365的Suite Navigation Bar。

在画板上点击add按钮弹出工具箱，工具箱中会显示你创建的webpart，添加HelloWorldWebPart到页面中，你会看到如下效果：

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

因为你还处于开发阶段，所以暂时没有必要打包和部署到SharePoint环境中。