SharePoint使用列格式化自定义-json实现

 列格式化可用于自定义字段在 SharePoint 列表和库中的显示方式。 为此，需要构造 JSON 对象，用于描述列表视图字段中显示的元素，以及要应用于这些元素的样式。 列格式化不会更改列表项或文件中的数据，只会更改如何向浏览列表的用户显示数据。 只要可以创建和管理列表视图，就能使用列格式化配置视图字段的显示方式。
 
复制代码

列格式化与字段自定义工具有何不同？

列格式化和 SharePoint 框架字段自定义工具扩展均可自定义字段在 SharePoint 列表中的显示方式。字段自定义工具更加强大，因为可用来编写你想要控制字段显示方式的任何代码。

列格式设置更易于广泛应用。但是，它不太灵活，因为它不允许自定义代码，而只允许某些预定义的元素和属性。

下表比较了列格式化和字段自定义工具。

字段类型	列格式化	字段自定义工具
根据项值和值范围应用条件格式	支持	支持
操作链接	支持不启动脚本的静态超链接	支持任何超链接，包括调用自定义脚本的超链接
数据可视化	支持可使用 HTML 和 CSS 表达的简单可视化	支持任意数据可视化

如果可以使用列格式化完成方案，这通常就会比使用字段自定义工具更快捷。只要可以创建和管理列表视图，就能使用列格式化创建和发布自定义。字段自定义工具可用于处理列格式化不支持的更高级方案。

字段自定义格式化参见:juejin.cn/post/702910…

列格式化入门

若要打开列格式化窗格，请打开列下的下拉菜单。在“列设置”下，选择“设置此列的格式”。然后选择高级模式.

显示字段值（基本）

最简单的列格式化是将字段值放置在 <div /> 元素内。下面的示例适用于数字、文本、选项和日期字段：

JSON 是不支持注释的,只是标记一下
{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   //这行代表显示输入的内容值
   "txtContent": "@currentField"
}
复制代码

一些字段类型需要进行额外一些处理，才能检索它们的值。人员字段在系统中表示为对象，并且人员的显示名称包含在此对象的 title 属性中。下面在上一示例的基础上进行了修改，以便适用于人员字段：

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField.title"
}
复制代码

查阅字段也表示为对象，显示文本存储在 lookupValue 属性中。此示例适用于查阅字段：

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField.lookupValue"
}
复制代码

应用条件格式

列格式化可用于根据字段值将样式、类和图标应用于字段。

根据数字范围应用条件格式（基本）

下图中的示例展示了应用于数字范围的条件格式。

在本示例中，如果当前字段中的值小于或等于 70，将使用 Excel 样式的条件表达式 (=if) 将类 (sp-field-severity--warning) 应用于父级 <div /> 元素。这样一来，如果值不大于 70，字段就会突出显示；如果值大于 70，字段就会正常显示。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    //这是设置大的单元格的格式
  "elmType": "div",
  "attributes": {
    "class": "=if(@currentField <= 70,'sp-field-severity--warning', '')"
  },
    //这是设置子单元格格式
  "children": [
    {
      "elmType": "span",
      "style": {
        "display": "inline-block",
        "padding": "0 4px"
      },
      "attributes": {
        "iconName": "=if(@currentField <= 70,'Error', '')"
      }
    },
    {
      "elmType": "span",
      "txtContent": "@currentField"
    }
  ]
}
复制代码

根据文本或选项字段值应用条件格式（高级)

可以将条件格式应用于可能包含一组固定值的文本或选项字段。下面的示例根据字段值是“已完成”、“审核中”、“有问题”还是其他值，应用不同的类。此示例根据字段值将 CSS 类 (sp-field-severity--low, sp-field-severity--good, sp-field-severity--warning, sp-field-severity--severeWarning, sp-field-severity--blocked) 应用于 <div />。然后它会输出具有 IconName 属性的 <span /> 元素。此属性会自动将另一个 CSS 类应用到该 <span /> ，该元素内会显示 Fluent UI 图标。最后，另一个 <span /> 元素是包含字段内的值的输出。

若要将不同的值映射到各种紧急性或严重性分级，此模式将非常有用。可以从此示例入手，将它编辑为指定自己的字段值，以及应映射到这些值的样式和图标。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "attributes": {
    "class": "=if(@currentField == 'Done', 'sp-field-severity--good', if(@currentField == 'In progress', 'sp-field-severity--low', if(@currentField == 'In review', 'sp-field-severity--warning', if(@currentField == 'Has issues', 'sp-field-severity--severeWarning', 'sp-field-severity--blocked')))) + ' ms-fontColor-neutralSecondary'"
  },
  "children": [
    {
      "elmType": "span",
      "style": {
        "display": "inline-block",
        "padding": "0 4px"
      },
      "attributes": {
        "iconName": "=if(@currentField == 'Done', 'CheckMark', if(@currentField == 'In progress', 'Forward', if(@currentField == 'In review', 'Error', if(@currentField == 'Has issues', 'Warning', 'ErrorBadge'))))"
      }
    },
    {
      "elmType": "span",
      "txtContent": "@currentField"
    }
  ]
}
复制代码

根据日期范围应用格式

由于日期通常用于跟踪截止时间和关键项目日程表，因此常见方案是根据日期/时间字段值应用格式。若要根据日期/时间字段值应用格式，请应用以下模式。

此示例将当前字段设置为，在项的“截止日期”值早于当前日期/时间时用红色显示。与上面的一些示例不同，此示例需要查阅另一个字段值，才能将格式应用于一个字段。请注意，“DueDate”是使用 [$FieldName] 语法进行引用。 FieldName 假定为字段的内部名称。此示例还利用了一个可用于日期/时间字段的特殊值，即 @now。此值在用户加载列表视图时计算并解析为当前日期/时间。

字段名称中的空格（若有）定义为 _x0020_。例如，应将“Due Date”字段引用为 $Due_x0020_Date。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "debugMode": true,
  "txtContent": "@currentField",
  "style": {
    "color": "=if([$DueDate] <= @now, '#ff0000', '')"
  }
}
复制代码

根据任意日期设置项格式（高级）

若要比较日期/时间字段值与非 @now 日期，请应用下面示例中的模式。下面的示例将当前字段设置为，在截止日期不晚于明天时用红色显示。为此，需要对日期执行数学运算。可以将毫秒添加到任何日期中，生成一个新日期。例如，若要将一天添加到某个日期中，可以添加 (246060*1000 = 86,400,000)。

本示例在抽象语法树内使用三元 (?) 运算符，演示用于表达条件表达式的替代语法。

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "<=",
               "operands": [
                  "[$DueDate]",
                  {
                     "operator": "+",
                     "operands": [
                        "@now",
                        86400000
                     ]
                  }
               ]
            },
            "#ff0000",
            ""
         ]
      }
   }
}
复制代码

下面是使用 Excel 样式表达式语法的上述相同示例：

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": "=if([$DueDate] <= @now + 86400000, '#ff0000', '')"
   }
}
复制代码

若要比较日期/时间字段值与另一个日期常量，请使用 Date() 方法将字符串转换为日期。下面的示例将当前字段设置为，在“DueDate”字段值早于 2017 年 3 月 22 日时用红色显示。

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": {
         "operator": "?",
         "operands": [
            {
               "operator": "<=",
               "operands": [
                  "[$DueDate]",
                  {
                     "operator": "Date()",
                     "operands": [
                        "3/22/2017"
                     ]
                  }
               ]
            },
            "#ff0000",
            ""
         ]
      }
   }
}
复制代码

下面是使用 Excel 样式表达式语法的上述相同示例：

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "div",
   "txtContent": "@currentField",
   "style": {
      "color": "=if([$DueDate] <= Date('3/22/2017'), '#ff0000', '')"
   }
}
复制代码

将字段值转换为超链接（基本）

下面的示例展示了如何将包含股票代码符号的文本字段转换为超链接，从而转到相应股票代码在 Yahoo Finance 上的实时报价页面。该示例使用可将当前字段值追加到静态超链接 finance.yahoo.com/quote/ 的 + 运算符。可以扩展此模式，将它用于任何方案。例如，让用户查看与某项相关的上下文信息，或对当前项启动业务流程，只要这些信息或流程可通过使用列表项值进行参数化的超链接进行访问即可。

{
   "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
   "elmType": "a",
   "txtContent": "@currentField",
   "attributes": {
      "target": "_blank",
      "href": "='http://finance.yahoo.com/quote/' + @currentField"
   }
}
复制代码

提示

在列表 Web 部件中，上面的定位标记将用户导航到新选项卡。若要在同一选项卡中导航，请添加 data-interception 属性并将其设置为 on。有关数据拦截的详细信息。

向字段添加动作按钮（高级）

下图展示了向字段添加的动作按钮。

列格式化可用于在字段旁边呈现快速操作链接。下面的示例适用于人员字段，可以在父元素 <div /> 内呈现下列两个元素：

包含人员显示名称的 <span /> 元素。
打开 mailto: 链接的 <a /> 元素，用于创建主题和正文已通过项元数据进行动态填充的电子邮件。该 <a /> 元素使用 ms-Icon、 ms-Icon—Mail和 ms-QuickAction Fluent UI 课堂进行样式设置，使其看起来像可单击的电子邮件图标。

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    "elmType": "div",
    "children": [
        {
            "elmType": "span",
            "style": {
                "padding-right": "8px"
            },
            "txtContent": "@currentField.title"
        },
        {
            "elmType": "a",
            "attributes": {
                "iconName": "Mail",
                "style": {
                    "text-decoration": "none"
                },
                "class": "sp-field-quickActions",
                "href": {
                    "operator": "+",
                    "operands": [
                        "mailto:",
                        "@currentField.email",
                        "?subject=Task status&body=Hey, how is your task coming along?.\r\n---\r\n",
                        "@currentField.title",
                        "\r\nClick this link for more info. http://contoso.sharepoint.com/sites/ConferencePrep/Tasks/Prep/DispForm.aspx?ID=",
                        "[$ID]"
                    ]
                }
            }
        }
    ]
}
复制代码

显示上升/下降趋势图标（高级）

下图展示了已添加上升/下降趋势图标的列表：

此示例依赖两个数字字段 Before 和 After，可以比较它们的值。它会在 After 字段旁边显示相应的趋势图标，具体视与 Before 值进行比较的字段值而定。如果 After 值更高，则使用 sp-field-trending--up；如果 After 值更低，则使用 sp-field-trending--down。

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    "elmType": "div",
    "children": [
        {
            "elmType": "span",
            "attributes": {
                "class": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": ">",
                            "operands": [
                                "[$After]",
                                "[$Before]"
                            ]
                        },
                        "sp-field-trending--up",
                        "sp-field-trending--down"
                    ]
                },
                "iconName": {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": ">",
                            "operands": [
                                "[$After]",
                                "[$Before]"
                            ]
                        },
                        "SortUp",
                        {
                            "operator": "?",
                            "operands": [
                                {
                                    "operator": "<",
                                    "operands": [
                                        "[$After]",
                                        "[$Before]"
                                    ]
                                },
                                "SortDown",
                                ""
                            ]
                        }
                    ]
                }
            }
        },
        {
            "elmType": "span",
            "txtContent": "[$After]"
        }
    ]
}
复制代码

设置多值字段的格式

可通过列格式将样式应用于 Person、Lookup 和 Choice 类型的多值字段的每个成员。

基本文本格式设置

下图展示了一个应用于 Person 字段的多值字段格式的示例。

此示例使用 length 运算符来检测字段的成员数，使用 join 运算符来串联所有成员的电子邮件地址。此示例在未找到成员时隐藏按钮，并处理文本中的复数形式。

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    "elmType": "a",
    "style": {
        "display": "=if(length(@currentField) > 0, 'flex', 'none')"
    },
    "attributes": {
        "href": {
            "operator": "+",
            "operands": [
                "mailto:",
                "=join(@currentField.email, ';')"
            ]
        }
    },
    "children": [
        {
            "elmType": "span",
            "style": {
                "display": "inline-block",
                "padding": "0 4px"
            },
            "attributes": {
                "iconName": "Mail"
            }
        },
        {
            "elmType": "span",
            "txtContent": {
                "operator": "+",
                "operands": [
                    "Send email to ",
                    {
                        "operator": "?",
                        "operands": [
                            "=length(@currentField) == 1",
                            "@currentField.title",
                            "='all ' + length(@currentField) + ' members'"
                        ]
                    }
                ]
            }
        }
    ]
}
复制代码

简单 HTML 元素格式设置

下图展示了一个基于多值 Lookup 字段的值构造简单句子的示例。

此示例使用 loopIndex 和 length 运算符来确定字段的最后一名成员，使用 forEach 属性来复制 HTML 元素。

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
    "elmType": "div",
    "style": {
        "display": "block"
    },
    "children": [
        {
            "elmType": "span",
            "forEach": "region in @currentField",
            "txtContent": {
               "operator": "?",
               "operands": [
                  "=loopIndex('region') == 0",
                  "[$region.lookupValue]",
                  {
                     "operator": "?",
                     "operands": [
                        "=loopIndex('region') + 1 == length(@currentField)",
                        "=', and ' + [$region.lookupValue]",
                        "=', ' + [$region.lookupValue]"
                     ]
                  }
               ]
            }
        }
    ]
}
复制代码

使用列格式化的最简单方法是，从示例入手，再将它编辑为应用到特定字段。可以复制、粘贴和编辑下面各部分中的示例，将它们用于自己的方案。 SharePoint/sp-dev-column-formatting 存储库中也提供了几个示例。