2. 在SharePoint中创建第一个SPFx Web部件

# 1. 简介

## 1.1 SharePoint和SPFx简介

SharePoint是由微软开发的一款企业信息协作平台，旨在帮助组织建立内部门户网站、协作工作空间和文件存档等。

SPFx全称为SharePoint Framework，是一种专为SharePoint Online和SharePoint On-premises开发人员设计的模块化、可扩展且跨设备的Web部件开发框架。通过使用SPFx，开发人员可以使用现代Web开发工具和技术（如TypeScript、React和Node.js）来构建在SharePoint中运行的自定义Web部件。

## 1.2 SPFx Web部件的作用和优势

SPFx Web部件是一种能够在SharePoint页面中嵌入并展示自定义内容的组件。与传统的基于服务端代码的开发方式相比，SPFx Web部件具有以下优势：

- 灵活性：可以定制Web部件的外观和功能，以满足特定的业务需求。
- 可扩展性：可以通过使用不同的开发技术和工具，扩展Web部件的功能和性能。
- 跨平台支持：支持在不同设备和浏览器上运行，确保用户体验的一致性。
- 安全性：遵循SharePoint的安全策略和权限管理规则，保护敏感数据和信息的安全性。

在接下来的章节中，我们将详细介绍如何使用SPFx来创建和部署Web部件，并探索其强大的功能和潜力。

# 2. 准备工作

### 2.1 安装和配置Node.js

要开始使用SharePoint Framework (SPFx) 开发，首先需要安装 Node.js。Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境，能够让 JavaScript 代码在服务器端运行。您可以从 [Node.js 官网](https://nodejs.org/) 下载适用于您操作系统的安装程序，并按照指示进行安装。

安装完成后，您可以打开命令行工具（如终端或命令提示符）并输入以下命令来验证 Node.js 是否成功安装：

node -v
npm -v

如果成功显示对应的版本号，则表示 Node.js 安装成功。

### 2.2 安装开发工具和环境

在正式开始使用 SPFx 开发工具之前，确保您安装了最新版本的开发工具和环境，包括 Git、代码编辑器（如 Visual Studio Code 或者 Atom）等。

### 2.3 创建 SharePoint 开发环境

在继续之前，请确保您已拥有适用于 SharePoint 开发的开发人员订阅，并且对应的权限。如果您使用 SharePoint Online，则建议您创建一个开发者网站集，用于测试和部署您的自定义 Web 部件。

在下一章节中，我们将开始创建一个新的 SPFx 项目。

# 3. 创建SPFx项目

在本章中，我们将详细介绍如何使用 Yeoman 工具生成 SPFx 项目模板，并解析项目结构，最后展示如何运行和调试 SPFx 项目。

#### 3.1 使用Yeoman生成SPFx项目模板

要创建一个新的 SPFx 项目，我们首先需要安装 Yeoman 和 @microsoft/generator-sharepoint 软件包。打开命令行界面，执行以下命令：

npm install -g yo gulp @microsoft/generator-sharepoint

安装完毕后，运行以下命令来生成 SPFx 项目模板：

yo @microsoft/sharepoint

然后，按照提示进行选择和填写项目信息，包括项目名称、描述、项目类型等。最后，Yeoman 会自动创建一个基本的 SPFx 项目结构，并安装所需的依赖项。

#### 3.2 项目结构解析

生成的 SPFx 项目结构如下所示：

.
├── config/
├── src/
│   ├── webparts/
│   │   ├── HelloWorld/
│   │   │    ├── HelloWorld.ts
│   │   │    ├── HelloWorldWebPart.ts
│   │   │    ├── HelloWorldWebPart.manifest.json
│   │   │    ├── HelloWorld.module.scss
│   │   │    └── HelloWorld.module.scss.d.ts
│   │   └── HelloWorldWebPart.ts
│   └── index.ts
├── .gitignore
├── gulpfile.js
├── package.json
├── README.md
└── tsconfig.json

- `config/`：包含项目的配置文件，用于定义构建和打包的设置。
- `src/`：用于存放源代码的目录。
- `src/webparts/`：存放 Web 部件代码的目录。
- `src/webparts/HelloWorld/`：一个示例 Web 部件的目录，其中包含了 Web 部件的 TypeScript 逻辑、样式和清单文件等。
- `.gitignore`：Git 版本控制工具的忽略文件配置。
- `gulpfile.js`：Gulp 任务配置文件，定义了用于构建和打包的自定义任务。
- `package.json`：项目的依赖包配置文件。
- `README.md`：项目的说明文档。
- `tsconfig.json`：TypeScript 的配置文件，定义了编译选项和编译输出目标等。

#### 3.3 运行并调试SPFx项目

在命令行界面中进入项目根目录，运行以下命令来构建并打开本地调试环境：

gulp serve

此命令将自动构建项目，并启动本地调试服务器。当命令完成后，将自动打开一个浏览器窗口，显示本地调试环境的 SharePoint 页面。

在本地调试环境中，我们可以通过修改 Web 部件的代码和样式来实时预览效果。在命令行界面中保存文件后，本地调试服务器将自动重新编译并刷新页面，以展示最新的更改。

通过以上步骤，我们成功创建了一个 SPFx 项目，并运行了本地调试环境。在接下来的章节中，我们将进一步开发和定制 Web 部件的功能。

# 4. 编写Web部件

SharePoint Framework（SPFx）提供了丰富的Web部件开发功能，可以通过SPFx框架轻松创建定制化的Web部件来扩展SharePoint页面的功能和样式。本章将介绍如何编写SPFx Web部件，包括Web部件的基本结构、使用TypeScript编写Web部件逻辑以及自定义Web部件的外观和样式。

#### 4.1 Web部件的基本结构

SPFx Web部件的基本结构由三个主要文件组成：

- **Web部件逻辑文件**（例如 `MyWebPart.ts`）：负责定义Web部件的行为和交互逻辑。
- **Web部件样式文件**（例如 `MyWebPart.module.scss`）：负责定义Web部件的样式和外观。
- **Web部件配置文件**（例如 `MyWebPart.manifest.json`）：负责定义Web部件的属性和配置信息。

#### 4.2 使用TypeScript编写Web部件逻辑

下面是一个简单的SPFx Web部件的逻辑代码示例，该Web部件可以在SharePoint页面中显示一个问候语，并根据当前时间显示不同的问候内容：

import { Version } from '@microsoft/sp-core-library';
import {
  BaseClientSideWebPart,
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-webpart-base';
import { escape } from '@microsoft/sp-lodash-subset';

import styles from './MyWebPart.module.scss';
import * as strings from 'MyWebPartStrings';

export interface IMyWebPartProps {
  description: string;
}

export default class MyWebPart extends BaseClientSideWebPart<IMyWebPartProps> {
  public render(): void {
    const currentTime: Date = new Date();
    let greeting: string = 'Hello';
    if (currentTime.getHours() >= 12 && currentTime.getHours() < 18) {
      greeting = 'Good afternoon';
    } else if (currentTime.getHours() >= 18) {
      greeting = 'Good evening';
    }

    this.domElement.innerHTML = `
      <div class="${styles.myWebPart}">
        <div class="${styles.container}">
          <div class="${styles.row}">
            <div class="${styles.column}">
              <span class="${styles.title}">${escape(this.properties.description)}</span>
              <p class="${styles.subTitle}">${greeting}, SharePoint!</p>
            </div>
          </div>
        </div>
      </div>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneTextField('description', {
                  label: strings.DescriptionFieldLabel
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

上述代码演示了一个简单的SPFx Web部件，其中使用了TypeScript语言编写Web部件的逻辑。通过定义Web部件的属性接口 `IMyWebPartProps` 和 Web部件类 `MyWebPart`，并重写 `render` 方法和 `getPropertyPaneConfiguration` 方法，实现了Web部件的渲染和配置功能。

#### 4.3 自定义Web部件的外观和样式

除了编写Web部件的逻辑代码，SPFx还提供了一种方便的方式来定义Web部件的样式和外观。通过在Web部件样式文件（例如 `MyWebPart.module.scss`）中定义CSS样式，可以轻松地为Web部件添加自定义样式，实现更加个性化的展现效果。

.myWebPart {
  .container {
    max-width: 700px;
    margin: 0px auto;
    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.1);
    padding: 20px;
    display: flex;
    flex-direction: column;
    align-items: center;
    background-color: #f4f4f4;
    border-radius: 4px;
  }

  .title {
    font-size: 50px;
    color: #333333;
    margin-bottom: 20px;
  }

  .subTitle {
    font-size: 24px;
    color: #666666;
  }
}

上述代码示例定义了Web部件 `MyWebPart` 的样式，包括容器样式 `.container`、标题样式 `.title` 和副标题样式 `.subTitle`。通过在Web部件逻辑代码中引入样式文件，并添加相应的CSS类，即可实现Web部件的外观定制。

通过上述内容的学习，读者可以了解到如何使用TypeScript编写SPFx Web部件的逻辑和样式，以及如何定义Web部件的基本结构，希望可以帮助读者更好地掌握SPFx Web部件开发的相关知识。

# 5. 在SharePoint中部署Web部件

在之前的章节中，我们已经学习了如何创建并编写SPFx Web部件。接下来，将介绍如何将这些Web部件部署到SharePoint中，以供用户在SharePoint页面中使用。

#### 5.1 在本地测试环境中部署Web部件

在部署Web部件之前，我们首先需要在本地测试环境中运行和调试Web部件，以确保其功能正常。下面是一些部署Web部件到本地测试环境的步骤：

1. 在命令行中进入到SPFx项目的根目录。

2. 运行以下命令以在本地运行Web部件：

   gulp serve

这将启动本地开发服务器，并在浏览器中打开Web部件的预览页面。

3. 在预览页面中进行测试，确保Web部件的功能和样式正常。

#### 5.2 在SharePoint Online中部署Web部件

一旦我们在本地测试环境中确认Web部件运行正常，就可以将它部署到SharePoint Online中，以供实际使用。下面是在SharePoint Online中部署Web部件的步骤：

1. 在命令行中进入到SPFx项目的根目录。

2. 运行以下命令以打包Web部件：

   gulp bundle --ship
   gulp package-solution --ship

这将生成一个打包文件和一个解决方案包。

3. 登录到您的SharePoint Online租户，并打开要部署Web部件的目标网站。

4. 进入网站的“站点内容”页面，并上传解决方案包。

5. 在“站点内容”页面中，点击解决方案包，并选择“部署”选项。

6. 部署完成后，在SharePoint页面的编辑模式下，点击“编辑”按钮，在工具栏中选择“添加一个应用部件”。

7. 在应用部件面板中，找到并选择刚才部署的Web部件，点击“添加”按钮。

8. 确认Web部件已经成功添加到页面，并保存页面。

现在，您的Web部件已经成功部署到SharePoint Online中，并可以在页面中使用了。

#### 5.3 部署Web部件到SharePoint On-premises

除了在SharePoint Online中部署Web部件外，我们还可以将其部署到自己的SharePoint On-premises环境中。下面是部署Web部件到SharePoint On-premises的步骤：

1. 在命令行中进入到SPFx项目的根目录。

2. 运行以下命令以打包Web部件：

   gulp bundle --ship
   gulp package-solution --ship

这将生成一个打包文件和一个解决方案包。

3. 登录到您的SharePoint On-premises环境的中央管理页面，并上传解决方案包。

4. 在中央管理页面的解决方案库中，选择刚才上传的解决方案包，并点击“部署”按钮。

5. 部署完成后，转到要部署Web部件的目标网站。

6. 进入网站的“站点内容”页面，并点击“新建页面”按钮。

7. 在新建页面中，点击“添加Web部件”按钮，并在弹出的面板中选择“企业内容”类别。

8. 在企业内容面板中，找到并选择刚才部署的Web部件，点击“添加”按钮。

9. 确认Web部件已经成功添加到页面，并保存页面。

现在，您的Web部件已经成功部署到SharePoint On-premises中，并可以在页面中使用了。

通过以上步骤，我们可以将SPFx Web部件部署到不同环境中，以满足不同的部署需求。接下来，我们将学习如何进行测试和迭代，以完善和发布我们的Web部件。

# 6. 测试和迭代

在创建和部署SPFx Web部件之后，测试和迭代是至关重要的。本章将重点介绍如何进行测试，并根据测试结果进行迭代和发布更新。

#### 6.1 编写单元测试和集成测试

在开发过程中，我们需要编写单元测试和集成测试来确保Web部件的质量和稳定性。可以使用工具如Mocha、Chai和Sinon来进行JavaScript代码的单元测试。此外，对于Web部件与SharePoint交互的功能，可以使用PnP JS库来进行集成测试。

// 示例：使用Mocha和Chai编写单元测试
describe('Web部件逻辑', function() {
  it('应正确返回数据', function() {
    // 编写测试逻辑
    // assert.equal(actual, expected);
  });
});

// 示例：使用PnP JS进行集成测试
import { sp } from "@pnp/sp/presets/all";

describe('Web部件与SharePoint交互', function() {
  it('应正确获取列表数据', async function() {
    sp.web.lists.getByTitle("ListName").items.get().then((data) => {
      // 编写断言逻辑
      // assert.equal(data.length, expectedLength);
    });
  });
});

#### 6.2 完善Web部件功能

根据测试结果，我们可以发现并修复Web部件中的bug，并且可以根据测试覆盖率来完善单元测试和集成测试，确保Web部件在不同环境下的稳定性和可靠性。

#### 6.3 迭代和发布更新

在对Web部件进行改进和修复之后，我们可以通过打包工具将更新后的Web部件部署到对应的环境中，如测试环境、预发布环境和生产环境，同时及时更新文档和版本记录，让团队成员了解到更新内容和变更情况。

通过测试和迭代，我们可以持续改进和优化Web部件的功能和性能，提升用户体验并保证系统的稳定性。