从 XSLT 视图呈现升级到列表格式

2023-09-03

在 SharePoint 经典世界中，你已习惯使用 XSLT (可扩展样式表语言来自定义列表和库的呈现) 和 XsltListViewWebPart 控件。如今，在现代世界中，你可以依靠列表格式获得更好的结果。

重要

本文指的是所谓的 PnP 组件、示例和/或工具，它们是由提供支持的活动社区支持的开源资产。没有来自 Microsoft 的官方支持渠道的开放源代码工具支持的 SLA。但是，这些组件或示例使用的是 Microsoft 支持的现成 API 和 Microsoft 支持的功能。

如果愿意，可以watch以下视频，而不是阅读整篇文章，你仍然可以将其视为更详细的参考。

事实上，通过“列表格式”，可以通过列格式或通过列表视图格式来自定义单个字段的呈现，或者通过列表视图格式来呈现整个列表视图。可以使用 SharePoint 的基于 Web 的 UI 和用户友好的设计器或编写自己的自定义 JSON 模板轻松执行此操作。在封面下，列表格式将处理客户端数据的呈现，而不会影响或更改实际数据，但只是在它上面应用自定义呈现模板。

此外，列表格式可以应用于 SharePoint 列表和库，以及Microsoft Lists列表，这些列表在封面下依赖于 SharePoint Online。本文介绍如何在解决方案中利用列表格式。

列格式设置

列格式允许自定义列表或库中单个字段的呈现。若要了解如何使用它，让我们在目标网站中创建一个新列表，例如使用 “旅行请求” 列表模板。输出将如以下屏幕截图所示。

具有现成格式的 Travel 请求列表，其中包含一些呈现良好的字段，如航空公司。

使用设计器设置列格式

现在，假设你想要自定义 “旅行持续时间 (天) ” 列的呈现，以突出显示持续时间最长的行程。单击列名称旁边的箭头，选择 “列设置” ，然后选择 “设置此列的格式”，如以下屏幕截图所示，以激活 UI 以自定义列呈现。

用于在 SharePoint Online 中激活列格式编辑器的上下文菜单。单击列名称旁边的箭头，选择“列设置”，然后选择“设置此列的格式”。

屏幕右侧将显示一个侧面板，可用于自定义列格式。选择 “条件格式” 并开始自定义所选列的呈现。

用于为所选列配置自定义列呈现的侧面板。可以选择当前列的“条件格式”。

选择后，选项允许你配置所选列的呈现规则。

显示所选列的条件格式规则时的侧面板。

可以根据需要创建任意数量的规则。条件呈现规则可以是全局呈现规则，与特定条件无关，也可以是特定的，当一个或多个条件 (等于或不等于) 针对一个或多个字段进行验证时。然后，对于每个规则，可以定义自定义呈现样式。在以下屏幕截图中，可以看到用于定义规则的基本 UI。

为列定义自定义格式规则时的侧面板。可以定义一个或多个条件和呈现样式。

配置呈现样式时，只需选择一种现成的样式，也可以单击 “更多样式” 并访问一整套样式设置，如以下屏幕截图所示。

定义自定义样式时的侧面板。可以定义自定义字体、文本和填充颜色、图标、图标颜色和边框。

可以看到，自定义样式可以由许多设置组成，例如字体、文本颜色、填充颜色、图标、图标颜色和边框。在以下屏幕截图中，可以看到为 “旅行工期 (天) ” 列定义的规则，其中 1 到 3 天的持续时间是“正常”的，用绿色突出显示，4 天的持续时间是“有风险的”，并用橙色突出显示，而 5 天的持续时间 (整个星期) 被视为太长，并用红色突出显示。

定义自定义样式时的侧面板。可以定义自定义字体、文本和填充颜色、图标、图标颜色和边框。

如前所述，只需使用 Web 浏览器和设计器即可定义此类规则。

使用自定义 JSON 模板设置列格式

但是，如果需要定义更高级的规则，该怎么办？例如，如果要为 “旅行工期 (天) ” 列而不是显式值定义值引用范围，该怎么办？或者，如果要为列定义完全自定义的呈现，该怎么办？

幸运的是，可以单击屏幕下部显示的 “高级模式” ，并开始在低级别编辑 JSON 模板。

注意

模板的 JSON 基于 Microsoft 定义的架构，可在以下 URL 中找到，可以在格式设置语法参考文档中找到详细信息架构参考。

在高级模式下定义自定义样式时的侧面板。有一个用于在低级别编辑 json 模板的文本区域。

有趣的是，当你选择切换到高级模式时，JSON 模板将开始向你显示已定义的实际条件格式的 JSON 模板。因此，可以从设计器轻松开始，如果需要更多内容，可以切换到高级模式，然后从已有位置继续。

即使本文无法深入了解 JSON 模板语法的所有详细信息，但检查为 “旅行持续时间 (天) ” 列生成的 JSON 也很有用，如以下代码摘录中所示。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "style": {
    "box-sizing": "border-box",
    "padding": "0 2px",
    "overflow": "hidden",
    "text-overflow": "ellipsis"
  },
  "attributes": {
    "class": {
      "operator": ":",
      "operands": [
        {
          "operator": "||",
          "operands": [
            {
              "operator": "||",
              "operands": [
                {
                  "operator": "==",
                  "operands": [
                    "[$TravelDuration]",
                    "1"
                  ]
                },
                {
                  "operator": "==",
                  "operands": [
                    "[$TravelDuration]",
                    "2"
                  ]
                }
              ]
            },
            {
              "operator": "==",
              "operands": [
                "[$TravelDuration]",
                "3"
              ]
            }
          ]
        },
        "sp-css-backgroundColor-BgMintGreen sp-css-borderColor-MintGreenFont sp-field-fontSizeSmall sp-css-color-MintGreenFont",
        {
          "operator": ":",
          "operands": [
            {
              "operator": "==",
              "operands": [
                "[$TravelDuration]",
                "4"
              ]
            },
            "sp-css-backgroundColor-BgGold sp-css-borderColor-GoldFont sp-field-fontSizeSmall sp-css-color-GoldFont",
            {
              "operator": ":",
              "operands": [
                {
                  "operator": "==",
                  "operands": [
                    "[$TravelDuration]",
                    "5"
                  ]
                },
                "sp-css-backgroundColor-BgDustRose sp-css-borderColor-DustRoseFont sp-field-fontSizeSmall sp-css-color-DustRoseFont",
                ""
              ]
            }
          ]
        }
      ]
    }
  },
  "txtContent": "[$TravelDuration]"
}

JSON 模板定义输出将是具有一些预定义呈现样式的 div HTML 元素。

"elmType": "div",
"style": {
    "box-sizing": "border-box",
    "padding": "0 2px",
    "overflow": "hidden",
    "text-overflow": "ellipsis"
}

然后，它定义一组运算符和操作数，以定义所有规则 (等于 1、2 或 3 的值;值 4;值 5) 以及规则条件生效时要应用的相应 CSS 样式。使用低级别的 JSON 模板，而不是基于 Web 的设计器，甚至可以提高模板的质量和可维护性。例如，无需列出绿色样式 (1、2 或 3) 的所有值，只需为值声明一个小于或等于 3 (= 3) <的规则。这同样适用于红色样式，你可以在其中声明该规则适用于任何大于 5 (>>5) 的值。在以下代码摘录中，可以读取修改后的 JSON 模板。

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    "elmType": "div",
    "style": {
      "box-sizing": "border-box",
      "padding": "0 2px",
      "overflow": "hidden",
      "text-overflow": "ellipsis"
    },
    "attributes": {
      "class": {
        "operator": ":",
        "operands": [
          {
            "operator": "<=",
            "operands": [
              "[$TravelDuration]",
              "3"
            ]
          },
          "sp-css-backgroundColor-BgMintGreen sp-css-borderColor-MintGreenFont sp-field-fontSizeSmall sp-css-color-MintGreenFont",
          {
            "operator": ":",
            "operands": [
              {
                "operator": "==",
                "operands": [
                  "[$TravelDuration]",
                  "4"
                ]
              },
              "sp-css-backgroundColor-BgGold sp-css-borderColor-GoldFont sp-field-fontSizeSmall sp-css-color-GoldFont",
              {
                "operator": ":",
                "operands": [
                  {
                    "operator": ">=",
                    "operands": [
                      "[$TravelDuration]",
                      "5"
                    ]
                  },
                  "sp-css-backgroundColor-BgDustRose sp-css-borderColor-DustRoseFont sp-field-fontSizeSmall sp-css-color-DustRoseFont",
                  ""
                ]
              }
            ]
          }
        ]
      }
    },
    "txtContent": "[$TravelDuration]"
}

这是一个非常简单且基本的示例，但你可以构建非常复杂的呈现规则。例如，可以在列的输出中嵌套 HTML 元素，也可以呈现自定义图像等。

注意

在 GitHub 存储库 SharePoint 列表格式设置示例（特别是列格式示例）中，可以找到许多有关列格式设置的有用示例。

列表视图格式设置

与自定义单个列的呈现一样，可以使用列表格式来自定义列表或库的整个视图的呈现。

若要自定义列表或库的列表视图，只需单击下拉菜单以选择当前视图，然后选择 选项“设置当前视图格式”，如以下屏幕截图所示。

用于激活列表视图格式的菜单项，该格式位于当前列表或库的可用视图的下拉列表下。

单击菜单项，将激活右侧的侧面板，通过该面板可以选择应用非常简单的模板来呈现 “交替行样式”，也可以激活 “条件格式” 并创建更宽松的格式设置模板。与列格式设置一样，可以定义条件和样式规则，这些规则现在将在行级别而不是列级别应用。

用于在“交替行样式”或“条件格式”之间进行选择的侧面板。

此外，在“选择布局”下拉列表中，可以选择创建列表类型的自定义模板（默认模板）或“库”，该模板提供基于卡的输出，你可以在其中自定义字段和卡片的呈现。

用于配置库布局和“卡片设计器”的侧面板。

选择“库”并通过单击“编辑卡”命令激活“卡片设计器”时，可以选择要在卡片中显示的字段、其顺序以及卡的一些常规配置设置。

用于配置库布局和“卡片设计器”的侧面板。

如果想要执行更多操作，可以单击 “高级模式” 并定义完全自定义的 JSON 模板，该模板将应用于整个列表，而不是面向单个列。

注意

在 GitHub 存储库 SharePoint 列表格式设置示例（特别是列表视图格式示例）中，可以找到许多有关列表视图格式设置的有用示例。

列表窗体格式

还有一个选项是自定义列表或库的形式，定义自定义页眉、页脚或正文。事实上，如果位于列表中，则只需显示任何项目的属性，然后单击屏幕右上角的 “编辑表单” 命令，然后选择 “配置布局” 选项，如以下屏幕截图所示。

用于自定义列表项窗体呈现的“编辑表单”命令。

右侧将显示一个侧面板，你将能够配置自定义 JSON 来自定义页眉、页脚或正文的呈现。在以下屏幕截图中，可以看到面板的外观。

用于自定义列表项页眉、页脚或正文呈现的“格式”面板。

相同的行为适用于文档库，但若要激活格式设置面板，必须选择文档，请单击 ECB 菜单 (三个点) ，选择“更多”，然后选择“属性”。然后，在文档属性窗格中，可以选择 “编辑窗体” 和 “配置布局” 选项。

现在，让我们看看可以使用此功能应用哪些类型的自定义项。为简单起见，请继续使用在前面部分创建的“旅行请求”列表，并编辑列表项的标题。例如，假设你想要将默认标头替换为显示请求者的头像和行程目的地的自定义框。在以下屏幕截图中，可以看到输出。

标头自定义的 UI，在框中显示请求者的头像和行程目标。

在以下代码摘录中，可以看到 JSON 模板来获取上述结果。

{
    "elmType": "div",
    "attributes": {
        "class": "ms-bgColor-themePrimary ms-fontColor-white ms-borderColor-neutralTertiary"
    },
    "style": {
        "width": "99%",
        "margin": "10px",
        "border": "1px solid",
        "padding": "10px"
    },
    "children": [
        {
            "elmType": "div",
            "style": {
                "display": "flex",
                "box-sizing": "border-box",
                "align-items": "center"
            },
            "children": [
                {
                    "elmType": "img",
                    "attributes": {
                      "src": "=getUserImage('[$Requester.email]','medium')"
                    },
                    "style": {
                      "border-radius": "50%",
                      "margin-bottom": "10px"
                    }
                  }
            ]
        },
        {
            "elmType": "div",
            "attributes": {
                "class": "ms-fontColor-white ms-fontWeight-bold ms-fontSize-24"
            },
            "style": {
                "box-sizing": "border-box",
                "width": "100%",
                "text-align": "left",
                "padding": "21px 12px",
                "overflow": "hidden"
            },
            "children": [
                {
                    "elmType": "div",
                    "txtContent": "='Travel request to ' + [$Destination.DisplayName]"
                }
            ]
        }
    ]
}

JSON 模板定义一个 HTML DIV 元素，该元素将当前主题 的主要 颜色作为背景色、文本的白色和 1 像素的纯色边框。

"elmType": "div",
"attributes": {
    "class": "ms-bgColor-themePrimary ms-fontColor-white ms-borderColor-neutralTertiary"
},
"style": {
    "width": "99%",
    "margin": "10px",
    "border": "1px solid",
    "padding": "10px"
}

然后有两个 DIV 元素作为上述 DIV 的子级。左侧的第一个 DIV 呈现请求者用户的图像。

{
    "elmType": "div",
    "style": {
        "display": "flex",
        "box-sizing": "border-box",
        "align-items": "center"
    },
    "children": [
        {
            "elmType": "img",
            "attributes": {
              "src": "=getUserImage('[$Requester.email]','medium')"
            },
            "style": {
              "border-radius": "50%",
              "margin-bottom": "10px"
            }
          }
    ]
}

而第二个 DIV 呈现具有目标名称的自定义字符串。

{
    "elmType": "div",
    "attributes": {
        "class": "ms-fontColor-white ms-fontWeight-bold ms-fontSize-24"
    },
    "style": {
        "box-sizing": "border-box",
        "width": "100%",
        "text-align": "left",
        "padding": "21px 12px",
        "overflow": "hidden"
    },
    "children": [
        {
            "elmType": "div",
            "txtContent": "='Travel request to ' + [$Destination.DisplayName]"
        }
    ]
}

请注意用于读取当前项的属性的语法（基于方括号和美元 ($) 符号引用字段），最终指定字段的详细属性，例如$Requester的电子邮件或$Destination的 DisplayName。另请注意，可以依赖 getUserImage 等自定义函数从所选项的字段中检索高级信息。

自定义页脚与页眉一样可自定义，使用的方法与之前完全相同。

相反，可以自定义正文，声明一个或多个自定义节以及每个节的一个或多个列。但是，请注意，一个列只能在一个节中引用，如果不在任何节中引用列，它将自动显示在最后一节中。同样，添加到列表或库的新列将自动列列在最后一列中。

自定义正文的 UI，包含两个部分：“主要信息”和“标题”、“请求者和目标”，以及包含所有提醒字段的“其他”。

在以下代码摘录中，可以看到一个包含“更多信息”部分的正文的 JSON 模板，该模板由字段 Title、Requester 和 Destination 组成，以及名为“Others”的另一个 catch-all 节。

{
    "sections": [
        {
            "displayname": "Main information",
            "fields": [
                "Title",
                "Requester",
                "Destination"
            ]
        },
        {
            "displayname": "Others",
            "fields": []
        }
    ]
}

请注意，每个节对象都由一个 显示名 和一个字段数组组成。

PnP 预配和 JSON 格式设置

使用列表格式设置时要注意的最后一个重要事项是，如果使用 PnP 预配引擎提取网站模板或列表模板，引擎还将导出任何自定义列格式或列表视图格式，并将其存储在用于视图的列或元素的 CustomFormatter 属性中。因此，可以使用一堆 PowerShell 脚本自定义列和列表视图、导出自定义项，并将其应用回生产和/或客户的网站。

注意

如果不知道什么是 PnP 预配引擎，或者想要深入了解它是什么，可以阅读了解项目的新式预配一文。

例如，在这里可以看到使用 PnP PowerShell 从 “旅行请求” 中提取模板的语法，包括列和列表视图格式设置模板。

Connect-PnPOnline https://<source-tenant-name>.sharepoint.com/sites/<SourceSite>
Get-PnPSiteTemplate -Out .\travel-requests.xml -ListsToExtract "Travel requests" -Handlers Lists

在以下代码摘录中，可以看到如何将刚刚提取的模板应用到目标站点。

Connect-PnPOnline https://<target-tenant-name>.sharepoint.com/sites/<TargetSite>
Invoke-PnPSiteTemplate -Path .\travel-requests.xml

请注意，模板的提取和应用甚至可以跨不同的 Microosft 365 租户进行。

建议的内容

有关本主题的其他信息，请参阅以下文档：

通过