65.9K
CodeProject 正在变化。 阅读更多。
Home

SharePoint 框架 (SPFx) 扩展、字段自定义器 – 自定义托管元数据字段

RaySukanta
starIconstarIconstarIconstarIconstarIcon

5.00/5 (2投票s)

2019年6月10日

CPOL

10分钟阅读

viewsIcon

11734

使用 SPFx 自定义托管元数据字段

引言

使用 JSON 列格式在 SharePoint 列表中生成仪表板在 SharePoint 平台中是一项非常常见的任务。但就目前而言，一旦涉及到托管元数据类型的列，JSON 列格式将不支持。

因此，如果有任何要求，当字段/列类型为数字、日期和时间以及托管元数据的值为空或空白时，用彩色背景标记/渲染单元格，前两种类型将非常容易实现。

使用 JSON 列格式，为具有文本、数字和日期时间类型的空或空白单元格显示彩色背景非常容易。但是 JSON 列格式不支持托管元数据。

为了实现相同的功能，根据 Microsoft 文档，SharePoint 框架扩展 (SPFx) 中的字段自定义是另一种选择。

背景

在我为托管元数据实现字段自定义器扩展的探索中，我无法从网上找到任何合适的示例。几乎所有可用的主题都基于 Microsoft 为基本数字类型列提供的默认实现。

此外，也没有明确提及字段自定义器扩展是否适用于列表的现有字段，或者是否总是需要添加由扩展部署的新网站列并将其作为新的列表列实现。

答案是肯定的。我们可以在列表的现有字段中实现字段自定义器扩展，或者添加由扩展部署的新网站列并将其作为新的列表列实现。

必备组件

开发 SPFx 应用程序，以下是先决条件

  • 安装开发工具 - NodeJS（NodeJS LTS 版本 8）
  • 安装代码编辑器（例如 Visual Studio Code）
  • 安装 Yeoman 和 gulp 以启动新项目。在命令提示符中使用以下命令
    npm install -g yo gulp
  • 安装 Yeoman SharePoint 生成器以快速创建 SharePoint 客户端解决方案项目。在命令提示符中使用以下命令
    npm install -g @microsoft/generator-sharepoint
  • 信任自签名开发人员证书，以从您的开发环境测试您的自定义解决方案，默认使用 HTTPS。一旦使用 SharePoint 框架的 Yeoman 生成器创建了项目，请在项目根文件夹中执行以下命令。
    gulp trust-dev-cert

要获取有关设置 SharePoint 框架开发环境的详细信息，请查看此 Microsoft 文档 - 设置您的 SharePoint 框架开发环境

为托管元数据创建字段自定义器扩展项目

以管理员身份运行 Windows PowerShell 或命令提示符，并使用以下命令在您首选的位置创建名为“FieldCustomizer-MMD”的新项目目录

md FieldCustomizer-MMD

使用以下命令移动到新创建的项目目录

cd FieldCustomizer-MMD

通过运行 Yeoman SharePoint 生成器创建新的ManagedMetadata扩展。

yo @microsoft/sharepoint

在提示时提供所需信息

  1. 对于“您的解决方案名称是什么？”，保留默认的FieldCustomizer-MMD，然后选择Enter。
  2. 对于“您希望您的组件定位哪些基线包？”，保留“仅限 SharePoint Online（最新）”，然后选择Enter。
  3. 对于“您想将文件放在哪里？”，保留“使用当前文件夹”，然后选择Enter。
  4. 选择否 (N) 以要求租户管理员在每个网站上安装扩展，然后按 Enter。在这里，请确保选择否 (N)。如果选择是 (y)，则不会通过脚手架生成Elements.xml功能部署文件。
  5. 对于“要创建哪种类型的客户端组件？”，选择“扩展”（使用箭头键）
  6. 从可用选项列表中选择“字段自定义器”作为扩展类型。

一旦您选择字段自定义器，下一组提示会要求提供有关您的扩展的信息。

  1. 添加MMD_CUSTOMIZER作为您的扩展名称，然后按Enter。
  2. 添加“自定义托管元数据列”作为“您的字段自定义器描述是什么？”的描述，然后选择Enter。
  3. 从可用选项列表中选择“字段自定义器”作为扩展类型。
  4. 选择“无 JavaScript 框架”作为您想使用哪个框架？

Yeoman SharePoint Generator

此时，Yeoman 安装所需的依赖项，并为解决方案文件和字段自定义器扩展搭建脚手架。这可能需要一些时间。

当脚手架完成后，将显示成功脚手架消息。

Scaffold Message

要启动代码编辑器 (Visual Studio Code)，请键入以下命令

code .

解决方案结构

将显示默认解决方案结构，如下所示。这是基本的 SharePoint 框架解决方案结构，所有解决方案类型都具有相似的配置选项。

Solution Structure

重要文件

  • MmdCustomizerFieldCustomizer.manifest.json

    此文件包含扩展类型和扩展的唯一 ID。MmdCustomizerFieldCustomizer_manifest_json

    {

"$schema": "https://developer.microsoft.com/json-schemas/spfx/
            client-side-extension-manifest.schema.json",
"id": "250b7e53-ef2f-44f9-a0a5-279f6281dc80",
"alias": "MmdCustomizerFieldCustomizer",
"componentType": "Extension",
"extensionType": "FieldCustomizer",

// 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/en-us/
// article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
"requiresCustomScript": false

}
  • MmdCustomizerFieldCustomizer.ts

    字段自定义器的逻辑包含在OnInit()、onRenderCell()和onDisposeCell()方法中。

    默认代码将由 Yeoman SharePoint 生成器生成。

    为了满足要求，即在 SharePoint 列表的视图中为包含空白值的托管元数据列显示彩色背景，需要在onRenderCell()方法中实现以下代码

    MmdCustomizerFieldCustomizer_ts

    @override

  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {

    // Use this method to perform your custom cell rendering.
    //var text: string = `${this.properties.sampleText}: ${event.fieldValue.Label}`;
     var text: string = `${event.fieldValue.Label}`;

    if(text!='undefined')
    {
      event.domElement.innerText = text;
    }
    else
    {
      //event.domElement.innerText = "NA";
      event.domElement.innerHTML = `
        <div class="od-FieldRenderer-customFormatter">
          <div style="padding:0 4px;color:#000000; height:41.99px" 
           class="sp-field-customFormatter sp-field-severity--severeWarning">
          </div>
        </div>`;
    }
    event.domElement.classList.add(styles.cell);
  }
  • MmdCustomizerFieldCustomizer.module.scss

如果列为空，请在此文件中更新样式以显示特定颜色。

MmdCustomizerFieldCustomizer_module_css

MmdCustomizer {
  .cell {
    display: inline-block;
  }
  .full {
    background-color: #fbd9cc
  }

  .od-FieldRenderer-customFormatter {
    min-height: 41px;
    margin: -11px 0;
    white-space: normal;
  }

  .sp-field-customFormatter {
    min-height: inherit;
    display: -webkit-box;
    display: -ms-flexbox;
    display: flex;
    -webkit-box-align: center;
    -ms-flex-align: center;
    align-items: center;
  }

  .sp-field-severity--severeWarning {
    background-color: rgba(234, 67, 0, .2);
  }

}

调试字段自定义器应用程序

要测试/调试应用程序，我们需要直接针对实时 SharePoint Online 站点使用它们。我们不必将自定义项部署到应用程序目录。一些简单的配置将启用此应用程序的调试功能。

为了测试这一点，我创建了以下包含“国家”作为托管元数据字段的列表。

ListPoC

打开config文件夹中的serve.json文件。根据我们现有列表中的分类/托管元数据字段名称，将InternalFieldName属性更新为“Country”。还要更新pageUrl属性，以匹配我们在预览步骤中刚刚创建的列表的 URL。

编辑后，您的serve.json应如下所示

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://netxplore.sharepoint.com/Lists/ListPOC/AllItems.aspx",
      "mmdCustomizer": {
        "Country": {
          "id": "250b7e53-ef2f-44f9-a0a5-279f6281dc80",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    },

    "mmdCustomizer": {
      "pageUrl": "https://netxplore.sharepoint.com/Lists/ListPOC/AllItems.aspx",
      "fieldCustomizers": {
        "Country": {
          "id": "250b7e53-ef2f-44f9-a0a5-279f6281dc80",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    }
  }
}

要编译代码并从本地计算机托管它，请从 powershell/cmd 提示符使用以下命令

GulpServe

当代码编译没有错误时，它会从https://:4321提供生成的清单。这还将启动serve.json文件中定义的 URL 中的默认浏览器。

导航到默认浏览器，然后单击“加载调试脚本”以继续从本地主机加载脚本。

AllowDebugScript

请注意“国家”列现在如何为自定义并作为字段自定义器属性提供的空记录显示彩色背景。

listpoc_formatted

将扩展部署到 SharePoint Online

由于我们已在调试模式下正确测试了解决方案，我们可以将其打包，以便作为部署到站点的解决方案包的一部分自动部署。我们需要将解决方案包安装到应安装它的站点，以便扩展清单被列入白名单以执行。

我们需要在网站或列表级别的SPField对象中关联以下属性。

  • ClientSiteComponentId是已安装在应用程序目录中的字段自定义器的标识符 (GUID)。
  • ClientSideComponentProperties是一个可选参数，可用于为字段自定义器实例提供属性。

我们需要将ClientSideComponentId与特定对象关联，以便扩展可见。

要添加到部署解决方案包中的字段定义

默认字段定义会自动创建，然后将用于在站点上安装解决方案包时自动部署所需的配置。默认字段定义在解决方案根目录的sharepoint文件夹和assets子文件夹下的elements.xml文件中定义

elements_xml

打开sharepoint\assets文件夹中的elements.xml文件。

请注意elements.xml中的以下 XML 结构。ClientSideComponentId属性已自动更新为src\extensions\mmdCustomizer文件夹中MmdCustomizerFieldCustomizer.manifest.json文件中可用的字段自定义器的唯一 ID。

我们需要调整此文件以匹配我们的字段类型和详细信息。

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{23d1a782-c24c-4b97-bfdf-36bd4660f037}"
    Name="TxFieldFx"
    DisplayName="TaxonomyField"
    Type="TaxonomyFieldType"
    Required="FALSE"
    Group="SPFxTaxonomyColumns"
    ClientSideComponentId="250b7e53-ef2f-44f9-a0a5-279f6281dc80">
    </Field>
</Elements>

为了确保在打包解决方案时考虑到element.xml文件，默认脚手架添加了所需的配置，以为解决方案包定义功能框架功能定义。

从config文件夹打开package-solution.json。package-solution.json文件定义了包元数据，如以下代码所示

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/
              package-solution.schema.json",
  "solution": {
    "name": "mmd-customization-client-side-solution",
    "id": "675fdae4-58e1-43c8-8d3c-6d2c475abbbe",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [
      {
        "title": "Application Extension - Deployment of custom action.",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "0b0d302f-3460-4c93-8752-aa806745cfb5",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/mmd-customization.sppkg"
  }
}

还要注意，默认情况下，includeClientSideAssets属性设置为true，这意味着 JavaScript 资产会自动打包在sppkg文件中。

将字段自定义器扩展部署到 SharePoint Online

现在我们准备将解决方案部署到 SharePoint 站点。

我们将使用此打包的ship 选项，以便所有资产都自动打包在解决方案包中。

  • 在控制台窗口中，输入以下命令以打包包含扩展的客户端解决方案，以便我们获得准备打包的基本结构

    Gulp Build

  • 执行以下命令以创建解决方案包

    Gulp Package Solution

  • 该命令在sharepoint/solution文件夹中创建包：mmd-customization.sppkg

    现在我们可以将生成的包部署到应用程序目录。我们可以将包部署到租户的应用程序目录或任何特定网站集的应用程序目录。

    将位于sharepoint/solution文件夹中的mmd-customization.sppkg上传到应用程序目录。

    请注意，SharePoint 将显示信任对话框，并要求您信任以 SharePoint Online 作为域的客户端解决方案。资产将根据您的租户设置自动从应用程序目录 URL 或 Office 365 公共 CDN 托管。

    Install Solution

  • 选择“部署”按钮。

    部署后，它将以“已部署”状态显示在应用程序目录中。

    AppCatalog

现在应在相应的网站集中添加并激活已安装的应用程序。为此，请选择右上角顶部导航栏上的齿轮图标，然后选择“添加应用程序”以转到您的“应用程序”页面。

Add App

它将打开所有可用的应用程序。选择mmd-customization-client-side-solution以在网站中安装。

Site Content App

安装完成后，按 F5 刷新页面。应用程序将在网站内容中可用。

Site Content

现在我们可以将此扩展用于新列表，或者我们可以将其应用于现有列表。

为新列表应用扩展

  • 创建一个新列表。
  • 创建新列表后，在“网站内容”页面上，从新创建列表的菜单中选择“设置”。
  • 在“列”下，选择“从现有网站列添加”。
  • 在SPFxTaxonomyColumns组下，选择从解决方案包预配的“TaxonomyField”字段，然后选择确定。

Site Columns

  • 列“TaxonomyField”将添加到您的列表中。
  • 现在将列重命名为所需的名称，例如“国家”

    Configure Column

  • 使用现有术语集对其进行配置，以便可以在列表中使用。对于此示例，它配置为国家。

    Configure Termset

    现在，如果您在列表中输入数据并 GZ 将国家字段留空，则国家字段将显示彩色背景。

    Formatted List

在现有列表中为任何现有托管元数据列应用扩展

如果我们有任何现有列表，其中包含不是从网站列组“SPFxTaxonomyColumns/TaxonomyField”创建的托管元数据列，我们可以实现相同的功能，而无需修改列表或添加新的网站列。

通过将已安装应用程序/扩展的ClientSideComponentId（在elements.xml中提及）与现有字段/列（此处为托管元数据列）关联，我们可以实现相同的功能（在本例中，为空单元格显示彩色背景）。

为此，我们需要 PowerShell 脚本 (PnP) 的帮助。

  • 首先，获取列表的 Guid 和将应用功能的列的名称
  • 然后，使用以下命令连接到站点
    Connect-PnPOnline –Url https://abcdxxxxx.sharepoint.com –Credentials (Get-Credential
  • 然后使用以下命令将现有字段的客户端组件 ID 更新为已安装应用程序/扩展的客户端组件 ID
    Set-PnPField
  • 要更新的列名
    -Identity 'Country'
  • 已安装应用程序/扩展的客户端组件 ID
    -Values @{ClientSideComponentId=[GUID]"250b7e53-ef2f-44f9-a0a5-279f6281dc80"}
  • 要更新的列表的 GUID
    -List '1af75e99-bdfb-47ae-a51a-960080d15eb6'
    Set-PnPField -Identity 'Country' 
             -Values @{ClientSideComponentId=[GUID]"250b7e53-ef2f-44f9-a0a5-279f6281dc80"} 
             -List '1af75e99-bdfb-47ae-a51a-960080d15eb6'

    一旦此命令成功执行，托管元数据列将按上述方式运行。

    您可以在单个列表或不同列表中添加多个托管元数据列，并使用相同的更新客户端组件 ID 来获得相同的功能。只要扩展安装在站点中，并且客户端组件 ID 与控件关联，它就会按预期工作。

历史

  • 2019 年 6 月 10 日：初始版本
© . All rights reserved.