列表布局自定义

项目
04/08/2023

在行上应用条件类

你可以使用 additionalRowClass 将一个或多个类应用于整个列表视图行，具体要取决于行中一个或多个字段的值。这些示例将不改变列表视图行的内容和结构。

有关在视图格式内部使用的建议类的列表，请参阅使用列格式化自定义 SharePoint 中的样式准则。

提示

使用 additionalRowClass 属性将类应用到列表视图行不会改变各个列的格式。这样，即可结合使用视图格式和列格式，以实现一些功能强大的可视化效果。

示例：根据日期字段应用条件类

下图显示了根据日期列的值应用类的列表视图：

使用条件格式进行视图格式化的 SharePoint 列表视图

当项目的 DueDate 早于当前日期/时间时，此示例会将类 sp-field-severity--severeWarning 应用到列表视图行：

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "additionalRowClass": "=if([$DueDate] <= @now, 'sp-field-severity--severeWarning', '')"
}

示例：根据文本或选项字段中的值应用条件类

已从列格式化示例（根据文本或选项字段中的值应用条件格式化）中采用此示例，将此概念应用到列表视图行时有一些重要区别。列格式化示例会根据 @currentField 的值将图标和类同时应用到列。但是，视图格式化中的 additionalRowClass 属性只能用于指定类，而不是图标。此外，由于 @currentField 在视图格式内部引用时始终解析为 Title 字段的值，因此，本示例会直接引用 Status 字段（方法是通过使用 additionalRowClass 属性中的 [$Field] 语法来确定要应用到行的类）。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "additionalRowClass": "=if([$Status] == 'Done', 'sp-field-severity--good', if([$Status] == 'In progress', 'sp-field-severity--low' ,if([$Status] == 'In review','sp-field-severity--warning', if([$Status] == 'Has issues','sp-field-severity--blocked', ''))))"
}

你可以在此处找到该示例及其他详细信息：根据选项字段应用条件格式

示例：基于模数的备用行格式设置

此示例将 % (Mod) 应用于列表视图行，使用备用着色行：

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "additionalRowClass": "=if(@rowIndex%2==0,'ms-bgColor-themeLight','')"
}

构建自定义列表行

你可以使用 rowFormatter，通过在列格式化中使用的相同语法来定义行内字段值的完全自定义布局。

示例：多行视图样式

下图显示了应用自定义多行视图样式的列表：

具有多行视图自定义的 SharePoint 列表

此示例使用 rowFormatter 元素，可完全替代列表视图行的呈现。此示例中的 rowFormatter 将创建每个列表视图行的边界 <div /> 框。在此边界框内，$Title 和 $Feedback 字段显示在不同行中。在这些字段下，将显示 button 元素，单击后所执行的操作与单击未自定义视图中的列表行（该操作将打开项目的属性窗体）相同。当 $Assigned_x0020_To 字段（假定为个人/组字段）的值与当前已登录用户匹配时，将根据条件显示此 button：

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
  "hideSelection": true,
  "hideColumnHeader": true,
  "rowFormatter": {
    "elmType": "div",
    "attributes": {
      "class": "sp-row-card"
    },
    "children": [
      {
        "elmType": "div",
        "style": {
          "text-align": "left"
        },
        "children": [
          {
            "elmType": "div",
            "attributes": {
              "class": "sp-row-title"
            },
            "txtContent": "[$Title]"
          },
          {
            "elmType": "div",
            "attributes": {
              "class": "sp-row-listPadding"
            },
            "txtContent": "[$Feedback]"
          },
          {
            "elmType": "button",
            "customRowAction": {
              "action": "defaultClick"
            },
            "txtContent": "Give feedback",
            "attributes": {
              "class": "sp-row-button"
            },
            "style": {
              "display": {
                "operator": "?",
                "operands": [
                  {
                    "operator": "==",
                    "operands": [
                      "@me",
                      "[$Assigned_x0020_To.email]"
                    ]
                  },
                  "",
                  "none"
                ]
              }
            }
          }
        ]
      }
    ]
  }
}

你可以在此处找到该示例及其他详细信息：多行视图呈现

构建自定义组头和组尾

可以使用 groupProps 来格式化组头，灵活地添加分组列的数据、显示名称和项目计数。还可在组头中添加组聚合，或直接在组脚中将其格式化。

示例: 彩色编码的组头

在下面的例子中，我们根据列元数据列出了格式化的组头。

按城市分组带有格式化组头的员工名单

在下面的示例中，groupProps 的 headerFormatter 用于格式化组头，@group 用于访问组信息。

注意

下面的 JSON 包含换行符。已添加这些代码以提高代码的可读性。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
  "groupProps": {
    "headerFormatter": {
      "elmType": "div",
      "style": {
        "flex-wrap": "wrap",
        "display": "flex",
        "box-sizing": "border-box",
        "padding": "4px 8px 5px 8px",
        "border-radius": "6px",
        "align-items": "center",
        "white-space": "nowrap",
        "overflow": "hidden",
        "margin": "1px 4px 4px 1px"
      },
      "attributes": {
        "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
                   if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
                   if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
                   if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
                   if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50',
                   'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary')))))"
      },
      "children": [
        {
          "elmType": "img",
          "attributes": {
            "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
                     if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
                     if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
                     if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
                     if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
          },
          "style": {
            "max-width": "24px",
            "max-height": "24px",
            "margin-top": "2px",
            "border-radius": "2px"
          }
        },
        {
          "elmType": "div",
          "children": [
            {
              "elmType": "span",
              "style": {
                "padding": "5px 5px 5px 5px",
                "font-weight": "500"
              },
              "txtContent": "@group.fieldData.displayValue"
            }
          ]
        },
        {
          "elmType": "div",
          "children": [
            {
              "elmType": "div",
              "style": {
                "display": "flex",
                "flex-direction": "row",
                "justify-content": "center"
              },
              "children": [
                {
                  "elmType": "div",
                  "txtContent": "='has ' + @group.count + if(@group.count > '1', ' employees', ' employee')",
                  "style": {
                    "font-weight": "500"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

示例：带聚合的颜色编码组头

在下面的例子中，我们列出了有带组聚合格式化的组头。

按城市分组的带有格式化组头和聚合摘要的员工名单

此示例中 groupProps 的 hideFooter 设置为 true- 以隐藏组尾，@aggregates 数组用于在组头中显示摘要。

注意

下面的 JSON 包含换行符。已添加这些代码以提高代码的可读性。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
  "groupProps": {
    "hideFooter": true,
    "headerFormatter": {
      "elmType": "div",
      "style": {
        "flex-wrap": "wrap",
        "display": "flex",
        "box-sizing": "border-box",
        "padding": "4px 8px 5px 8px",
        "border-radius": "6px",
        "align-items": "center",
        "white-space": "nowrap",
        "overflow": "hidden",
        "margin": "1px 4px 4px 1px"
      },
      "attributes": {
        "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
                   if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
                   if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
                   if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
                   if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50',
                   'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary')))))"
      },
      "children": [
        {
          "elmType": "img",
          "attributes": {
            "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
                     if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
                     if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
                     if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
                     if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
          },
          "style": {
            "max-width": "24px",
            "max-height": "24px",
            "margin-top": "2px",
            "border-radius": "2px"
          }
        },
        {
          "elmType": "div",
          "children": [
            {
              "elmType": "span",
              "style": {
                "padding": "5px 5px 5px 5px",
                "font-weight": "500"
              },
              "txtContent": "@group.fieldData.displayValue"
            }
          ]
        },
        {
          "elmType": "div",
          "forEach": "aggregate in @aggregates",
          "children": [
            {
              "elmType": "div",
              "style": {
                "display": "=if([$aggregate.columnDisplayName] == 'Approved' && Number([$aggregate.value]) < @group.count, 'flex', 'none')",
                "flex-direction": "row",
                "justify-content": "center"
              },
              "children": [
                {
                  "elmType": "div",
                  "txtContent": "='has approval pending for ' + Number(@group.count - Number([$aggregate.value])) + if(@group.count - Number([$aggregate.value]) > 1 , ' employees', ' employee')",
                  "style": {
                    "font-weight": "500"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

示例: 自定义组尾

在下面的例子中，我们根据聚合值列出了格式化的组尾。

按城市分组带有格式化组尾的员工名单

在示例中，groupProps 的 footerFormatter 用于格式化组尾，@columnAggregate 用于访问列聚合。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
  "groupProps": {
    "hideFooter": false,
    "footerFormatter": {
      "elmType": "div",
      "children": [
        {
          "elmType": "div",
          "attributes": {
            "iconName": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, 'SortDown', 'SortUp')"
          },
          "style": {
            "color": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, '#d13438', '#107c10')",
            "font-weight": "600",
            "margin-top": "10px"
          }
        },
        {
          "elmType": "div",
          "style": {
            "color": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, '#d13438', '#107c10')",
            "font-weight": "600",
            "margin-top": "10px",
            "font-family": "Segoe UI"
          },
          "txtContent": "=@columnAggregate.type + ': ' + @columnAggregate.value"
        }
      ]
    }
  }
}

构建自定义列表页脚

可使用 footerFormatter 来格式化设具有访问列聚合权限的列表页脚。

示例: 自定义列表页脚

在下面的示例中，我们根据聚合值列出了格式化的页脚。

按城市分组带有格式化列表页脚的员工名单

此示例中， footerFormatter 设置为格式化列表页脚，而 @columnAggregate 用于访问列聚合。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
  "hideFooter": false,
  "footerFormatter": {
    "elmType": "div",
    "attributes": {
      "class": "ms-fontColor-themePrimary"
    },
    "customCardProps": {
      "formatter": {
        "elmType": "div",
        "children": [
          {
            "elmType": "div",
            "style": {
              "display": "flex"
            },
            "txtContent": "=@columnAggregate.type + ' of ' + @columnAggregate.columnDisplayName + ' is ' + @columnAggregate.value"
          }
        ],
        "style": {
          "height": "10px",
          "width": "auto",
          "cursor": "pointer",
          "font-size": "14px",
          "padding": "14px"
        }
      },
      "openOnEvent": "hover",
      "directionalHint": "bottomCenter",
      "isBeakVisible": true,
      "beakStyle": {
        "backgroundColor": "white"
      }
    },
    "txtContent": "View details",
    "style": {
      "text-decoration": "none",
      "cursor": "pointer",
      "font-size": "16px",
      "margin-top": "10px"
    }
  }
}

详细语法参考

rowFormatter

可选元素。指定用于描述列表视图行格式的 JSON 对象。此 JSON 对象的架构与列格式的架构相同。有关此架构及其功能的详细信息，请参阅格式设置语法参考。

注意

使用 rowFormatter 属性将替代 additionalRowClass 属性中指定的任何内容。它们相互排斥。

rowFormatter 元素与列格式化之间的行为差异

尽管共享同一架构，但 rowFormatter 元素内的各个元素与列格式化对象中的相同元素之间存在一些行为差异。

@currentField 始终解析为 rowFormatter 内的 Title 字段的值。

additionalRowClass

可选元素。指定应用到整行的 CSS 类。支持表达式。

仅当未指定 rowFormatter 元素时，additionalRowClass 才会生效。如果已指定 rowFormatter，则会忽略 additionalRowClass。

hideSelection

可选元素。指定是否禁用在视图中选择行的功能。 false 是列表视图内的默认行为（这意味着所选内容可见且已启用）。 true 意味着用户将无法选择列表项。

hideColumnHeader

可选元素。指定是否隐藏视图中的列标题。 false 是列表视图内的默认行为（这意味着列标题可见）。 true 意味着该视图不显示列标题。

groupProps

对组相关的自定义选项进行分组。有关 groupProps 的详细信息，请参阅组自定义语法参考

commandBarProps

对命令栏自定义选项进行分组。有关 commandBarProps的详细信息，请参阅命令栏自定义语法参考