在新式 SharePoint 页面上调试 SharePoint 框架解决方案

在构建 SharePoint 框架解决方案时，可以在新式 SharePoint 页面上对它们进行测试。 对于构建 SharePoint 框架扩展，在新式页面上进行测试是唯一的选择，因为目前 SharePoint 工作台不支持加载扩展。 然而，新式页面上的测试也可用于调试 Web 部件，为开发人员提供附加价值。

重要

虽然在新式 SharePoint 页面上调试本地 SharePoint 框架解决方案没有技术限制，但是在生产租户中使用它时应当小心谨慎。 使用该功能可以执行未按照组织策略进行测试和验证的代码，这些代码可能会对你的生产数据带来危害。

在新式 SharePoint 页面上调试 SharePoint 框架扩展

目前，SharePoint 框架扩展只能在新式 SharePoint 页面上进行调试。 SharePoint 工作台不支持测试扩展。 根据所使用的 SharePoint 框架版本，可通过不同方法在新式页面上调试扩展。

使用服务配置调试扩展

向项目添加 SharePoint 框架扩展时，SharePoint 框架 Yeoman 生成器将扩展项目配置。 使用此配置，可以在 Web 浏览器中自动启动一个新式 SharePoint 页面，其中包含在该页面上调试扩展所需的所有参数。

工作原理

向项目添加新的 SharePoint 框架扩展时，SharePoint 框架 Yeoman 生成器将为项目中的 config/serve.json 文件添加一个新条目。 示例条目如下所示：

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    }
  }
}

在默认配置旁边，SharePoint 框架 Yeoman 生成器将为添加到项目中的每个扩展创建一个条目。 每个条目都包含一个应用于测试特定扩展的新式页面 URL、应加载的扩展列表，以及应在每个扩展上设置的属性列表。 要使用特定的服务配置，请在命令行中执行：

gulp serve --config=<name>

例如：

gulp serve --config=helloWorld

运行此命令后，gulp 将在 Web 浏览器上启动配置中指定的新式页面。 该页面将显示一个弹出框，要求你确认是否立即加载调试脚本。

确认后，该页面将加载在服务配置中指定的扩展。

禁用调试脚本

默认情况下，在页面上启用并允许一次调试脚本时，将在整个浏览器会话中允许它们。 若要禁用调试脚本加载而不结束浏览器会话或手动删除会话数据，请在请求中包括 URL 参数reset=true。

通过手动构建调试 URL 来调试扩展

如果使用的是一个低于 1.3.0 版本的 SharePoint 框架，并且想要在新式页面上调试扩展，必须手动构造包含所需参数的 URL。 首先，通过在命令行中将工作目录更改为项目文件夹并执行以下命令来启动本地 gulp 服务器：

gulp serve --nobrowser

接下来，在 Web 浏览器中，导航到希望在其中测试扩展的新式页面。 加载完页面后，复制它的 URL。 根据要测试的扩展类型，有不同的参数需要添加到 URL 中。

调试应用程序自定义工具

要调试“应用程序自定义工具”，请向新式页面的 URL 添加以下项目：

谨慎

为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
    "location":"<extensionType>",
    "properties":<propertiesJSON>
}}

例如：

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
    ?loadSPFX=true
    &debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={
        "e5625e23-5c5a-4007-a335-e6c2c3afa485":{
          "location":"ClientSideExtension.ApplicationCustomizer",
          "properties":{
            "testMessage":"Hello as property!"
          }
        }
    }

以下是需要添加的查询字符串参数：

参数	说明
loadSPFX=true	确保 SharePoint 框架在页面上加载。 出于性能原因，除非至少有一个扩展进行注册，否则不会加载框架。 由于尚未注册任何组件，因此必须显式加载框架。
debugManifestsFile	指定要加载在本地获得服务的组件。 加载程序只在应用程序目录（对于已部署的解决方案）和 SharePoint 清单服务器（对于系统库）中查找组件。
customActions	模拟自定义操作。 在网站中部署和注册此组件时，将创建这个 CustomAction 对象，并描述可以对它设置的所有不同属性。

customActions 参数具有以下应替换的令牌：

标记	说明
<extensionId>	将扩展的 GUID 用作关联自定义操作的键。 这必须与扩展名的 ID 值匹配，该值在 manifest.json文件扩展名中可用。
<extensionType>	自定义操作类型。 对应用自定义工具扩展使用 ClientSideExtension.ApplicationCustomizer。
<propertiesJSON>	一个可选的 JSON 对象，其中包含可通过 this.properties 成员提供的属性。

使用添加到 URL 中的参数，在 Web 浏览器中重新加载页面。 该页面将显示一个弹出框，要求你确认是否立即加载调试脚本。

确认后，该页面将加载在服务配置中指定的扩展。

调试字段自定义工具

若要调试“字段自定义工具”，请将以下内容添加到新式页面的 URL：

谨慎

为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={
    "<fieldName>":{
      "id":"<fieldCustomizerId>",
      "properties":<propertiesJSON>
    }
}

例如：

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &fieldCustomizers={
    "Percent":{
      "id":"45a1d299-990d-4917-ba62-7cb67158be16",
      "properties":{
        "sampleText":"Hello!"
      }
    }
  }

以下是需要添加的查询字符串参数：

参数	说明
loadSPFX=true	确保 SharePoint 框架在页面上加载。 出于性能原因，除非至少有一个扩展进行注册，否则不会加载框架。 由于尚未注册任何组件，因此必须显式加载框架。
debugManifestsFile	指定要加载在本地获得服务的组件。 加载程序只在应用程序目录（对于已部署的解决方案）和 SharePoint 清单服务器（对于系统库）中查找组件。
fieldCustomizers	指示列表中的哪些字段应由字段自定义工具控制其呈现。 ID 参数指定应该用于控制字段呈现的扩展的 GUID。 properties 参数是可选文本字符串，其中包含 JSON 对象，它会反序列化为扩展的 this.properties。

fieldCustomizers 参数具有以下应替换的令牌：

标记	说明
<fieldName>	字段的内部名称。
<fieldCustomizerId>	与此字段关联的字段自定义工具扩展的 GUID。
<propertiesJSON>	扩展中定义的属性值。 在本示例中，sampleText 是由扩展定义的属性。

使用添加到 URL 中的参数，在 Web 浏览器中重新加载页面。 该页面将显示一个弹出框，要求你确认是否立即加载调试脚本。

确认后，该页面将加载在服务配置中指定的扩展。

调试列表视图命令集

若要调试列表视图命令集，请将以下内容添加到新式页面的 URL：

谨慎

为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
  "location":"<extensionType>",
  "properties":<propertiesJSON>
}}

例如：

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{
    "location":"ClientSideExtension.ListViewCommandSet.CommandBar",
    "properties":{
      "sampleTextOne":"One item is selected in the list.",
      "sampleTextTwo":"This command is always visible."
    }
  }}

以下是需要添加的查询字符串参数：

参数	说明
loadSPFX=true	确保 SharePoint 框架在页面上加载。 出于性能原因，除非至少有一个扩展进行注册，否则不会加载框架。 由于尚未注册任何组件，因此必须显式加载框架。
debugManifestsFile	指定要加载在本地获得服务的组件。 加载程序只在应用程序目录（对于已部署的解决方案）和 SharePoint 清单服务器（对于系统库）中查找组件。
customActions	模拟自定义操作。 可以针对此 CustomAction 对象设置可影响按钮外观和位置的多个属性，我们稍后会进行介绍。

customActions 参数具有以下应替换的令牌：

标记	说明
<extensionId>	扩展的 GUID。
<extensionType>	显示命令的位置。 可能的值有： ClientSideExtension.ListViewCommandSet.ContextMenu：项目的上下文菜单， ClientSideExtension.ListViewCommandSet.CommandBar：列表或库中的顶部命令集菜单。 ClientSideExtension.ListViewCommandSet：上下文菜单和命令栏（对应于 SPUserCustomAction.Location="CommandUI.Ribbon"）。
<propertiesJSON>	一个可选 JSON 对象，包含可通过 this.properties 成员提供的属性。

使用添加到 URL 中的参数，在 Web 浏览器中重新加载页面。 该页面将显示一个弹出框，要求你确认是否立即加载调试脚本。

确认后，该页面将加载在服务配置中指定的扩展。

在新式 SharePoint 页面上调试 SharePoint 框架 Web 部件

要在租户的新式 SharePoint 页面上测试 SharePoint 框架客户端 Web 部件的本地版本，首先，通过将工作目录更改为项目文件夹并在命令行中执行以下命令来启动本地 gulp 服务器：

gulp serve --nobrowser

接下来，在 Web 浏览器中，导航到希望在其中测试 Web 部件的新式页面。 加载页面后，向 URL 添加以下内容：

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

例如：

谨慎

为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js

该页面将重新加载并显示一个弹出框，要求你确认是否立即加载调试脚本。

确认要加载你正在开发的 Web 部件后，可以编辑页面，并在工具箱中选择任何本地 Web 部件。

在新式页面上添加了测试 SharePoint 框架 Web 部件的值

构建 SharePoint 框架 Web 部件时，可以使用本地工作台对其进行测试。 这不仅方便而且高效：每次在代码中更改某些内容时，本地工作台都会自动重新加载该内容并显示最新更改。

在某些情况下，比如在构建与 SharePoint 通信的 Web 部件时，不能使用本地 SharePoint 工作台，因为需要访问 SharePoint API，而这些 API 只能在 SharePoint 网站的上下文中调用。 在此类情况下，与其使用本地工作台，不如使用托管的 SharePoint 工作台，可以通过在网站的 URL 中添加 /_layouts/15/workbench.aspx 来访问它，例如 https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx。

UI 约束

SharePoint 框架工作台可以很方便地模仿新式 SharePoint 页面画布。 但它并没有模仿所有方面。 画布的宽度不同、并非所有主题颜色都会反映出来，而且工作台不允许测试跨页体验，其中 Web 部件跨越 Web 浏览器的全宽，而没有任何水平边距或填充。

它是否与其他 Web 部件和扩展一起工作

使用 SharePoint 工作台，只能从解决方案测试 Web 部件。 但是，如果想要了解 Web 部件如何与页面上的其他 Web 部件一起工作呢？ 使用本文概述的方法在新式页面上测试本地解决方案，比打包项目、将其部署到应用程序目录，然后将 Web 部件添加到页面的方式更为有效。

调试 SharePoint 框架 Web 部件 - 替代方法

如果在没有 的情况下生成 Web 部件解决方案 --ship 参数，如下所示：

gulp bundle
gulp package-solution

生成的包将引用本地计算机中的代码 (https://localhost:4321). 您可以正常部署解决方案到应用程序目录。

然后，可以通过运行以下命令来启动本地服务器：

gulp serve --nobrowser

现在，你可以返回到已部署解决方案的 SharePoint 网站，并将 Web 部件添加到任何页面（新式或经典），然后将从你的本地开发环境中加载 Web 部件代码。 可以像运行 gulp 服务 并将 Web 部件添加到工作台一样调试 Web 部件。

仅可在开发模式中，才能使用这种方法。 若你部署一个应用到指向你本地主机的应用目录，若开发环境未处于运行状态，则该应用无法运行。

另请参阅

• 在 Visual Studio Code 中调试 SharePoint 框架解决方案
• 轻松测试新式页面上的 SharePoint 框架 Web 部件（Waldek Mastykarz、Rencore）
• 在生产中测试和调试 SPFx 解决方案而不会产生任何影响 (Elio Struyf)
• SharePoint 框架的 Yeoman 生成器
• SharePoint 框架概述