构建你的第一个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环境中。