格式设置语法参考

项目
11/19/2024

elmType

指定要创建的元素类型。有效元素包括：

div
span
a
img
svg
path
button
p
filepreview

其他任何值都会导致错误生成。

filepreview

使用属性elmTypefilepreviewsrc设置为 @thumbnail.<Size> 的特殊，以查看文档库中文件的缩略图。

如果缩略图加载成功，则左下角会显示一个小的品牌类型图标。如果缩略图无法加载 (或文件类型不支持缩略图) ，则会改为显示文件类型图标。

"elmType": "filepreview",
"attributes": {
  "src": "@thumbnail.medium"
}

img src 安全性

允许来自以下域的图像：

租户域、配置的多地理位置域和虚域 (company.sharepoint.com)
cdn.office.net、 akamaihd.net、 static2.sharepointonline.com CDN

默认情况下，自定义格式化程序中会阻止大多数其他外部图像源。若要包含外部映像并允许特定域或 CDN，需要将域添加到站点级别设置。有关详细信息，请参阅：允许或限制在 SharePoint 页面上嵌入内容的功能

txtContent

可选属性，用于指定 elmType 指定元素的文本内容。此属性的值可以是字符串（包括特殊字符串），也可以是表达式对象。

style

可选属性，用于指定要应用到 elmType 指定元素的样式属性。此对象包含与 CSS 名称和值对应的名称/值对。样式对象中每个属性的值可以是字符串（包括特殊字符串），也可以是表达式对象。可应用下列样式属性。

'background-color'
'fill'
'background-image'
'border'
'border-bottom'
'border-bottom-color'
'border-bottom-style'
'border-bottom-width'
'border-color'
'border-left'
'border-left-color'
'border-left-style'
'border-left-width'
'border-right'
'border-right-color'
'border-right-style'
'border-right-width'
'border-style'
'border-top'
'border-top-color'
'border-top-style'
'border-top-width'
'border-width'
'outline'
'outline-color'
'outline-style'
'outline-width'
'border-bottom-left-radius'
'border-bottom-right-radius'
'border-radius'
'border-top-left-radius'
'border-top-right-radius'
'box-decoration-break'
'box-shadow'
'box-sizing'

'overflow-x'
'overflow-y'
'overflow-style'
'rotation'
'rotation-point'

'opacity'
'cursor'

'height'
'max-height'
'max-width'
'min-height'
'min-width'
'width'

'flex-grow'
'flex-shrink'
'flex-flow'
'flex-direction'
'flex-wrap'
'flex'
'justify-content'
'align-items'

'box-align'
'box-direction'
'box-flex'
'box-flex-group'
'box-lines'
'box-ordinal-group'
'box-orient'
'box-pack'

'font'
'font-family'
'font-size'
'font-style'
'font-variant'
'font-weight'
'font-size-adjust'
'font-stretch'

'grid-columns'
'grid-rows'

'margin'
'margin-bottom'
'margin-left'
'margin-right'
'margin-top'

'column-count'
'column-fill'
'column-gap'
'column-rule'
'column-rule-color'
'column-rule-style'
'column-rule-width'
'column-span'
'column-width'
'columns'

'padding'
'padding-bottom'
'padding-left'
'padding-right'
'padding-top'

'bottom'
'clear'
'clip'
'display'
'float'
'left'
'overflow'
'position'
'right'
'top'
'visibility'
'z-index'

'border-collapse'
'border-spacing'
'caption-side'
'empty-cells'
'table-layout'

'color'
'direction'
'letter-spacing'
'line-height'
'text-align'
'text-decoration'
'text-indent'
'text-transform'
'unicode-bidi'
'vertical-align'
'white-space'
'word-spacing'
'hanging-punctuation'
'punctuation-trim'
'text-align-last'
'text-justify'
'text-outline'
'text-overflow'
'text-shadow'
'text-wrap'
'word-break'
'word-wrap'

'stroke'
'fill-opacity'

'--inline-editor-border-width'
'--inline-editor-border-style'
'--inline-editor-border-radius'
'--inline-editor-border-color'

'-webkit-line-clamp'

'object-fit'
'transform' // Only translate(arg) and translate(arg, arg) are currently supported

下面的示例展示了样式对象值。此示例应用两个样式属性（padding 和 background-color）。 padding 值是硬编码的字符串值。 background-color 值是计算结果为红色 (#ff0000) 或绿色 (#00ff00) 的表达式，具体视当前字段值（由 @currentField 指定）是否小于 40 而定。有关详细信息，请参阅 Expression 对象部分。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "style": {
    "padding": "4px",
    "background-color": {
      "operator": "?",
      "operands": [
        {
          "operator": "<",
          "operands": [
            "@currentField",
            40
          ]
        },
        "#ff0000",
        "#00ff00"
      ]
    }
  }
}

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "style": {
  "padding": "4px",
  "background-color": "=if(@currentField < 40, '#ff0000', '#00ff00')"
  }
}

attributes

attributes可选属性指定要添加到由 elmType指定的元素的更多属性。此对象包含名称/值对。属性名必须为下列值之一：

href
rel
src
class
target
title
role
iconName
d
aria
data-interception
viewBox
preserveAspectRatio
可拖动

其他任何属性名都会导致错误生成。属性值可以是表达式对象，也可以是字符串。下面的示例将两个属性（target 和 href）添加到 elmType 指定元素中。 target 属性被硬编码为字符串。 href 属性是要在运行时计算为 http://finance.yahoo.com/quote/ + 当前字段值 (@currentField) 的表达式。

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

children

children可选属性指定由 elmType指定的元素的子元素。值按一组 elm 对象的形式进行指定。可以进行任意级别的嵌套。如果元素包含 txtContent 属性，将忽略子属性。

debugMode

debugMode可选属性用于调试。它输出错误消息，并在控制台中记录警告。

forEach

可选 forEach 属性允许元素为特定多值字段或数组的每个成员复制自身。属性的值 "forEach" 的格式应为 "iteratorName in @currentField" 或 "iteratorName in [$FieldName]""iteratorName in Expression-Returning-An-Array"。

iteratorName 表示用于表示多值字段的当前成员的迭代器变量的名称。迭代器的名称可以是字母数字字符和下划线的任意组合， _ (不以数字开头的) 。

循环中使用的字段必须位于启用了多值选项的受支持字段类型中：Person、Lookup 和 Choice。还可以使用返回数组的表达式。

在具有 forEach 或其子元素的元素中，迭代器变量可以称为，就像它是一个新字段一样。可使用 loopIndex 运算符访问迭代器的索引。

forEach 无法应用于根元素，如果字段中没有值，则不呈现任何元素。

有关示例，请参阅设置多值字段的格式。

customRowAction

button 元素可以用于启动父项上的特定操作。每个元素都有 button 一个必需的属性，该属性 customRowAction指定 action 在选择按钮时采用的。此操作必须为以下值之一：

defaultClick：使用此操作的按钮将执行与单击未自定义视图中的列表项相同的操作。以下示例演示了一个按钮，该按钮在选中时模拟对项的选择，从而打开列表项。将此示例按钮添加到文档库会模拟文件或文件夹上的选择，这会导致打开文件或文件夹。
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "button",
  "txtContent": "Open this item",
  "customRowAction": {
    "action": "defaultClick"
  }
}
```

共享：选择按钮将打开共享对话框。下面是此类按钮的示例：

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "button",
  "txtContent": "Share this item",
  "customRowAction": {
    "action": "share"
  }
}

delete：选择按钮将打开删除确认对话框。
editProps：选择按钮将在编辑模式下打开项属性页。
openContextMenu：选择按钮将打开项目的默认上下文菜单。

setValue：选择元素将使用提供的字段值更新项。

{
  "elmType": "div",
  "txtContent": "[$FieldName]",
  "customRowAction":{
    "action": "setValue",
    "actionInput": {
      "FieldInternalName_1": "FieldValue_1",
      "FieldInternalName_2": "FieldValue_2",
    }
  }
}

executeFlow：选择按钮将启动由属性中的 actionParams ID 指定的指定 Flow。有关此按钮的示例，请参阅创建按钮以启动 Flow。以下示例演示这种类型的按钮：
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
  "elmType": "button",
  "txtContent": "It's Flow Time!",
  "customRowAction": {
    "action": "executeFlow",
    "actionParams": "{\"id\":\"f7ecec0b-15c5-419f-8211-302a5d4e94f1\", \"headerText\":\"It's Flow Time!\",\"runFlowButtonText\":\"Do it\"}"
  }
}
```
使用 executeFlow 操作时，actionParams 属性可具有以下选项：
- id：要启动的流的 ID（必需）
- headerText：设置流面板顶部的文本（可选）
- runFlowButtonText：设置流面板中主按钮的文本（可选）
embed：单击该按钮将打开一个标注，其中嵌入了内容。内容将由中的 actionInput属性中src提供的 URL 确定。还可以使用 actionInput控制height标注的和 width 。
注意
- src需要只是url应用生成的可嵌入代码的一部分， (通常在元素) 的 iframe 属性中找到src。
- 此操作仅在较新版本的 Microsoft Lists 应用中可用。
有关允许或限制域的详细信息，请参阅允许或限制使用自定义格式化程序在 SharePoint Lists上嵌入内容的功能。
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "button",
  "customRowAction": {
    "action": "embed",
    "actionInput": {
      "src": "https://www.relecloud.com/embed/ll00hWQMJxQ",
      "height": "350",
      "width": "700"
    }
  },
  "txtContent": "Click here to open recipe video 👩‍🍳"
}
```
使用 embed 操作时，actionInput 属性可具有以下选项：
- src：要嵌入的内容的 URL。 需要 ()
- height：嵌入内容将在其中呈现的标注的高度。默认值为 300。 (可选)
- width：嵌入内容将在其中呈现的标注的宽度。默认值为 300。 (可选)

customCardProps

将自定义卡添加到元素，该元素显示在悬停或click事件上。可以选择下列自定义：

"formatter"：定义自定义卡片格式的 JSON 对象。
"openOnEvent"：应在其发生时打开自定义卡片的事件。
- 有效值： click、 hover
"directionalHint"：指定相对于自定义卡定位的目标的方向。这是首选位置，但不能保证具体取决于空间。
- 有效值：bottomAutoEdge、、bottomCenter、bottomLeftEdge、leftBottomEdgebottomRightEdge、leftCenterleftTopEdgerightBottomEdge、rightCenter、rightTopEdge、、topAutoEdge、、topCenter、、 topLeftEdgetopRightEdge
"isBeakVisible"：指定是否显示尖角。
"beakStyle"：指定自定义卡嘴的样式对象。

defaultHoverField

为文档库中的文件添加人员字段的配置文件卡或文件悬停卡。

"defaultHoverField": "[$Editor]" 为编辑者字段添加个人资料卡片
"defaultHoverField": "[$FileLeafRef]" 在文档库中添加文件悬停卡

columnFormatterReference

这将替换为所引用列的格式设置程序 JSON。不支持多级引用。

不支持引用多选项列格式化程序模板和不基于模板的列格式化程序。

{
  "columnFormatterReference": "[$FieldName]"
}

inlineEditField

为引用列添加字段编辑器。

{
  "elmType": "div",
  "inlineEditField": "[$FieldName]",
  "txtContent": "[$FieldName]"
}

filePreviewProps

filePreviewProps是一个可选属性，它允许替代 .elmType 中filepreview文件类型图标和品牌类型图标的默认样式。

fileTypeIconClass和 brandTypeIconClass 可用于分别向文件类型图标和品牌类型图标元素提供 CSS 类名称。

fileTypeIconStyle和 brandTypeIconStyle 可用于分别为文件类型图标和品牌类型图标提供样式。这些样式优先于上述两个属性提供的 CSS 类中的相同样式。

"elmType": "filepreview",
"attributes": {
  "src": "@thumbnail.medium",
 },
"filePreviewProps": {
  "fileTypeIconClass": "sp-css-borderColor-neutralLight",
  "fileTypeIconStyle": {
    "width": "100px"
  },
  "brandTypeIconClass": "sp-css-borderColor-neutralLight",
  "brandTypeIconStyle": {
    "width": "68px"
  }
}

表达式

txtContent、样式属性和属性的值可以表示为表达式，以便在运行时根据当前字段 (或行) 的上下文对其进行计算。表达式对象可以进行嵌套，从而包含其他表达式对象。

可以从 22H2 功能更新开始，使用 SharePoint Online 中的 Excel 样式表达式和SharePoint Server 订阅版编写表达式，也可以在 SharePoint Online、SharePoint Server 订阅版和 SharePoint Server 2019中使用抽象语法树表达式来编写表达式。

中的所有 ViewFields 字段都可以在表达式中引用，即使标记为 Explicit。

Excel 样式的表达式

所有 Excel 样式的表达式都以等号 (=) 开头。此表达式样式仅在 SharePoint Online 中可用，SharePoint Server 订阅版从 22H2 功能更新开始。在 22H2 功能更新之前，SharePoint Server 2019或SharePoint Server 订阅版中不提供此表达式样式。

如果不等于 [$Author.email]，则此简单条件表达式的计算结果none为，否则计算结果为''：@me

=if(@me != [$Author.email], 'none', '')

可以编写更复杂的 if/else 语句，如下所示：

=if([$Sentiment] <= 0.3, 'sp-field-severity--blocked', if([$Sentiment] < 0.9,'sp-field-severity--warning','sp-field-severity--good'))

可以编写采用一个或两个操作数的非条件运算符，如下所示：

=[$foo] * -7

=sin(@currentField)

=toString(60 + (sin(6.2831853 * @currentField) * 60))

抽象语法树表达式

以下示例包含一个执行表达式的 Expression 对象：

(@currentField > 40) ? '100%' : (((@currentField * 2.5).toString() + '%')

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "operator": "?",
  "operands": [
    {
      "operator": ">",
      "operands": [
        "@currentField",
        "40"
      ]
    },
    "100%",
    {
      "operator": "+",
      "operands": [
        {
          "operator": "toString()",
          "operands": [
            {
              "operator": "*",
              "operands": [
                "@currentField",
                2.5
              ]
            }
          ]
        },
        "%"
      ]
    }
  ]
}

运算符

运算符指定要执行的运算类型。有效的运算符值包括：

+
-
/
*
<
>
%
==
!=
<=
>=
||
&&
toString()
Number()
Date()
cos
sin
?
:
toLocaleString()
toLocaleDateString()
toLocaleTimeString()
indexOf
toLowerCase
join
length
abs
loopIndex
floor
ceiling
pow
substring
getDate
getMonth
getYear
toUpperCase
lastIndexOf
startsWith
endsWith
replace
replaceAll
padStart
padEnd
getThumbnailImage
getUserImage
addDays
addMinutes
appendTo
removeFrom
split

二进制算术运算符 - 需要包含两个操作数的标准算术二进制运算符包括：

+
-
/
*
<
>
%
==
!=
<=
>=

一元运算符 - 只要求一个操作数的标准一元运算符是：

toString()：返回表示对象的字符串
- "txtContent": "=toString(45)" 结果为 “45”
Number()：返回数值，如果操作数不是数字，则返回 NaN
- "txtContent": "=Number('365')" 结果是 365
- "txtContent": "=Number('Wowee')" 结果是 NaN
- "txtContent": "=Number(Date('12/26/1981'))"结果是 378190800000
Date()：从参数返回 datetime 对象， (将字符串或数字转换为日期，对区域设置)
- "txtContent": "=Date('12/26/1981')" 结果是 12/26/1981, 12:00:00 AM
cos：返回应以弧度指定的指定角度的余弦值
- "txtContent": "=cos(5)" 结果是 0.28366218546322625
sin：返回数字的正弦值
- "txtContent": "=sin(90)" 结果是 0.8939966636005579
toDateString()：以简短友好的格式返回日期
- "txtContent": "=toDateString(@now)" 结果不会因用户的区域设置而变化，它将类似于 “2022 年 8 月 3 日周三”
toLocaleString()：返回日期的语言敏感表示形式
- "txtContent":"=toLocaleString(@now)" 结果因用户的区域设置而异，但 en-us 类似于 “2/5/2019，下午 1：22：24”
toLocaleDateString()：仅返回日期的日期部分的语言敏感表示形式
- "txtContent":"=toLocaleDateString(@now)" 结果因用户的区域设置而异，但 en-us 类似于 “2/5/2019”
toLocaleTimeString()：仅返回日期的时间部分的语言敏感表示形式
- "txtContent":"=toLocaleTimeString(@now)" 结果因用户的区域设置而异，但 en-us 类似于 “下午 1：22：24”
toLowerCase：返回转换为小写的值， (仅适用于字符串) - 仅在 SharePoint Online 中可用
- "txtContent":"=toLowerCase('DogFood')" 结果是“dogfood”
abs：返回给定数字的绝对值 - 仅在 SharePoint Online 中可用
- "txtContent":"=abs(-45)" 结果为 45
length：返回数组中的项数 (多选人员或选择字段) ，对于所有其他值类型，如果为 true，则返回 1，在 false 时返回 0。它不提供字符串值的长度（查看后面介绍的有关此类运算的 indexOf 解决方法）。 - 只适用于 SharePoint Online
- "txtContent":"=length(@currentField)"如果有两个选定值，则可能会导致 2
- "txtContent":"=length('Some Text')" 结果为 1
- "txtContent":"=length('')" 结果为 0
- "txtContent":"=length(45)" 结果为 1
- "txtContent":"=length(0)" 结果为 0
floor：返回小于或等于给定数字的最大整数。 - 只适用于 SharePoint Online
- "txtContent":"=floor(45.5)" 的计算结果为 45
ceiling：将给定数字向上舍入到下一个最大的整数或整数。 - 只适用于 SharePoint Online
- "txtContent":"=ceiling(45.5)" 的计算结果为 46
getDate：返回给定日期的月份日期。 - 只适用于 SharePoint Online
- "txtContent":"=getDate(Date('12/26/1981'))" 的计算结果为 26
getMonth：根据本地时间返回指定日期中的月份，作为从零开始的值 (其中零表示) 一年中的第一个月。 - 只适用于 SharePoint Online
- "txtContent":"=getMonth(Date('12/26/1981'))" 的计算结果为 11
getYear：返回给定日期的年份。 - 只适用于 SharePoint Online
- "txtContent":"=getYear(Date('12/26/1981'))" 的计算结果为 1981
toUpperCase：返回转换为大写的值， (仅适用于字符串) - 仅在 SharePoint Online 中可用
- "txtContent":"=toUpperCase('DogFood')" 结果是“DOGFOOD”

二元运算符 - 以下是应有两个操作数的运算符：

indexOf：采用两个操作数。第一个是要在其中搜索的文本（或数组），第二个是要搜索的文本。返回字符串（或数组）中第一次出现的搜索词的索引值。从 0 开始索引。如果在文本 (或数组) 中找不到搜索词，则返回 -1。操作数是区分大小写的。 - 仅 SharePoint Online 中提供
- "txtContent": "=indexOf('DogFood', 'Dog')" 结果为 0
- "txtContent": "=indexOf('DogFood', 'F')" 结果为 3
- "txtContent": "=indexOf('DogFood', 'Cat')" 结果为 -1
- "txtContent": "=indexOf('DogFood', 'f')" 结果为 -1
join：采用两个操作数。第一个是数组（多选人员或选择字段），第二个是分隔字符串。返回由分隔字符串分隔的数组值的字符串串联。 - 仅 SharePoint Online 中提供
- "txtContent": "=join(@currentField, ', ')" 结果可能是“Apple, Orange, Cherry”（具体取决于所选值）
- "txtContent": "=join(@currentField.title, '|')" 可能会生成 “梅根·鲍文|Alex Wilber“ (，具体取决于所选人员)
pow：返回指数幂的基数。 - 只适用于 SharePoint Online
- "txtContent":"=pow(2,3)" 的计算结果为 8
lastIndexOf：返回指定值在字符串 (或数组中最后出现的位置)
- "txtContent": "=lastIndexOf('DogFood DogFood', 'Dog')" 的计算结果为 8
- "txtContent": "=lastIndexOf('DogFood DogFood', 'F')" 的计算结果为 11
- "txtContent": "=lastIndexOf('DogFood DogFood', 'Cat')" 结果为 -1
- "txtContent": "=lastIndexOf('DogFood DogFood', 'f')" 结果为 -1
startsWith：确定字符串是否以指定字符串的字符开头
- "txtContent":"=startsWith('DogFood', 'Dog')" 结果是 true
- "txtContent":"=startsWith('DogFood', 'Food')" 结果是 false
endsWith：确定字符串是否以指定字符串的字符结尾
- "txtContent":"=endsWith('DogFood', 'Dog')" 结果是 false
- "txtContent":"=endsWith('DogFood', 'Food')" 结果是 true
getUserImage：返回指向给定电子邮件和首选大小的用户的个人资料图像的 URL
- "src":"=getUserImage('kaylat@contoso.com', 'small')" 以小分辨率返回指向用户个人资料图片的 URL
- "src":"=getUserImage('kaylat@contoso.com', 's')" 以小分辨率返回指向用户个人资料图片的 URL
- "src":"=getUserImage('kaylat@contoso.com', 'medium')" 以中等分辨率返回指向用户个人资料图片的 URL
- "src":"=getUserImage('kaylat@contoso.com', 'm')" 以中等分辨率返回指向用户个人资料图片的 URL
- "src":"=getUserImage('kaylat@contoso.com', 'large')" 以大分辨率返回指向用户个人资料图片的 URL
- "src":"=getUserImage('kaylat@contoso.com', 'l')" 以大分辨率返回指向用户个人资料图片的 URL
appendTo：返回一个数组，其中给定项追加到给定数组
- "txtContent": "=appendTo(@currentField, 'Choice 4')" 返回一个数组，其中向数组添加了 @currentField “选项 4”
- "txtContent": "=appendTo(@currentField, 'kaylat@contoso.com')" 返回一个数组，其中“”kaylat@contoso.com已添加到 @currentField 数组
removeFrom：返回一个数组，其中包含从给定数组中删除的给定条目（如果存在）
- "txtContent": "=removeFrom(@currentField, 'Choice 4')" 返回从数组中删除了“选项 4”的 @currentField 数组
- "txtContent": "=removeFrom(@currentField, 'kaylat@contoso.com')" 返回从数组中删除了“”kaylat@contoso.com的 @currentField 数组
split：通过搜索给定模式将给定字符串划分为子字符串的有序列表，并返回这些子字符串的数组
- "txtContent": "=split('Hello World', ' ')"返回包含两个字符串的数组 -“Hello”和“World”
addDays：返回一个 datetime 对象，该对象包含添加的天数 (或从给定的日期时间值中扣除)
- "txtContent": "=addDays(Date('11/14/2021'), 3)" 返回 2021 年 11 月 17 日上午 12:00:00
- "txtContent": "=addDays(Date('11/14/2021'), -1)" 返回 2021 年 11 月 13 日上午 12:00:00
addMinutes：返回一个 datetime 对象，该对象具有添加 (或从给定 datetime 值中扣除) 的分钟数
- "txtContent": "=addMinutes(Date('11/14/2021'), 3)" 返回 2021 年 11 月 14 日上午 12:03:00
- "txtContent": "=addMinutes(Date('11/14/2021'), -1)" 返回 2021 年 11 月 13 日上午 11:59:00

三元运算符 - 以下是应有三个操作数的运算符：

substring：返回开始索引和结束索引之间的字符串部分。 - 只适用于 SharePoint Online
- "txtContent":"=substring('DogFood', 3, 4)" 的计算结果为 F
- "txtContent":"=substring('DogFood', 4, 3)" 的计算结果为 F
- "txtContent":"=substring('DogFood', 3, 6)" 的计算结果为 Foo
- "txtContent":"=substring('DogFood', 6, 3)" 的计算结果为 Foo
子字符串 () 方法返回开始索引和结束索引之间的字符串部分或字符串末尾部分。
replace：在字符串 (或数组) 搜索指定值，并返回替换指定值的新字符串 (或数组) 。对于字符串，将仅替换值的第一个实例。
- "txtContent":"=replace('Hello world', 'world', 'everyone')" 结果是 Hello everyone
- "txtContent":"=replace([$MultiChoiceField], 'Choice 1', 'Choice 2')" 返回将选项 1 替换为 Choice 2 的数组
- "txtContent":"=replace([$MultiUserField], @me, 'kaylat@contoso.com')"返回替换为“”kaylat@contoso.com的数组@me
replaceAll：在字符串中搜索指定值，并返回替换指定值) (或数组的新字符串。对于字符串，将替换值的所有实例。
- "txtContent":"=replaceAll('H-e-l-l-o W-o-r-l-d', '-', '')"结果Hello World
padStart：用另一个字符串填充当前字符串，直到生成的字符串达到给定长度。从当前字符串的开头应用填充。
- "txtContent":"=padStart('DogFood', 10, 'A')" 结果是 AAADogFood
- "txtContent":"=padStart('DogFood', 10, 'AB')" 结果是 ABADogFood
- "txtContent":"=padStart('DogFood', 5, 'A')" 结果是DogFood
padEnd：使用给定字符串填充当前字符串，直到生成的字符串达到给定长度。从当前字符串的结尾应用填充。
- "txtContent":"=padEnd('DogFood', 10, 'A')" 结果是DogFoodAAA
- "txtContent":"=padEnd('DogFood', 10, 'AB')" 结果是DogFoodABA
- "txtContent":"=padEnd('DogFood', 5, 'A')" 结果是DogFood
getThumbnailImage：返回指向给定图像字段和首选大小的图像的 URL。
- "src":"=getThumbnailImage([$ImageField], 400, 200)" 生成指向宽度为 400 且高度为 200 的给定图像字段的图像的 URL

条件运算符 - 条件运算符如下：

?：使用抽象树语法编写的条件运算使用 ? 作为运算符。这是为了实现等效 a ? b : c的表达式，其中，如果表达式 a 的计算结果为 true，则结果为 b，否则结果为 c。对于 Excel 样式的表达式，可以使用语句编写这些 if 表达式。无论如何，有三个操作数。第一个是要计算的条件。第二个是条件为 true 时的结果。第三个是条件为 false 时的结果。
- "txtContent":"=if(4 < 5, 'yes', 'no')" 结果是“yes”
- "txtContent":"=if(4 > 5, 'yes', 'no')" 结果是“no”

多值字段相关运算符 - 以下运算符仅在具有 Person、Lookup 或 Choice 类型的多值字段的上下文中使用。

length
join
loopIndex

如果提供了字段名称，则 length 返回多值字段中的成员数。当提供单值字段时， length 当该字段中有值时，将返回 1。

join 使用指定的运算符串联多值字段中的值。第一个操作数应指向多值字段中的值，例如 "@currentField.lookupValue"。 "[$AssignedTo.title]" 第二个操作数应为一个字符串字面量，它是将值联接在一起的分隔符。

loopIndex如果提供迭代器变量的名称，则返回从迭代器 0) 开始的当前索引 (。迭代器的名称必须作为字符串文本提供。仅在启用了各自的 forEach 或其子元素时，才可在元素中使用 loopIndex。

有关示例，请参阅设置多值字段的格式。

与字符串相关的运算符 - 使用字符串值时，可以使用一些以前详细的运算符：

+
indexOf 字符串长度的 (解决方法)

+ 在需要连接字符串时可以使用，例如：

"txtContent": "=[$column1] + ' ' + [$column2] + 'some other text'"

indexOf 由于运算符 length 不适用于字符串值类型， (它将返回 1 或 0) ， indexOf 因此可以作为获取字符串长度的不错解决方法，例如： indexOf([$column1] + '^', '^')。我们将使用 '^' 或任何其他字符来查找字符串的末尾。

操作数

指定表达式的参数或操作数。这是一组表达式对象或基值。

特殊字符串值

txtContent、style 和 attributes 的值可以是字符串，也可以是表达式对象。支持使用一些特殊字符串模式，从列表字段和用户上下文中检索值。

"@currentField"

将评估当前字段的值。

一些字段类型表示为对象。若要输出对象值，请引用相应对象内的特定属性。例如，如果当前字段是人员/组字段，指定 @currentField.title 可以检索人员姓名（通常显示在列表视图中）。下面介绍了表示为对象的字段类型，并列出了它们的属性。

注意

@currentField.title 默认返回人员的姓名。不过，如果调整了人员字段的显示字段，可能就会更改 title 属性值。例如，如果人员字段将显示字段配置为“部门”，则会使用人员部门作为 title 属性值。

人员字段

人员字段对象的属性如下（带有示例值）：

{
  "id": "122",
  "title": "Kalya Tucker",
  "email": "kaylat@contoso.com",
  "sip": "kaylat@contoso.com",
  "picture": "https://contoso.sharepoint.com/kaylat_contoso_com_MThumb.jpg?t=63576928822",
  "department":"Human Resources",
  "jobTitle":"HR Manager"
}

“人员”字段可以有带以下格式设置的个人资料悬停卡片：

{
  "elmType": "div",
  "txtContent": "[$Editor.title]",
  "defaultHoverField": "[$Editor]"
}

日期/时间字段

可以通过几种不同的方式检索日期/时间字段值，具体视要显示的日期格式而定。支持使用以下方法，将日期值转换为特定格式：

toLocaleString() - 显示完全扩展为包含日期和时间的日期类型。
toLocaleDateString() - 显示只包含日期的日期类型。
toLocaleTimeString() - 显示只包含时间的日期类型。

例如，下面的 JSON 将当前字段（假设是日期字段）显示为日期和时间字符串。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": {
    "operator": "toLocaleString()",
    "operands" : ["@currentField"]
  }
}

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "=toLocaleString(@currentField)"
}

位置字段

位置字段对象的属性如下（带有示例值）：

{
  "Address": {
    "City": "Knoxville",
    "CountryOrRegion": "United States",
    "State": "TN",
    "Street": "963 Worlds Fair Park Dr"
  },
  "Coordinates": {
    "Latitude": "35.961673736572266",
    "Longitude": "-83.92420959472656"
  },
  "DisplayName": "World's Fair Park",
  "LocationUri": "https://www.bingapis.com/api/v6/localentities/8346bf26-6da4-104c-6ba5-2334b83f6ac8?setLang=en"
}

下面的示例展示了如何对当前字段使用位置字段。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json",
  "elmType": "div",
  "style": {
    "display": "block"
  },
  "children": [
    {
      "elmType": "a",
      "txtContent": "@currentField.DisplayName",
      "attributes": {
        "href": "='https://www.bing.com/maps?cp=' + @currentField.Coordinates.Latitude + '~' + @currentField.Coordinates.Longitude + '&lvl=17&sV=2'",
        "target": "_blank",
        "title": "=@currentField.Coordinates.Latitude + ', ' + @currentField.Coordinates.Longitude"
      },
      "style": {
        "display": "block"
      }
    },
    {
      "elmType": "div",
      "txtContent": "@currentField.Address.Street"
    },
    {
      "elmType": "div",
      "txtContent": "=@currentField.Address.City + ', ' + @currentField.Address.State"
    },
    {
      "elmType": "div",
      "txtContent": "@currentField.Address.CountryOrRegion"
    }
  ]
}

查阅字段

查阅字段对象的属性如下（带有示例值）：

{
  "lookupId": "100",
  "lookupValue": "North America",
}

下面的示例展示了如何对当前字段使用查阅字段。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "a",
  "txtContent": "@currentField.lookupValue",
  "attributes": {
    "href": {
      "operator": "+",
      "operands": [
        "https://contoso.sharepoint.com/teams/Discovery/Lists/Regions/DispForm.aspx?ID=",
        "@currentField.lookupId"
      ]
    },
    "target": "_blank"
  }
}

超链接字段

超链接字段对象的属性如下（带有示例值）：

{
  "desc": "SharePoint Patterns and Practices",
}

若要引用 URL 值，请使用 @currentField。

下面的示例展示了如何对当前字段使用超链接字段。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "a",
  "txtContent": "@currentField.desc",
  "attributes": {
    "href": "@currentField",
    "target": "_blank"
  }
}

图像字段

图像字段对象具有以下 fileName 属性：

{
  "fileName": "image.png",
}

注意

截至 2024 年 7 月，只有 fileName 属性具有值。

以下示例显示如何在当前字段上使用图像字段。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "img",
  "attributes": {
    "src": "=getThumbnailImage(@currentField, 400, 300)",
    "alt": "@currentField.fileName"
  },
  "style": {
    "width": "100%",
    "max-width": "100%"
  }
}

审批状态字段

审批状态字段对象的属性如下 (带有示例值):

{
  "displayValue": "Approved",
  "numeric": 0
}

displayValue 是审批状态的本地化字符串。

@currentField 或 [$__ModerationStatus] 还会在内部映射到以下内部数值：

0：已批准
1：被拒绝
2：挂起
3：草稿
4：计划

[$_ModerationStatus] 字段支持对字符串和数值进行比较。数值比较适用于区域设置和语言，这是此字段的推荐方式。

当状态为 Pending 时，以下表达式的计算结果为右侧的输出：

// reading field value
"[$_ModerationStatus]" => "Pending"

// obtaining the internal numeric value:
"=Number([$_ModerationStatus])" => 2
"=[$_ModerationStatus.numeric]" => 2

// addition results in string concatenation:
"='status:'+[$_ModerationStatus]" => 'status:Pending'

// numeric comparisons
"=([$_ModerationStatus] == 2)" => true
"=([$_ModerationStatus] != 1)" => true

// other comparators are rarely useful, for cases where you want might want to exclude Draft & Scheduled
"=([$_ModerationStatus] < 3)" => true

// localized string comparison, works only with one locale (en-us here)
"=if([$_ModerationStatus]=='Pending','This Works too!', 'Nope!')" => 'This Works too!'

以下示例演示如何在当前字段上使用审批状态字段：

{
  "elmType": "div",
  "txtContent": "@currentField.displayValue",
  "style": {
    "color": "=if(@currentField == 2, 'red', '')"
  }
}

"[$FieldName]"

列在整行的上下文中进行格式化。通指定前面带一个美元符号并由方括号括起来的字段内部名称：[$InternalName]，可以使用此上下文引用同一行中其他字段的值。例如，若要获取内部名称为“MarchSales”的字段值，请使用 [$MarchSales]。

注意

仅当其他字段包含在同一视图中时，对其他字段的引用才起作用。

如果字段值是对象，可以访问对象的属性。例如，若要访问“SalesLead”人员字段的“Title”属性，请使用 "[$SalesLead.title]"。

"[!FieldName]"

在列和视图格式设置中，可以通过指定用方括号括起来且前面有感叹号的字段 的内部名称 来引用任何字段的元数据： [!InternalName]。

当前字段的显示名称在此元数据中可用，可以使用属性进行访问 DisplayName ： [!SalesLead.DisplayName]。

"@currentWeb"

这将评估网站的绝对 URL。它等于页面上下文中的 webAbsoluteUrl 值。此值仅在 SharePoint Online 中提供。

"@me"

这将评估当前登录用户的电子邮件地址。

此字段可用于显示当前用户的电子邮件地址，但更有可能是在条件内使用。下面是一个示例，当人员字段等于当前登录用户时，将颜色设置为红色，否则为蓝色：

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "@currentField.title",
  "style": {
    "color": {
      "operator": "?",
      "operands": [
        {
            "operator": "==",
            "operands": [
              "@me",
              "@currentField.email"
            ]
        },
          "red",
          "blue"
      ]
    }
  }
}

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "@currentField.title",
  "style": {
    "color": "=if(@me == @currentField.email, 'red', 'blue')"
  }
}

"@now"

这将评估当前日期和时间。

"@rowIndex"

这将评估视图中行的呈现索引。此值基于呈现位置，即使已对视图进行排序和筛选，也会根据位置保持一致。从 0 开始索引。此值仅在 SharePoint Online 中提供。

下面是是使用视图格式中的值将交替样式应用于行的示例：

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

"@window.innerHeight"

在呈现列表时，这将计算为一个等于浏览器窗口高度 (以像素为单位的数字) 。

"@window.innerWidth"

计算结果为呈现列表时等于浏览器窗口宽度（以像素为单位）的数字。

缩略图

在文档库中，有一系列令牌可用于检索文件缩略图的 URL，其中包括：

@thumbnail.small、 @thumbnail.medium和 @thumbnail.large 以三个预定义大小评估缩略图 URL。
@thumbnail.<bounding size> 将 URL 计算为宽度和高度上不大于边界大小的最大缩略图。例如，@thumbnail.150 计算结果为不大于 150 × 150 像素的缩略图的 URL。
@thumbnail.<bounding width>x<bounding height> 将 URL 评估为不大于边界宽度和边界高度的最大缩略图。例如，@thumbnail.100x200 计算结果为宽度不超过 100 像素且高度不超过 200 像素的缩略图的 URL。

这些标记将不会在非文件项目（包括文件夹）中生成值。

注意

生成的缩略图的纵横比与文件的外观相同，更改边界大小不会影响缩略图的纵横比。

提示

缩略图仅适用于支持的文件格式列表。这意味着由于缺乏对某些格式的支持，有时生成的 URL 是无法访问的。但是，如果将有效的缩略图标记设置为标记的唯src 一 img 属性，我们将处理它，并在图像不可用时隐藏该图像。

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "img",
  "attributes": {
    "src": "@thumbnail.200x150",
    "alt": "='Thumbnail of file ' + [$FileLeafRef]"
  },
  "style": {
    "width": "100%",
    "max-width": "100%"
  }
}

使用 FileLeafRef 的默认文件悬停卡

{
  "elmType": "img",
  "style": {
    "width": "100%",
    "height": "100%",
    "display": "=if([$File_x0020_Type] == '', 'none', '')"
  },
  "attributes": {
    "src": "@thumbnail.300x300"
  },
  "defaultHoverField": "[$FileLeafRef]"
}

displayValue

以下列类型可以使用 displayValue 属性来获取默认呈现的值，具体取决于列设置：

日期/时间
数字
是/否
货币
审批状态

{
  "elmType": "div",
  "txtContent": "@currentField.displayValue"
}

这也适用于字段名称：

{
  "elmType": "div",
  "txtContent": "[$FieldName.displayValue]"
}

“@isSelected”

对于视图中的选定项 () ，这将计算结果 true 为， false 否则为。

“@lcid”

这将评估当前区域性的 LCID。这可用于设置日期、时间和数字的格式。

“@UIlcid”

这将评估为当前 UI 区域性的 LCID。这可用于显示本地化的显示字符串。

通过

格式设置语法参考

elmType

filepreview

img src 安全性

txtContent

style

attributes

children

debugMode

forEach

customRowAction

customCardProps

defaultHoverField

columnFormatterReference

inlineEditField

filePreviewProps

表达式

Excel 样式的表达式

抽象语法树表达式

运算符

操作数

特殊字符串值

"@currentField"

"[$FieldName]"

"[!FieldName]"

"@currentWeb"

"@me"

"@now"

"@rowIndex"

"@window.innerHeight"

"@window.innerWidth"

缩略图

displayValue

“@isSelected”

“@lcid”

“@UIlcid”

其他资源