SharePoint 框架的 Yeoman 生成器

项目
04/08/2023

SharePoint Online SPFx Yeoman 生成器 可帮助你使用正确的工具链和项目结构快速创建 SharePoint 客户端解决方案项目。它与 Yeoman 一起使用，提示你提出问题，以创建项目基架 (& 文件夹文件) 。

重要

本页假定你已安装开发 SharePoint 框架解决方案所需的所有先决条件。验证页面中概述的更新说明设置 SharePoint 框架开发环境。

SharePoint Online SPFx Yeoman 生成器 (“SPFx 生成器”)，使用开发人员对提示问题的回答来创建新 SharePoint 框架 (SPFx) 项目。根据一些提示性回答，提出其他问题。

例如，如果选择 Web 部件 组件类型，则只会看到有关 Web 部件名称和模板类型的问题。但是，如果选择扩展组件类型，系统还会提示你输入扩展类型，例如应用程序自定义工具、字段定制器或 ListView 命令集。

下面演示了如何在当前文件夹中创建名为 sfpxplay-01 的新解决方案，其中有一个使用最小项目模板的 Web 部件HelloWorld:

yo @microsoft/sharepoint --skip-install

     _-----_     ╭──────────────────────────╮
    |       |    │      Welcome to the      │
    |--(o)--|    │  SharePoint Online SPFx  │
   `---------´   │          Yeoman          │
    ( _´U`_ )    │     Generator@1.14.0     │
    /___A___\   /╰──────────────────────────╯
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

Let's create a new SharePoint solution.
? What is your solution name? spfxplay-01
? Which type of client-side component to create? WebPart
Add new Web part to solution spfxplay-01.
? What is your Web part name? HelloWorld
? Which template would you like to use? Minimal

   create package.json
    force .yo-rc.json
   create config/package-solution.json
   create config/config.json
   create config/serve.json
   create tsconfig.json
   create .vscode/launch.json
   create .vscode/settings.json
   create config/deploy-azure-storage.json
   create config/write-manifests.json
   create src/index.ts
   create README.md
   create .gitignore
   create .npmignore
   create gulpfile.js
   create tslint.json
   create src/webparts/helloWorld/loc/en-us.js
   create src/webparts/helloWorld/loc/mystrings.d.ts
   create src/webparts/helloWorld/HelloWorldWebPart.module.scss
   create src/webparts/helloWorld/HelloWorldWebPart.ts
   create src/webparts/helloWorld/HelloWorldWebPart.manifest.json
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_outline.png
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_color.png

Changes to package.json were detected.
Skipping package manager install.

      _=+#####!
   ###########|       .------------------------------------.
   ###/    (##|(@)    |          Congratulations!          |
   ###  ######|   \   |  Solution spfxplay-01 is created.  |
   ###/   /###|   (@) |   Run gulp serve to play with it!  |
   #######  ##|   /   '------------------------------------'
   ###     /##|(@)
   ###########|
      **=+####!

提示

此站点中的文档中介绍了不同的组件类型和选项。此页面不涵盖每个选项。有关每个组件类型的详细信息，请参阅整个文档中的相关主题。

安装 SharePoint Online SPFx Yeoman 生成器

SPFx 生成器可用作 npm 包。通过在控制台中执行以下命令来安装最新版本的 SPFx 生成器：

npm install @microsoft/generator-sharepoint -g

还可以通过在包名称中指定版本号（用 @1 分隔）来安装特定版本的生成器。例如，如果要安装 SPFx 生成器 v1.10，请执行以下命令：

npm install @microsoft/generator-sharepoint@1.10 -g

项目模板选项

在 SPFx v1.14 之前，生成器为开发人员提供了两个项目模板:

无 JavaScript 框架:
React

注意

第三个选项 Knockout 在 SPFx v1.10 之前的所有 SPFx 版本中可用。已在 SPFx v1.11 中将 Knockout 作为选项停用。

这些模板包含项目开始创建解决方案所需的最小代码。 无 JavaScript 框架 模板使用 HTML 和 CSS 来设置基本组件的样式，而 React 模板使用 HTML、React 和 CSS 执行相同的操作。

SPFx v1.14 中使用主题支持更新项目模板

在 SPFx v1.14 版本中，SPFx 生成器引入了新的 & 更新项目模板。这些模板的目标是包括必要的代码，以支持该组件在当前环境中运行的主题 (SharePoint 或 Microsoft Teams)。

这些模板中包含的代码简化了开发人员为向其组件添加主题支持而必须执行的初始工作。例如，使用这些模板时，确定当前 SharePoint 网站中使用的颜色和字体所需的所有代码均可在 Web 部件中使用，当主题更改以选取新主题设置时，Web 部件将收到通知。

对于 Microsoft Teams 上下文中使用的 SPFx 组件，它们将收到当前 Microsoft Teams 客户端的主题详细信息，例如默认值 (浅色)、深色和高对比度。

此外，这些模板包括用于确定组件当前是在 SharePoint 上下文中运行还是在 Microsoft Teams 上下文中运行的代码。

例如，以下方法包含在这两个模板中。 _getEnvironmentMessage() 方法返回一个字符串，该字符串指示组件当前是否在 SharePoint 或 Microsoft Teams 中运行，以及是否部署到生产或开发中 (由 localhost 提供)。 onThemeChanged()确定当前主题是否处于深色模式，并根据当前主题颜色对属性应用进行一些更改:

private _getEnvironmentMessage(): string {
  if (!!this.context.sdks.microsoftTeams) { // running in Teams
    return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentTeams
        : strings.AppTeamsTabEnvironment;
  }

  return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentSharePoint
        : strings.AppSharePointEnvironment;
}

protected onThemeChanged(currentTheme: IReadonlyTheme | undefined): void {
  if (!currentTheme) {
    return;
  }

  this._isDarkTheme = !!currentTheme.isInverted;
  const {
    semanticColors
  } = currentTheme;
  this.domElement.style.setProperty('--bodyText', semanticColors.bodyText);
  this.domElement.style.setProperty('--link', semanticColors.link);
  this.domElement.style.setProperty('--linkHovered', semanticColors.linkHovered);

}

最小项目模板

在 SPFx v1.14 中，SPFx 生成器增加了一个新的项目模板选项 最小化。此项目模板选项在新项目中不包含主题或主机环境代码。

例如，新的 Web 部件项目以以下代码开头，表示运行 Web 部件所需的最小代码:

export default class HelloWorldMinimalWebPart
          extends BaseClientSideWebPart<IHelloWorldMinimalWebPartProps> {

  protected onInit(): Promise<void> {
    return super.onInit();
  }

  public render(): void {
    this.domElement.innerHTML = `<div class="${ styles.helloWorldMinimal }"></div>`;
  }

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

已停用的生成器提示

随着 SharePoint 框架的每一次发布，Yeoman 生成器中可能会增加或删除提示信息。为简化项目创建体验，删除了提示信息。

在以下部分中，你将找到具有适用指导的已停用提示。

面向不同的 SharePoint 环境

在 SPFx v1.13 版本中，已停用以下提示:

你想要为你的组件设定哪些基准包？

此提示向开发人员提供了创建面向特定 SharePoint 部署的项目选项，包括:

仅 SharePoint Online（最新）
SharePoint 2016 及更高版本，包括 2019 和 SharePoint Online
SharePoint 2019 及更高版本，包括 SharePoint Online

从 SPFx v1.13 开始，生成器只能为 SharePoint Online 创建项目。

跳过功能部署 - `skipFeatureDeployment`

在 SPFx v1.14 版本中，已停用以下提示:

是否要允许租户管理员选择能够立即将解决方案部署到所有站点的选项，而无需运行任何站点中的部署或添加应用程序功能?

此问题是询问是应为租户中的所有站点自动安装解决方案，还是应在每个站点中手动安装该解决方案? 默认选项为 [N]o。

注意

了解更多关于此提示的信息: SharePoint 框架解决方案的租户范围解决方案部署。

此问题的结果设置在项目的 ./config/package-solution.json 文件中的 skipFeatureDeployment 属性上。

从 SPFx v1.14 开始，skipFeatureDeployment 属性默认为 true。如有必要，可以在创建项目后更改此属性的值。

域隔离 Web 部件 - `isDomainIsolated`

在 SPFx v1.14 版本中，已停用以下提示:

解决方案中的组件是否需要访问唯一且不与租户中的其他组件共享的 Web API 的权限？

此问题是询问解决方案中的 Web 部件是应在唯一域的 IFRAME 中呈现，还是作为当前页面在 DIV 中呈现。默认选项为 [N]o。

注意

了解更多关于此提示的信息: 独立 Web 部件

此问题的结果设置在项目的 ./config/package-solution.json 文件中的 isDomainIsolated 属性上。

从 SPFx v1.14 开始，isDomainIsolated 属性默认为 false。如有必要，可以在创建项目后更改此属性的值。

要使用哪种框架?

在 SPFx v1.14 版本中，更改了以下提示:

要使用哪种框架?

对于特定项目类型，例如 SPFx 扩展的 Web 部件 & 类型，将显示此提示。它使开发人员能够从不同的项目模板中进行选择: 无 JavaScript 框架 或 React。

由 Yeoman 生成器创建的默认项目基架是使用所选选项确定的。

在 SPFx v1.14 中，此提示已更改为以下内容，并向用户提供了三个选项: 最小、无框架 或 React:

你想要使用哪个模板?

组件说明

在 SPFx v1.14 版本中，已停用以下提示:

Web 部件说明是什么?

你的应用程序定制器说明是什么？

字段自定义工具的说明是什么?

你的 ListView 命令集说明是什么?

你的库说明是什么?

自适应卡片扩展说明是什么?

这些提示的值是在组件的 *.manifest.json 文件中的属性上preConfiguredEntries[0].description.default&preConfiguredEntries[0].properties.description设置的。

从 SPFx v1.14 开始，这些属性设置为空字符串。如有必要，可以在创建项目后更改这些属性的值。

SPFx 生成器命令行选项

可以使用 SPFx 生成器的命令行选项在一个命令中创建项目，而不是通过提示。执行以下命令以查看对 SharePoint 生成器可用的命令行选项的列表：

yo @microsoft/sharepoint --help

通过

SharePoint 框架的 Yeoman 生成器

安装 SharePoint Online SPFx Yeoman 生成器

项目模板选项

SPFx v1.14 中使用主题支持更新项目模板

最小项目模板

已停用的生成器提示

面向不同的 SharePoint 环境

跳过功能部署 - skipFeatureDeployment

域隔离 Web 部件 - isDomainIsolated

要使用哪种框架?

组件说明

SPFx 生成器命令行选项

其他资源

跳过功能部署 - `skipFeatureDeployment`

域隔离 Web 部件 - `isDomainIsolated`