Шаблоны Excel

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

Благодаря этому шаблоны XLSX подходят для двух разных задач:

  • Пакетные отчёты — периодические выгрузки, которые подтягивают данные из нескольких типов сущностей, считают формулами и дают книгу, готовую для анализа или рассылки.

  • Экспорт документа из одной записи — приложение к договору, приложение с ценами или лист сверки, сформированные из одной записи, когда результат должен быть настоящей таблицей с работающими формулами, а не статичной распечаткой.

Эта страница описывает поведение, специфичное для движка XLSX. Возможности, общие для всех трёх форматов — плейсхолдеры, повторяющиеся разделы, выражения и изображения, — описаны на своих страницах, а здесь на них даны ссылки там, где обработка в XLSX отличается.

Значения попадают в ячейки с настоящими типами Excel

Когда движок заполняет плейсхолдер, он не вставляет каждое значение как текст. Он проверяет полученное значение и записывает его как подходящий тип ячейки Excel:

Число

Если значение удаётся разобрать как число, ячейка получает числовое значение. Excel воспринимает его как число для формул, сортировки и форматирования.

Логическое значение

Если значение — строка true или false (без учёта регистра), ячейка получает логическое значение.

Дата

Если значение соответствует распознаваемому шаблону даты, ячейка получает серийный номер даты — так Excel хранит даты внутри. Формат даты применяется автоматически (см. Автоформат дат ниже).

Текст

Если ничего из перечисленного не подошло, ячейка получает текстовую строку.

Пусто

Если значение — пустая строка, ячейка остаётся пустой: ни значения, ни формулы, ни константы с пустой строкой.

Благодаря такой работе с типами столбец цен, заполненный через {{unitPrice}} — где unitPrice — машинное имя поля типа «Дробное» в типе сущности, — корректно суммируется формулой Excel без преобразования.

Автоформат дат

Когда значение даты записывается в ячейку с форматом Общий (по умолчанию в Excel), движок автоматически применяет формат dd.MM.yyyy — например, 15.03.2025.

Если автор шаблона уже задал для ячейки собственный числовой формат — например, MM/dd/yyyy или yyyy-MM-dd HH:mm, — движок сохраняет его и не переопределяет.

Значит, вывод дат можно контролировать двумя способами:

  • Принять значение по умолчанию — оставьте у ячейки формат «Общий», и результат будет в формате dd.MM.yyyy.

  • Выбрать свой формат — задайте в файле шаблона для ячейки собственный формат даты, и движок его соблюдёт.

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

Живые формулы Excel

Формула, введённая в шаблон обычным способом — в Excel как =A2*B2, — остаётся нетронутой. В итоговом файле она остаётся живой формулой и пересчитывается как обычно.

Этого достаточно, когда формула известна заранее. Когда это не так — когда диапазон зависит от числа строк в данных, — запишите формулу как текст и пометьте ячейку префиксом формулы.

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

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

Смысл префикса в том, что сама формула — шаблон. Здесь lastRow — машинное имя поля типа сущности, в котором хранится последняя строка блока данных:

{{=}}SUM(D2:{{lastRow}})

Если lastRow разрешается в D41, ячейка получает =SUM(D2:D41). В следующем месяце, когда строк станет больше, тот же шаблон даст другой диапазон.

В одной формуле может быть несколько плейсхолдеров. Оба конца диапазона могут браться из данных:

{{=}}SUM({{rangeStart}}:{{rangeEnd}})

Если rangeStart равно C2, а rangeEnd — C41, ячейка получает =SUM(C2:C41).

Префикс должен стоять в самом начале ячейки.

Формулу с фиксированным диапазоном вводите в ячейку шаблона в Excel как =SUM(D2:D100). Движок не трогает обычные формулы, и такую формулу легче читать. Используйте префикс, когда часть формулы должна браться из данных.
Не ставьте плейсхолдер-выражение внутрь ячейки с префиксом формулы. {{=}}SUM(D2:D{{=1 + itemCount}}) не даёт формулу: движок находит внутренний {{=...}}, вычисляет его и заменяет результатом всю ячейку — в итоге в ячейке просто число. Используйте обычный плейсхолдер, который уже содержит нужное значение, а если значение надо вывести, посчитайте его в поле-выражении записи.
Тот же префикс работает на листе _data, где с его помощью вычисляются выражения фильтров, выбирающие записи для отчёта.

Формула или вычисленное значение

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

{{=}}SUM(D2:{{lastRow}})

Префикс формулы — обратите внимание на закрывающие скобки сразу после = и на то, что остальная часть ячейки по-прежнему шаблон. Записывает в ячейку живую формулу. Расчёт ведёт Excel; читатель может изменить входное значение и увидеть, как за ним меняется итог.

{{=quantity * unitPrice}}

Плейсхолдер-выражение — выражение стоит внутри скобок. quantity и unitPrice — машинные имена полей типа сущности; выражение вычисляется как JavaScript по данным записи и записывается как статичное значение. В результате в ячейке число; формулы за ним нет.

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

Вычисление формул на сервере

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

Если книга слишком велика, чтобы вычислить её за разумное время, движок останавливается и помечает книгу для пересчёта при открытии. Файл всё равно доставляется и остаётся корректным — арифметику просто выполняет Excel, когда читатель открывает файл. Заметная разница — короткий пересчёт при открытии и устаревшие на вид значения, пока он не закончится.

Функция DATEDIF

DATEDIF вычисляется на сервере, как и любая другая формула.

DATEDIF считает разницу между двумя датами в целых единицах:

Единица Значение

"Y"

Полных лет между двумя датами.

"M"

Полных месяцев между двумя датами.

"D"

Дней между двумя датами.

Пример:

=DATEDIF(A2, B2, "M")

Если A2 — 2025-01-15, а B2 — 2025-09-20, результат — 8 (восемь полных месяцев).

Если начальная дата позже конечной, DATEDIF возвращает ошибку #NUM!, как и в Excel.

Разделение ячейки символом вертикальной черты

Одна ячейка шаблона может дать несколько ячеек результата, если использовать символ вертикальной черты (|) как разделитель.

Разделение выполняется по тексту шаблона, до разрешения любых плейсхолдеров. Движок режет ячейку по первой черте:

  • текст до черты остаётся в текущей ячейке,

  • текст после черты попадает в новую ячейку, вставленную справа, а существующие ячейки сдвигаются,

  • затем обе половины обрабатываются снова, так что ячейка с несколькими чертами делится, пока черт не останется.

Поскольку разрез делается до разрешения, черта, которая приходит внутри значения, ничего не разделяет — делит только черта, набранная в шаблоне.

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

Пример:

Допустим, шаблон привязан к типу сущности, среди полей которого есть displayName, address и city — каждое из них — машинное имя поля типа сущности. Одна ячейка в шаблоне превращается в три в результате:

Шаблон
A

1

{{displayName}}|{{address}}|{{city}}
Результат
A B C

1

Tverskaya 12

1 Tverskaya St

Moscow

Ячейки, которые уже стоят справа, сдвигаются, а не перезаписываются.

Форматирование и формулы сохраняются при повторении строк

Когда повторяющийся раздел дублирует строки (см. повторяющиеся разделы), в дублированных строках сохраняются:

  • Стили ячеек — шрифты, цвета, границы, числовые форматы и условное форматирование остаются нетронутыми.

  • Формулы ячеек — формулы из строки шаблона копируются в каждую дублированную строку как есть.

Значит, если в строке шаблона столбец цены имеет формат #,##0.00, а столбец итога содержит =C5*D5, в повторённых строках каждая цена отформатирована одинаково, а каждая формула итога сохранена.

Ссылки на ячейки Excel в скопированных формулах не корректируются автоматически. Формула =C5*D5 в строке шаблона останется =C5*D5 в каждой повторённой строке — она не сдвинется на =C6*D6, =C7*D7 и так далее.
Строка шаблона 5
C D E

5

{{quantity}}

{{unitPrice}}

=C5*D5
Что даёт повторение
C D E

5

10

4 500

=C5*D5

6

4

7 200

=C5*D5

7

25

1 100

=C5*D5

Теперь каждая строка показывает итог первой строки. Если расчёт должен следовать за каждой строкой, используйте вместо этого плейсхолдер-выражение — он вычисляется для каждого элемента и поэтому верен в каждой строке:

{{=quantity * unitPrice}}

Устойчивость к ошибкам

Движок XLSX изолирует ошибки на двух уровнях, чтобы одна проблема не ломала всю книгу.

На уровне ячейки

Если плейсхолдер или выражение в одной ячейке не сработали, движок записывает в эту ячейку маркер ошибки — ERR:, за которым следуют тип и текст ошибки, — и продолжает обработку остальных ячеек. Все остальные ячейки листа формируются как обычно.

На уровне листа

Если лист не удалось сформировать целиком — например, из-за структурной проблемы в шаблоне, — движок записывает в ячейку A1 этого листа RENDER ERROR, за которым следуют название листа и сведения об ошибке, и продолжает с остальными листами. Все остальные листы книги формируются как обычно.

В обоих случаях книга всё равно создаётся и доставляется. Маркеры ошибок делают проблемы видимыми в результате.

Книги из нескольких листов

В шаблоне XLSX может быть любое число листов. Каждый лист обрабатывается независимо:

  • Листы с плейсхолдерами проходят через движок шаблонов.

  • Листы без плейсхолдеров передаются без изменений — в результате они выглядят точно так же, как в шаблоне.

Значит, в одной книге шаблон может сочетать динамические листы (заполняемые из данных) со статичными (справочные таблицы, инструкции или руководства по оформлению).

Зарезервированный лист _data обрабатывается отдельно и удаляется из результата. Подробности о дополнительных источниках данных — в разделе Лист _data.

Корневой и родительский контекст во вложенных разделах

Внутри повторяющегося раздела плейсхолдеры разрешаются относительно текущего элемента. Чтобы добраться до полей окружающей записи, в шаблонах XLSX поддерживается тот же синтаксис контекста, что и в DOCX и PPTX:

  • {{$.fieldName}} — корневой контекст (запись верхнего уровня) при любой глубине вложенности.

  • {{../fieldName}} — родительский контекст (на один уровень выше).

Вложенные коллекции в XLSX

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

Пример — кампании с размещениями:

В этом примере у типа сущности есть поле-коллекция campaigns (машинное имя). У каждой кампании есть поле campaignName и своя вложенная коллекция placements. У каждого размещения есть поля displayName, address и price — все это машинные имена, определённые у соответствующих типов сущностей (см. вложенные сущности):

Шаблон
A B C

3

{{#campaigns}}

4

Campaign: {{campaignName}}

5

{{#placements}}

6

{{displayName}}

{{address}}

{{price}}

7

{{/placements}}

8

{{/campaigns}}

Строки с тегами (3, 5, 7, 8) удаляются. Строка 4 повторяется для каждой кампании; строки 5—​7 разворачивают размещения внутри каждой кампании. Строки ниже строки 8 сдвигаются вниз, освобождая место для добавленного содержимого.

Полный синтаксис и другие схемы — в разделе повторяющиеся разделы.

Усечение длинного текста

Максимальная длина ячейки Excel — 32 767 символов. Если плейсхолдер разрешается в значение длиннее этого предела, движок усекает текст до 32 767 символов.

Выходной файл создаётся как обычно. Это ограничение самого формата файлов Excel, и его нельзя повысить.

Изображения на листах

Плейсхолдеры-изображения работают в шаблонах XLSX так же, как в DOCX и PPTX. Фигура на листе, весь текст которой — тег плейсхолдера (например, {{displayPhoto}}, где displayPhoto — машинное имя поля «Файл/Изображение» в типе сущности), заменяется изображением, если значение поля — ссылка на изображение.

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

Инструкции по настройке, поддерживаемые форматы и диагностика — в разделе плейсхолдеры-изображения.

Сводка по особенностям XLSX

Возможность Поведение

Типы ячеек

Значения записываются как числа, логические значения, даты или текст.

Автоформат дат

dd.MM.yyyy применяется к ячейкам с форматом «Общий»; пользовательские форматы сохраняются.

Живые формулы

Обычные формулы Excel сохраняются; префикс {{=}} строит формулу из данных.

Вычисление формул

Формулы вычисляются на сервере; при необходимости переходят на пересчёт при открытии.

DATEDIF

DATEDIF(start, end, unit) с единицами "Y", "M", "D"; вычисляется на сервере.

Разделение ячеек

Символ вертикальной черты (|) делит одну ячейку шаблона на несколько ячеек результата.

Повторение строк

Стили ячеек и формулы копируются в каждую повторённую строку.

Устойчивость к ошибкам

Изоляция на уровне ячейки и листа; маркеры ошибок в результате.

Несколько листов

Каждый лист обрабатывается независимо; статичные листы передаются как есть; временные листы удаляются.

Доступ к контексту

$. — корень, ../ — родитель; вложенные коллекции поддерживаются с заранее рассчитанными сдвигами строк.

Усечение текста

Значения длиннее 32 767 символов усекаются.

Изображения

Замена фигур изображениями, как в DOCX и PPTX.

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