Использование JSON форматирования столбцов SharePoint в List Filter Online

Введение

Форматирование столбцов — это возможность SharePoint Online, которая изменяет отображение столбца с помощью описания в формате JSON: состояние в виде цветного индикатора, число, окрашенное в зависимости от значения, пользователь в виде ссылки, открывающей письмо. Описание хранится в самом столбце, и SharePoint применяет его во всех представлениях списка.

List Filter Online умеет учитывать эти описания. Когда параметр включён, веб-часть читает JSON форматирования каждого столбца, у которого он есть, и строит по нему ячейки таблицы, поэтому таблица на вашей странице выглядит как список, из которого она берёт данные. Веб-часть реализует наиболее употребительное подмножество языка форматирования столбцов; в этой статье точно перечислено, что поддерживается, что нет и что происходит, когда формат выходит за пределы подмножества.

Включение форматирования столбцов

Откройте страницу в режиме редактирования, откройте область свойств веб-части и разверните группу Вид. Включите параметр Использовать форматирование столбцов из списка. По умолчанию параметр выключен.

Сам JSON в веб-части не вводится. Он берётся из определения столбца в исходном списке — того же определения, которое SharePoint редактирует, когда вы открываете в списке Параметры столбца → Форматировать этот столбец и сохраняете формат. Веб-часть загружает его вместе с остальными свойствами столбцов, поэтому формат, заданный столбцу списка на другом сайте, тоже применяется. Форматы задаются на уровне столбцов: каждый столбец с форматом выводится по нему, а столбцы без формата сохраняют форматы отображения, выбранные в конфигураторе столбцов (см. статью KB10258. Настройка столбцов в List Filter Online: заголовки, форматы и параметры отображения).

Когда формат применяется к столбцу, он полностью заменяет содержимое ячейки, включая параметр Ссылка на элемент этого столбца. Если значение должно оставаться ссылкой, добавьте ссылку в сам формат.

Что поддерживается

Элементы

Формат — это дерево элементов. Каждый элемент является объектом со следующими ключами:

• elmType — одно из значений div, span, a, img, button или p. Любое другое значение, кроме неподдерживаемых, перечисленных ниже, выводится как div.
• txtContent — текст элемента: строковый литерал, токен поля или выражение.
• style — CSS-свойства элемента (см. ниже).
• attributes — HTML-атрибуты элемента (см. ниже).
• children — массив дочерних элементов, выводимых по порядку.

Ключи, неизвестные веб-части, такие как $schema или debugMode, игнорируются.

Стили

Объект style может задавать следующие CSS-свойства; каждое значение может быть литералом или выражением:

background, background-color, border, border-top, border-right, border-bottom, border-left, border-color, border-style, border-width, border-radius, box-shadow, color, cursor, direction, display, fill, flex-direction, flex-wrap, align-items, justify-content, font-family, font-size, font-style, font-weight, letter-spacing, line-height, text-align, text-decoration, text-overflow, text-transform, white-space, word-break, overflow, opacity, visibility, padding, padding-top, padding-right, padding-bottom, padding-left, margin, margin-top, margin-right, margin-bottom, margin-left, width, min-width, max-width, height, min-height, max-height.

Свойства вне этого списка — например position или z-index, способные нарушить разметку таблицы, — пропускаются без сообщений. Значение, содержащее url(, также пропускается, поэтому фоновые изображения через стили загрузить нельзя.

Атрибуты

Остальные атрибуты, включая role, aria-*, d и data-interception, игнорируются.

Токены полей

Токены могут стоять отдельно ("txtContent": "@currentField") или внутри более длинной строки ("txtContent": "Владелец: [$Owner.title]"). Столбец с несколькими значениями (несколько пользователей, подстановок или терминов) отображается как список через запятую; обращение к свойству, например [$Owner.email], у такого столбца возвращает свойство первого значения. Значения пользователей и подстановок отображаются своим именем; даты — в виде локализованной даты.

Выражения

Выражения записываются либо как деревья операторов — объекты с ключами operator и operands, — либо как строки, начинающиеся с =, в Excel-подобном синтаксисе SharePoint. Обе формы поддерживают один и тот же набор операций:

• арифметика: + (также сцепление строк), -, *, /, %;
• сравнение: ==, !=, >, <, >=, <= — даты сравниваются по метке времени;
• логика: &&, ||, !, условный оператор ? : (в дереве — оператор ? или : с тремя операндами) и функция if(условие, еслиИстина, еслиЛожь);
• преобразование: toString(), Number(), Date();
• числа: abs(), floor(), ceiling();
• строки: toLowerCase(), toUpperCase(), indexOf(), substring(), length().

В строках с = строковые литералы записываются в одинарных или двойных кавычках, числа — цифрами, логические значения — как true и false; скобки группируют подвыражения, а токены полей используются напрямую: =if([$Priority] == 'High', '#a4262c', '#323130').

Что не поддерживается

Веб-часть не реализует следующие части языка форматирования столбцов:

• forEach — повторение элемента для каждого значения столбца с несколькими значениями;
• customRowAction — кнопки, запускающие поток, открывающие панель или задающие значение поля;
• elmType: "filepreview" — предварительный просмотр документов;
• elmType: "svg" и path — встроенная векторная графика;
• токены @rowIndex, @window, @thumbnail, @currentWeb и другие токены, не перечисленные выше;
• операторы и функции, не перечисленные выше, такие как toLocaleString(), toLocaleDateString(), startsWith(), padStart(), replace(), split(), join(), getDate(), addDays(), getUserImage(), cos() и sin().

Формат, использующий forEach, customRowAction, filepreview, svg, неизвестный оператор или функцию, неизвестный токен @ или содержащий синтаксическую ошибку в выражении с =, вывести нельзя. В этом случае веб-часть отказывается от формата и выводит столбец с его отображением по умолчанию — форматом, выбранным в конфигураторе столбцов, — точно так, как если бы параметр был выключен для этого столбца. Остальные столбцы не затрагиваются. Неизвестные атрибуты и свойства стилей, напротив, просто пропускаются, а остальная часть формата применяется.

Примеры

Следующие форматы не выходят за пределы поддерживаемого подмножества.

Индикатор состояния. Значение выбора показывается на скруглённом фоне, цвет которого зависит от значения:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "@currentField",
  "style": {
    "display": "inline-block",
    "padding": "2px 10px",
    "border-radius": "12px",
    "font-weight": "600",
    "color": "#ffffff",
    "background-color": "=if(@currentField == 'Approved', '#107c10', if(@currentField == 'Rejected', '#a4262c', '#8a8886'))"
  }
}

Число, окрашенное в зависимости от значения, записанное как дерево операторов. Суммы больше 1000 показываются красным полужирным шрифтом:

{
  "elmType": "span",
  "txtContent": "@currentField",
  "style": {
    "color": {
      "operator": "?",
      "operands": [
        { "operator": ">", "operands": [ { "operator": "Number()", "operands": [ "@currentField" ] }, 1000 ] },
        "#a4262c",
        "#107c10"
      ]
    },
    "font-weight": "=if(Number(@currentField) > 1000, '700', '400')"
  }
}

Ссылка со значком. Пользователь из столбца «Кому назначено» выводится как почтовая ссылка со значком конверта; формат задаётся самому столбцу «Кому назначено» и использует свойства значения пользователя:

{
  "elmType": "a",
  "attributes": {
    "href": "='mailto:' + @currentField.email",
    "title": "=@currentField.title",
    "iconName": "Mail",
    "target": "_blank"
  },
  "txtContent": "@currentField.title",
  "style": {
    "color": "#0078d4",
    "text-decoration": "none"
  }
}

Производительность

JSON столбца разбирается один раз — при первом выводе ячейки этого столбца, — и разобранное дерево повторно используется для всех остальных ячеек столбца и для всех последующих страниц элементов. Для каждой ячейки вычисляются только токены и выражения. Поэтому включение параметра почти не увеличивает время появления таблицы даже на длинных страницах.

Связанные статьи