生成首个 SharePoint 客户端 Web 部件(Hello World 第 1 部分)Build your first SharePoint client-side web part (Hello World part 1)

客户端 Web 部件是运行在 SharePoint 页面的上下文中的客户端组件。可以将客户端 Web 部件部署到 SharePoint Online,还可以使用现代 JavaScript 工具和库生成它们。Client-side web parts are client-side components that run inside the context of a SharePoint page. Client-side web parts can be deployed to SharePoint Online, and you can also use modern JavaScript tools and libraries to build them.

客户端 Web 部件支持:Client-side web parts support:

  • 使用 HTML 和 JavaScript 生成。Building with HTML and JavaScript.
  • SharePoint Online 和本地环境。Both SharePoint Online and on-premises environments.


请务必先设置开发环境,再执行本文中的步骤。Before following the steps in this article, be sure to Set up your development environment.

也可以观看 SharePoint PnP YouTube 频道上的这段视频,按照下面这些步骤操作:You can also follow these steps by watching this video on the SharePoint PnP YouTube Channel:

新建 Web 部件项目Create a new web part project

新建 Web 部件项目的具体步骤To create a new web part project

  1. 在常用位置上新建项目目录。Create a new project directory in your favorite location.

    md helloworld-webpart
  2. 转到项目目录:Go to the project directory.

    cd helloworld-webpart
  3. 通过运行 Yeoman SharePoint 生成器创建新的 HelloWorld Web 部件:Create a new HelloWorld web part by running the Yeoman SharePoint Generator.

yo @microsoft/sharepoint
  1. 当出现提示时:When prompted:

    • 接受默认的“helloworld-webpart”**** 作为解决方案名称,然后按 Enter。Accept the default helloworld-webpart as your solution name, and then select Enter.
    • 选择“仅限 SharePoint Online (最新)”****,然后按 Enter。Select SharePoint Online only (latest), and select Enter.
    • 选择“使用当前文件夹”**** 作为文件放置位置。Select Use the current folder for where to place the files.
    • 选择“N”**** 以不允许将解决方案立即部署到所有网站。Select N to not allow the solution to be deployed to all sites immediately.
    • 在解决方案是否包含独有权限的问题上选择“N”****。Select N on the question if solution contains unique permissions.
    • 选择“Web 部件”**** 作为要创建的客户端组件类型。Select WebPart as the client-side component type to be created.
  2. 接下来的一组提示将要求提供 Web 部件的具体信息:The next set of prompts ask for specific information about your web part:

    • 接受默认的“HelloWorld”**** 作为 Web 部件名称,然后按 Enter。Accept the default HelloWorld as your web part name, and then select Enter.
    • 接受默认的“HelloWorld 说明”**** 作为 Web 部件说明,然后按 Enter。Accept the default HelloWorld description as your web part description, and then select Enter.
    • 接受默认的“无 JavaScript Web 框架”**** 作为要使用的框架,然后按 Enter。Accept the default No javascript web framework as the framework you would like to use, and then select Enter.

    Yeoman SharePoint 生成器提示创建 Web 部件客户端解决方案

此时,Yeoman 安装必需的依赖项,并为解决方案文件和“HelloWorld”**** Web 部件搭建基架。At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the HelloWorld web part. 这可能需要几分钟的时间才能完成。This might take a few minutes.

基架搭建完成后,应该可以看到指明已成功搭建基架的以下消息。When the scaffold is complete, you should see the following message indicating a successful scaffold.

已成功搭建 SharePoint 客户端解决方案的基架

有关任何错误故障排除的信息,请参阅已知问题For information about troubleshooting any errors, see Known issues.

使用常用的代码编辑器Using your favorite Code Editor

由于 SharePoint 客户端解决方案基于 HTML/TypeScript,因此可使用任何支持客户端开发的代码编辑器来生成 Web 部件,例如:Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your web part, such as:

SharePoint 框架文档中的步骤和示例使用的是 Visual Studio Code。SharePoint Framework documentation uses Visual Studio Code in the steps and examples. Visual Studio Code 是 Microsoft 提供的轻型源代码编辑器,功能十分强大,可以在桌面上运行,适用于 Windows、Mac 和 Linux。Visual Studio Code is a lightweight but powerful source code editor from Microsoft that runs on your desktop and is available for Windows, Mac, and Linux. 其中内置了对 JavaScript、TypeScript 和 Node.js 的支持,且生态系统中包含多种适用于其他语言(如 C++、C#、Python 和 PHP)和运行时的扩展。It comes with built-in support for JavaScript, TypeScript, and Node.js, and has a rich ecosystem of extensions for other languages (such as C++, C#, Python, PHP) and runtimes.

预览 Web 部件Preview the web part

若要预览 Web 部件,请在本地 Web 服务器上生成并运行它。To preview your web part, build and run it on a local web server. 默认情况下,客户端工具链使用 HTTPS 终结点。The client-side toolchain uses HTTPS endpoint by default. 可以在位于 config 文件夹中的 serve.json 文件中配置此设置,但建议使用默认值。This setting can be configured in the serve.json file located in the config folder, but we do recommend using the default values.

切换到控制台,并确保仍位于 helloworld-webpart 目录中,然后输入以下命令:Switch to your console, ensure that you are still in the helloworld-webpart directory, and then enter the following command:


只能在开发环境中安装一次开发人员证书,因此,如果已在环境中执行此操作,则可以跳过该步骤。Developer certificate has to be installed ONLY once in your development environment, so you can skip this step, if you have already executed that in your environment.

gulp trust-dev-cert

至此,已安装开发人员证书。在控制台中输入以下命令,以生成并预览 Web 部件:Now that we have installed the developer certificate, enter the following command in the console to build and preview your web part:

gulp serve

此命令执行一系列 gulp 任务,以在 localhost:4321localhost:5432 上创建基于节点的本地 HTTPS 服务器。This command executes a series of gulp tasks to create a local, node-based HTTPS server on localhost:4321 and localhost:5432. 然后,将在默认浏览器中启动工作台,以便从本地开发环境中预览 Web 部件。The workbench is then launched in your default browser to preview web parts from your local dev environment.


如果在浏览器中看到证书有问题,请参阅设置开发环境一文中有关安装开发人员证书的详细信息。If you are seeing issues with the certificate in browser, please see details on installing a developer certificate from the Set up your development environment article. 如果仍有问题,请通过使用 resmon.ex(“网络”选项卡)并查看侦听端口来检查没有其他程序正在侦听端口号。If you are still seeing issues, please check nothing else is listening on the port numbers, by using resmon.exe, the network tab and looking at Listening Ports.

对 Web 部件项目运行 gulp serve

SharePoint 客户端开发工具使用 gulp 作为任务运行程序,以处理如下生成过程任务:SharePoint client-side development tools use gulp as the task runner to handle build process tasks such as:

  • 捆绑和缩小 JavaScript 与 CSS 文件。Bundling and minifying JavaScript and CSS files.
  • 运行工具,以在每次生成前调用捆绑和缩小任务。Running tools to call the bundling and minification tasks before each build.
  • 将 SASS 文件编译为 CSS。Compiling SASS files to CSS.
  • 将 TypeScript 文件编译为 JavaScript。Compiling TypeScript files to JavaScript.

Visual Studio Code 内置对 gulp 和其他任务运行程序的支持。Visual Studio Code provides built-in support for gulp and other task runners. 可以在 Windows 中按 Ctrl+Shift+B 或在 Mac 上按 Cmd+Shift+B,调试并预览 Web 部件。Select Ctrl+Shift+B on Windows or Cmd+Shift+B on Mac to debug and preview your web part.

SharePoint Workbench 是开发人员设计图面,可方便用户快速预览和测试 Web 部件,而无需在 SharePoint 中部署它们。SharePoint Workbench is a developer design surface that enables you to quickly preview and test web parts without deploying them in SharePoint. SharePoint Workbench 包括客户端页面和客户端画布,用户可以在其中添加、删除和测试仍处于开发阶段的 Web 部件。SharePoint Workbench includes the client-side page and the client-side canvas in which you can add, delete, and test your web parts in development.

本地运行的 SharePoint Workbench

使用 SharePoint Workbench 预览并测试 Web 部件的具体步骤To use SharePoint Workbench to preview and test your web part

  1. 要添加 HelloWorld Web 部件,请选择“添加”**** 图标(将鼠标悬停在某个部分上时会出现此图标,如上图所示)。To add the HelloWorld web part, select the add icon (this icon appears when you mouse hovers over a section as shown in the previous image). 这会打开工具箱,其中显示可供添加的 Web 部件列表。This opens the toolbox where you can see a list of web parts available for you to add. 此列表包括“HelloWorld”**** Web 部件,以及本地开发环境中的其他 Web 部件。The list includes the HelloWorld web part as well other web parts available locally in your development environment.

    localhost 中的 SharePoint Workbench 工具箱

  2. 选择“HelloWorld”****,将 Web 部件添加到页面:Select HelloWorld to add the web part to the page.

    SharePoint Workbench 中的 HelloWorld Web 部件

    恭喜!已成功将首个客户端 Web 部件添加到了客户端页面。Congratulations! You have just added your first client-side web part to a client-side page.

  3. 选择 Web 部件最左侧的铅笔图标,调出 Web 部件属性窗格。Select the pencil icon on the far left of the web part to reveal the web part property pane.

    HelloWorld Web 部件属性窗格

    你可以在属性窗格中定义属性,以便自定义 Web 部件。属性窗格由客户端驱动,并在 SharePoint 中提供一致的设计。The property pane is where you can define properties to customize your web part. The property pane is client-side driven and provides a consistent design across SharePoint.

  4. Description 文本框中的文本修改为 Client-side web parts are awesome!Modify the text in the Description text box to Client-side web parts are awesome!

    请注意,Web 部件中的文本也会随着键入更改。Notice how the text in the web part also changes as you type.

属性窗格新引入的功能之一是配置它的更新行为,可设置为反应模式或非反应模式。One of the new capabilities available to the property pane is to configure its update behavior, which can be set to reactive or non-reactive. 默认情况下,更新行为是反应模式,可方便用户在编辑属性的同时查看所做的更改。By default, the update behavior is reactive and enables you to see the changes as you edit the properties. 如果行为是反应模式,所做的更改会立即保存。The changes are saved instantly when the behavior is reactive.

Web 部件项目结构Web part project structure

使用 Visual Studio Code 浏览 Web 部件项目结构的具体步骤To use Visual Studio Code to explore the web part project structure

  1. 在控制台中,按 Ctrl+C 中断处理。In the console, break the processing by selecting Ctrl+C.

  2. 输入以下命令,在 Visual Studio Code(或常用编辑器)中打开 Web 部件项目:Enter the following command to open the web part project in Visual Studio Code (or use your favorite editor):

    code .

    HelloWorld 项目结构

如果出现错误,则需要安装 PATH 中的代码命令If you get an error, you might need to install the code command in PATH.

TypeScript 是生成 SharePoint 客户端 Web 部件的主要语言。TypeScript 是键入的 JavaScript 超集,它编译为纯 JavaScript。SharePoint 客户端开发工具使用 TypeScript 类、模块和接口生成,可帮助开发者生成可靠的客户端 Web 部件。TypeScript is the primary language for building SharePoint client-side web parts. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. SharePoint client-side development tools are built using TypeScript classes, modules, and interfaces to help developers build robust client-side web parts.

以下是项目中的一些关键文件。The following are some key files in the project.

Web 部件类Web part class

“src\webparts\helloworld”**** 文件夹中的“HelloWorldWebPart.ts”**** 定义了 Web 部件的主入口点。HelloWorldWebPart.ts in the src\webparts\helloworld folder defines the main entry point for the web part. Web 部件类“HelloWorldWebPart”**** 扩展了“BaseClientSideWebPart”****。The web part class HelloWorldWebPart extends the BaseClientSideWebPart. 所有客户端 Web 部件都应扩展“BaseClientSideWebPart”**** 类,将它定义为有效 Web 部件。Any client-side web part should extend the BaseClientSideWebPart class to be defined as a valid web part.

“BaseClientSideWebPart”**** 实现生成 Web 部件至少所需的功能。BaseClientSideWebPart implements the minimal functionality that is required to build a web part. 此类还提供了许多参数,用于验证并访问只读属性,如 displayMode、Web 部件 properties、Web 部件 context、Web 部件 instanceId、Web 部件 domElement等。This class also provides many parameters to validate and access read-only properties such as displayMode, web part properties, web part context, web part instanceId, the web part domElement, and much more.

请注意,Web 部件类的定义为接受“IHelloWorldWebPartProps”**** 属性类型。Notice that the web part class is defined to accept a property type IHelloWorldWebPartProps.

此属性类型在“HelloWorldWebPart.ts”**** 文件中“HelloWorldWebPart”**** 类前面被定义为接口。The property type is defined as an interface before the HelloWorldWebPart class in the HelloWorldWebPart.ts file.

export interface IHelloWorldWebPartProps {
    description: string;

此属性定义用于为 Web 部件定义自定义属性类型,稍后将在属性窗格部分进行介绍。This property definition is used to define custom property types for your web part, which is described in the property pane section later.

Web 部件呈现方法Web part render method

呈现 Web 部件的 DOM 元素位于 render 方法中。此方法用于在该 DOM 元素内呈现 Web 部件。在 HelloWorld Web 部件中,DOM 元素设置为 DIV。方法参数包括显示模式(读取或编辑)和配置的 Web 部件属性(如果存在):The DOM element where the web part should be rendered is available in the render method. This method is used to render the web part inside that DOM element. In the HelloWorld web part, the DOM element is set to a DIV. The method parameters include the display mode (either Read or Edit) and the configured web part properties if any:

public render(): void {
  this.domElement.innerHTML = `
    <div class="${ styles.helloWorld }">
      <div class="${ styles.container }">
        <div class="${ styles.row }">
          <div class="${ styles.column }">
            <span class="${ styles.title }">Welcome to SharePoint!</span>
            <p class="${ styles.subTitle }">Customize SharePoint experiences using web parts.</p>
            <p class="${ styles.description }">${escape(this.properties.description)}</p>
            <a href="https://aka.ms/spfx" class="${ styles.button }">
              <span class="${ styles.label }">Learn more</span>

这种模型非常灵活,以便你可以将 Web 部件内置到任意 JavaScript 框架中,并将其加载到 DOM 元素中。This model is flexible enough so that web parts can be built in any JavaScript framework and loaded into the DOM element.

配置 Web 部件属性窗格Configure the Web part property pane

属性窗格在 HelloWorldWebPart 类中进行定义。The property pane is defined in the HelloWorldWebPart class. 需要在 getPropertyPaneConfiguration 属性中定义属性窗格。The getPropertyPaneConfiguration property is where you need to define the property pane.

定义属性后,可以使用 this.properties.<property-value> 在 Web 部件中访问它们,如 render 方法中所示:When the properties are defined, you can access them in your web part by using this.properties.<property-value>, as shown in the render method:

<p class="${styles.description}">${escape(this.properties.description)}</p>

请注意,为了确保字符串有效,正在对属性值执行 HTML 转义。Notice that we are performing an HTML escape on the property's value to ensure a valid string. 若要详细了解如何使用属性窗格和属性窗格字段类型,请参阅让 SharePoint 客户端 Web 部件成为可配置部件To learn more about how to work with the property pane and property pane field types, see Make your SharePoint client-side web part configurable.

现在,向属性窗格添加其他一些属性:复选框、下拉列表和开关。Let's now add a few more properties to the property pane: a checkbox, a drop-down list, and a toggle. 首先,从框架中导入各自的属性窗格字段。We first start by importing the respective property pane fields from the framework.

  1. 滚动到文件顶部,并向 导入部分添加 @microsoft/sp-property-pane 中的以下内容:Scroll to the top of the file and add the following to the import section from @microsoft/sp-property-pane:


    完整的导入部分如下所示:The complete import section looks like the following:

    import {
    } from '@microsoft/sp-property-pane';
  2. 将 Web 部件属性更新为包含新属性。Update the web part properties to include the new properties. 这会将字段映射到类型化对象。This maps the fields to typed objects.

  3. 将“IHelloWorldWebPartProps”**** 接口替换为以下代码。Replace the IHelloWorldWebPartProps interface with the following code.

    export interface IHelloWorldWebPartProps {
        description: string;
        test: string;
        test1: boolean;
        test2: string;
        test3: boolean;
  4. 保存此文件。Save the file.

  5. 将“getPropertyPaneConfiguration”**** 方法替换为以下代码,用于添加新属性窗格字段,并将这些字段映射到各自的类型化对象。Replace the getPropertyPaneConfiguration method with the following code, which adds the new property pane fields and maps them to their respective typed objects.

    protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
      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'
  6. 向 Web 部件 properties 添加属性后,你现在可以访问这些属性,就像之前访问 description 属性一样:After you add your properties to the web part properties, you can now access the properties in the same way you accessed the description property earlier:

    <p class="${ styles.description }">${escape(this.properties.test)}</p>

    若要设置属性默认值,必须更新 Web 部件清单的“properties”**** 属性包:To set the default value for the properties, you need to update the web part manifest's properties property bag.

  7. 打开“HelloWorldWebPart.manifest.json”,并将“properties”修改为:Open HelloWorldWebPart.manifest.json and modify the properties to:

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

此时,Web 部件属性窗格包含这些属性默认值。The web part property pane now has these default values for those properties.

Web 部件清单Web part manifest

HelloWorldWebPart.manifest.json 文件定义了 Web 部件元数据,如版本、ID、显示名称、图标和说明。The HelloWorldWebPart.manifest.json file defines the web part metadata such as version, id, display name, icon, and description. 每个 Web 部件都必须包含此清单。Every web part must contain this manifest.

  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "fbcf2c6a-7df9-414c-b3f5-37cab6bb1280",
  "alias": "HelloWorldWebPart",
  "componentType": "WebPart",

  // The "*" signifies that the version should be taken from the package.json
  "version": "*",
  "manifestVersion": 2,

  // If true, the component can only be installed on sites where Custom Script is allowed.
  // Components that allow authors to embed arbitrary script code should set this to true.
  // https://support.office.com/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
  "requiresCustomScript": false,
  "supportedHosts": ["SharePointWebPart"],

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
    "group": { "default": "Other" },
    "title": { "default": "HelloWorld" },
    "description": { "default": "HelloWorld description" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "description": "HelloWorld",
      "test": "Multi-line text field",
      "test1": true,
      "test2": "2",
      "test3": true

至此,已引入新属性。请运行以下命令,确保再次通过本地开发环境托管 Web 部件。Now that we have introduced new properties, ensure that you are again hosting the web part from the local development environment by executing the following command. 这还会确保正确应用之前的更改。This also ensures that the previous changes were correctly applied.

gulp serve

在 SharePoint 中预览 Web 部件Preview the web part in SharePoint

SharePoint Workbench 还托管在 SharePoint 中,以预览和测试仍处于开发阶段的本地 Web 部件。SharePoint Workbench is also hosted in SharePoint to preview and test your local web parts in development. 主要优势在于,不仅可以在 SharePoint 上下文中运行,还可以与 SharePoint 数据进行交互。The key advantage is that now you are running in SharePoint context and you are able to interact with SharePoint data.

  1. 转到以下 URL:https://your-sharepoint-tenant.sharepoint.com/_layouts/workbench.aspxGo to the following URL: https://your-sharepoint-tenant.sharepoint.com/_layouts/workbench.aspx


    如果没有安装 SPFx 开发人员证书,Workbench 会发出通知,指明它被配置为不通过 localhost 加载脚本。If you do not have the SPFx developer certificate installed, Workbench notifies you that it is configured not to load scripts from localhost. 在控制台窗口中停止当前正在运行的进程,在项目目录控制台中运行 gulp trust-dev-cert 命令,以便在再次运行 gulp serve 命令之前安装开发人员证书。Stop the currently running process in the console window, and execute the gulp trust-dev-cert command in your project directory console to install the developer certificate before running the gulp servecommand again. 有关安装开发人员证书的详细信息,请参阅设置开发环境一文。See details on installing a developer certificate from the Set up your development environment article.

    在 SharePoint Online 网站中运行的 SharePoint Workbench

  2. 请注意,SharePoint Workbench 现在有 Office 365 套件导航栏。Notice that the SharePoint Workbench now has the Office 365 Suite navigation bar.

  3. 选择画布上的“添加”**** 图标,调出工具箱。Select the add icon in the canvas to reveal the toolbox. 工具箱现在显示托管 SharePoint Workbench 与“HelloWorldWebPart”**** 的网站支持的 Web 部件。The toolbox now shows the web parts available on the site where the SharePoint Workbench is hosted along with your HelloWorldWebPart.

    在 SharePoint Online 网站中运行的 SharePoint Workbench 工具箱

  4. 从工具箱添加 HelloWorldAdd HelloWorld from the toolbox. 现在,你即将在托管于 SharePoint 的页面中运行 Web 部件!Now you're running your web part in a page hosted in SharePoint!

    在 SharePoint Online 网站中运行的 SharePoint Workbench,其中运行 HelloWorld Web 部件


Web 部件颜色取决于网站颜色。The color of the web part depends on the colors of the site. 默认情况下,Web 部件动态引用托管 Web 部件的网站中使用的 Office UI Fabric Core 样式,继承网站的核心颜色。By default, web parts inherit the core colors from the site by dynamically referencing Office UI Fabric Core styles used in the site where the web part is hosted.

由于 Web 部件仍处于开发和测试阶段,因此无需将 Web 部件打包并部署到 SharePoint。Because you are still developing and testing your web part, there is no need to package and deploy your web part to SharePoint.

后续步骤Next steps

恭喜!已成功运行首个 Hello World Web 部件!Congratulations on getting your first Hello World web part running!

至此,Web 部件已在运行。在下一主题将 Web 部件连接到 SharePoint 中,可以继续生成 Hello World Web 部件。Now that your web part is running, you can continue building out your Hello World web part in the next topic, Connect your web part to SharePoint. 将使用相同的 HelloWorld Web 部件项目,并添加与 SharePoint 列表 REST API 进行交互的功能。You will use the same Hello World web part project and add the ability to interact with SharePoint List REST APIs. 请注意,gulp serve 命令仍在控制台窗口或 Visual Studio Code(如果使用它作为编辑器)中运行。Notice that the gulp serve command is still running in your console window (or in Visual Studio Code if you are using that as editor). 浏览下一篇文章时,可以继续让它运行。You can continue to let it run while you go to the next article.


如果发现本文档或 SharePoint Framework 有问题,请使用 sp-dev-docs 存储库上的问题列表或向本文添加注释,向 SharePoint 工程团队报告问题。If you find an issue in the documentation or in the SharePoint Framework, please report that to SharePoint engineering by using the issue list at the sp-dev-docs repository or by adding a comment to this article. 提前感谢读者提供反馈意见。Thanks for your input in advance.