Лист _data

Шаблоны XLSX поддерживают зарезервированный лист _data, который подтягивает дополнительные источники данных — записи других типов сущностей, отфильтрованные выражением. Благодаря этому одна сформированная книга может объединять данные из нескольких источников.

Лист _data доступен только в шаблонах XLSX.

Обзор всех возможностей XLSX — типизированные значения, живые формулы, разделение ячеек и другое — см. в разделе Шаблоны Excel.

Когда использовать лист _data

Используйте лист _data, когда сформированной книге нужны данные сверх тех, что даёт запись, из которой запущено формирование. Типичные случаи:

  • книга договора, в которую включён актуальный прайс-лист из типа сущности справочника,

  • отчёт для сверки, который подтягивает платежи из отдельного типа сущности вместе с данными сделки,

  • сводка по кампании, которая объединяет данные сделки с записями инвентаря конструкций, отфильтрованными по региону.

Без листа _data шаблон XLSX может обращаться только к полям записи, из которой запущено формирование, и к записям, связанным с ней через поля-ссылки.

Структура листа

Лист _data использует три столбца для объявления каждого источника данных:

Столбец Содержит Содержание

A

Ключ коллекции

Имя, по которому на этот источник данных ссылаются плейсхолдеры на других листах. Например, priceCatalog.

B

Тип сущности

Машинное имя типа сущности, который нужно запросить. Например, priceListEntry.

C

Выражение фильтра

Выражение, которое отфильтровывает возвращаемые записи. Синтаксис выражения такой же, как у выражений в остальных частях системы. Оставьте пустым, чтобы вернуть все записи этого типа сущности.

Каждая строка объявляет один источник данных, начиная с первой строки листа. На одном листе _data можно объявить столько источников данных, сколько в нём строк. Строка с пустым столбцом A пропускается, поэтому пустые строки можно использовать как разделители.

Вспомогательные столбцы

Столбцы D и далее можно использовать для вспомогательных вычислений — промежуточных значений, служебных формул или заметок. Движок не читает эти столбцы как часть объявлений источников данных.

Пример

Допустим, в системе есть два типа сущностей: Позиция прайс-листа (машинное имя priceListEntry, поля itemName, unitPrice и category) и Цифровой экран (машинное имя digitalDisplay, поле status). Все это машинные имена, заданные, когда администратор создавал каждый тип сущности и его поля.

Лист _data, который подтягивает все позиции прайс-листа категории «outdoor» и все активные конструкции:

Лист _data
A B C

1

priceCatalog

priceListEntry

category == 'outdoor'

2

activeDisplays

digitalDisplay

status == 'active'

Объявления начинаются со строки 1.

Подписи к столбцам

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

Чтобы подписать столбцы, поставьте в столбец A комментарий. Комментарий формируется в ничто, и столбец A остаётся пустым, а строка с пустым столбцом A пропускается ещё до чтения столбцов B и C, так что остальная часть строки — свободный текст:

Лист _data со строкой подписей
A B C

1

{{! Ключ коллекции }}

Тип сущности

Фильтр

2

priceCatalog

priceListEntry

category == 'outdoor'

3

activeDisplays

digitalDisplay

status == 'active'

Подпись остаётся видимой для того, кто открывает шаблон, и невидима для движка. Строка, у которой столбец A просто оставлен пустым, пропускается так же — так работают пустые строки-разделители между группами объявлений.

#, // или -- в столбце A читаются как обычный ключ коллекции и дают источник данных, который не загрузился, и строку на листе _errors.

На других листах книги загруженные записи доступны как коллекции. Внутри повторяющегося раздела плейсхолдеры используют машинные имена полей загруженного типа сущности — здесь itemName и unitPrice из типа Позиция прайс-листа:

{{#priceCatalog}}
  {{itemName}}  |  {{unitPrice}}
{{/priceCatalog}}

Порядок обработки

Лист _data обрабатывается в два этапа:

  1. Формирование — сначала все ячейки листа _data проходят через движок шаблонов. Значит, в столбце с выражением фильтра можно использовать плейсхолдеры. Например, если у типа сущности записи, из которой запущено формирование, есть поле с машинным именем dealRegion, фильтр region == '{{$.dealRegion}}' берёт dealRegion из этой записи до применения фильтра.

    В пакетных отчётах критерии поиска пользователя доступны по ключу filter. Выражение фильтра region == '{{filter.variableValues.region}}' подставляет выбранный пользователем регион до выполнения запроса к источнику данных.

  2. Чтение объявлений — после формирования движок читает столбцы A, B и C, чтобы извлечь объявления источников данных, и загружает запрошенные записи.

Каждый источник данных объявляется и фильтруется независимо от остальных источников на листе _data.

После обработки лист _data удаляется из итоговой книги. В сформированном файле его нет.

Зарезервированные ключи коллекций

Два ключа коллекций зарезервированы и не могут использоваться на листе _data:

  • items — зарезервирован для вложенных элементов основной записи (например, позиций предложения).

  • filter — содержит критерии поиска, которые пользователь применил при формировании отчёта. Движок использует этот ключ, чтобы сделать значения фильтра доступными как плейсхолдеры — {{filter.name}}, {{filter.variableValues.region}} и так далее. Полный справочник и примеры — в разделе значения фильтра в шаблоне.

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

Префикс формулы

Ячейка, которая начинается с {{=}}, считается формулой Excel: префикс отбрасывается, остаток формируется как шаблон, а результат записывается в ячейку как формула.

Это отличается от плейсхолдера-выражения ({{=price * quantity}}), который вычисляет JavaScript и вставляет статическое значение. Обратите внимание, где стоят закрывающие скобки — в этом вся разница.

Тот же префикс работает и на обычных листах; см. Шаблоны Excel. На листе _data он важнее, потому что формулы вычисляются до чтения объявлений, и благодаря этому столбец C может вычислять фильтр из значений, посчитанных во вспомогательных столбцах.

Используйте префикс, когда для фильтра нужно вычисление, например арифметика с датами.

Пример — всё, что создано за последние 30 дней:

Лист _data
A B C

1

recentDeals

deal

{{=}}CONCATENATE("createdAt > '", TEXT(TODAY()-30, "yyyy-mm-dd"), "'")

Три этапа по порядку:

  1. Каждая ячейка листа формируется как шаблон.

  2. Каждая формула листа вычисляется, так что C1 становится текстом createdAt > '2026-07-02'.

  3. Столбцы A, B и C читаются как объявление — и в C1 теперь готовый фильтр.

То же работает и со вспомогательными столбцами: поместите промежуточное значение в столбец D, а формула в столбце C пусть читает D1.

Здесь префикс не выводит формулу перед читателем. Лист _data удаляется из итоговой книги, поэтому формула существует лишь столько, сколько нужно, чтобы получить текст фильтра.

Проверка прав

Движок проверяет, что у текущего пользователя есть право на чтение типа сущности, объявленного в каждом источнике данных. Если права на чтение этого типа сущности нет, источник данных не загружается.

Обработка ошибок

Источник данных, который не удалось загрузить, не останавливает отчёт. Если типа сущности нет, выражение фильтра неверно, ключ коллекции зарезервирован или не пройдена проверка прав, движок:

  • подставляет для этого ключа коллекции пустой массив (поэтому плейсхолдеры, которые на него ссылаются, ничего не выводят, а не дают ошибку), и

  • создаёт в итоговой книге лист _errors.

На листе _errors четыре столбца:

Столбец Содержание

Collection Key

Ключ коллекции из строки листа _data, которая не загрузилась.

Entity Type

Машинное имя запрошенного типа сущности.

Filter

Использованное выражение фильтра.

Error

Описание того, что пошло не так.

Если все источники данных загрузились, лист _errors не создаётся.

Если какие-то разделы с данными оказались пустыми, проверьте в сформированной книге лист _errors. Лист _errors — основной диагностический инструмент для проблем с листом _data.

Связанные страницы