Введение

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

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

📝 Заметка
Веб-часть применяет только форматирование столбцов. Форматирование представлений - 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(, также пропускается, поэтому фоновые изображения через стили загрузить нельзя.

Атрибуты

АтрибутЭлементыПоведение
classвсеЗадаёт CSS-класс элемента. Имена классов SharePoint, такие как sp-field-severity--good, принимаются, но на странице не имеют стилей; для цветов используйте style.
titleвсеЗадаёт всплывающую подсказку элемента.
hrefaАдрес ссылки. Разрешены http:, https:, mailto:, tel: и относительные адреса; любая другая схема отбрасывается, и элемент выводится без ссылки. Ссылки получают rel="noreferrer".
targetaЦелевое окно ссылки; _blank (новая вкладка), если не указано.
src, altimgАдрес и альтернативный текст изображения. Действуют те же правила адресов, что и для href; изображение без допустимого src не выводится.
iconNameвсеИмя значка Fluent UI, например Mail или CheckMark, вставляемого перед текстом элемента.

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

Токены полей

ТокенЗначение
@currentFieldЗначение форматируемого столбца.
@currentField.propСвойство значения: для пользователя title, email, id, jobTitle, department или picture; для подстановки lookupValue или lookupId; для гиперссылки Url или Description.
[$Field]Значение другого столбца того же элемента по его внутреннему имени.
[$Field.prop]Свойство этого значения с теми же именами свойств.
@meАдрес электронной почты текущего пользователя.
@nowТекущие дата и время.

Токены могут стоять отдельно ("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, неизвестный оператор или функцию, неизвестный токен @ в выражении с = или содержащий синтаксическую ошибку в выражении с =, вывести нельзя. В этом случае веб-часть отказывается от формата и выводит столбец с его отображением по умолчанию - форматом, выбранным в конфигураторе столбцов, - точно так, как если бы параметр был выключен для этого столбца. Остальные столбцы не затрагиваются. Неизвестные атрибуты и свойства стилей, напротив, просто пропускаются, а остальная часть формата применяется.

❗ Важно
Форматы, созданные конструктором форматирования столбцов в SharePoint, и образцы, опубликованные корпорацией Майкрософт, часто используют конструкции вне поддерживаемого подмножества, такие как forEach, customRowAction, getUserImage() или toLocaleDateString(). Поэтому формат, работающий в списке, в веб-части может откатиться к отображению по умолчанию. После включения параметра всегда проверяйте результат на странице и упростите формат, если столбец выводится не так, как ожидалось.

📝 Заметка
Значения могут поступать как текст, отформатированный по региональным параметрам списка. Используйте Number() или Date() только для форматов, которые эти функции распознают: локальные десятичные разделители, разделители тысяч и форматы дат могут преобразовываться неверно. Ссылка на другой столбец не гарантирует получение исходного числового значения или даты. Проверяйте фактические значения и упрощайте форматирование, если преобразование ненадёжно.

Внутри длинных строк подставляются @currentField, его свойства и ссылки [$Field]. Используйте @me и @now отдельно или в выражениях с =. Неизвестный токен @ вызывает возврат к стандартному отображению в выражении с =, а в обычном тексте остаётся буквальным текстом.

Примеры

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

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

{
  "$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 столбца разбирается один раз - при первом выводе ячейки этого столбца, - и разобранное дерево повторно используется для всех остальных ячеек столбца и для всех последующих страниц элементов. Для каждой ячейки вычисляются только токены и выражения. Поэтому включение параметра почти не увеличивает время появления таблицы даже на длинных страницах.

Вопросы и ответы

Задайте вопрос по статье и получите официальный ответ нашей команды.

Вопросов пока нет. Задайте первый вопрос.

Рекомендуемые статьи

Ограничения и производительность: большие доски, длинные ветки и порог представления списка

Справочник по ограничениям Vitextra Discussions: как выполняется постраничная загрузка списка тем, какие столбцы индексированы, как загружаются длинные ветки, ограничение 10 МБ для изображений и структура «папка на год» библиотеки Файлы обсуждений, лимиты очереди модерации и веб-части Activity, а также рекомендации для досок с более чем 5 000 тем.

55 6 мин
Настройка и использование Pending Policies Bar

Добавьте компактное напоминание о политиках на страницу интранета, настройте переходы и узнайте, почему его счётчик может отличаться от My Policies.

20 3 мин
Как настроить аудиторию кампании ознакомления

Объединяйте группы Entra ID и SharePoint, атрибуты сотрудников и индивидуальные исключения для выбора аудитории кампании.

18 4 мин

Поделиться