Выражения и форматирование

Плейсхолдер-выражение вычисляет выражение JavaScript на месте и вставляет результат. Он записывается со знаком равенства после открывающих скобок:

{{=price * quantity}}

Имена переменных внутри выражения — price, quantity — это машинные имена полей типа сущности, к которому привязан шаблон. Плейсхолдеры-выражения работают во всех трёх форматах шаблонов (DOCX, XLSX, PPTX).

Плейсхолдеры-выражения вычисляет движок шаблонов при формировании документа. Их нужно отличать от полей-выражений, которые вычисляются и хранятся в самом типе сущности и приходят в шаблон уже посчитанными — для них достаточно простого {{total}}.

Когда нужны выражения

Плейсхолдер-выражение нужен, когда требуется:

  • вычислить значение, которое не хранится в поле, — например, сумму по позиции из цены за единицу и количества,

  • отформатировать число или дату особым образом — например, показать цену как 1,250.00 или дату как 2025-03-15,

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

Простой вставки поля ({{fieldName}}) достаточно, когда значение должно выводиться как хранится. Выражения нужны там, где значение надо вычислить или особым образом отформатировать.

Синтаксис выражений

Выражение между {{= и }} вычисляется как JavaScript. Все поля текущего контекста доступны как переменные — имя каждой переменной — это машинное имя поля типа сущности.

В примерах ниже предполагается, что шаблон привязан к типу сущности, среди полей которого есть price (дробное), quantity (целое) и invoiceNumber (строка) — все это машинные имена:

Выражение Результат (при price = 50, quantity = 3)

{{=price * quantity}}

150

{{=price > 100 ? 'Premium' : 'Standard'}}

Standard

{{='Invoice #' + invoiceNumber}}

Invoice #2024-0042

Доступны стандартные операторы и встроенные функции JavaScript: арифметика (`, `-`, `*`, `/`, `%`), сравнение (`>`, `<`, `===`), тернарный оператор (`? :`), конкатенация строк (`) и функции Math (Math.round, Math.max и другие).

До чего достаёт выражение

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

Функции форматирования

Внутри плейсхолдеров-выражений через объект fmt доступны три функции форматирования.

fmt.number(value, pattern)

Форматирует число по шаблону-строке. В шаблоне используются такие символы:

Символ шаблона Значение

0

Обязательная цифра — выводится всегда, даже если это ноль.

#

Необязательная цифра — выводится, только если в этой позиции у числа есть цифра.

,

Разделитель групп (тысяч).

.

Десятичный разделитель.

Примеры (с машинными именами полей price, rate, quantity и ratio текущего типа сущности):

Выражение Входное значение Результат

{{=fmt.number(price, '#,##0.00')}}

1250

1,250.00

{{=fmt.number(rate, '0.0##')}}

3.5

3.500

{{=fmt.number(quantity, '#,##0')}}

48000

48,000

{{=fmt.number(ratio, '0.00')}}

0.753

0.75

fmt.date(value, pattern)

Форматирует дату по шаблону-строке. В шаблоне используются такие символы:

Символ шаблона Значение

yyyy

Год из четырёх цифр.

yy

Год из двух цифр.

MM

Месяц из двух цифр (01—​12).

dd

День из двух цифр (01—​31).

HH

Час из двух цифр, 24-часовой формат (00—​23).

mm

Минуты из двух цифр (00—​59).

ss

Секунды из двух цифр (00—​59).

Примеры (где startDate, createdAt и signedOn — машинные имена полей типа «Дата-время» в типе сущности):

Выражение Результат

{{=fmt.date(startDate, 'dd.MM.yyyy')}}

15.03.2025

{{=fmt.date(startDate, 'yyyy-MM-dd')}}

2025-03-15

{{=fmt.date(createdAt, 'dd.MM.yyyy HH:mm')}}

15.03.2025 14:30

{{=fmt.date(signedOn, 'MM/dd/yyyy')}}

03/15/2025

fmt.currency(value)

Сокращённая запись для fmt.number(value, '#,##0.00'). Она форматирует число с двумя знаками после запятой и разделителем групп тысяч.

{{=fmt.currency(totalCost)}}

Здесь totalCost — машинное имя поля типа «Дробное» в типе сущности. Если его значение равно 48250, результат — 48,250.00.

Эта функция не добавляет символ валюты. Если символ нужен, припишите его в выражении:

{{='$' + fmt.currency(totalCost)}}

Автоформатирование

Когда значение вставляется простым плейсхолдером ({{fieldName}}), система автоматически форматирует некоторые типы данных:

  • Даты форматируются как dd.MM.yyyy — например, 15.03.2025.

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

Автоформатирование действует только для простых плейсхолдеров. Плейсхолдеры-выражения возвращают необработанный результат вычисления JavaScript — когда в выражении нужен форматированный вывод, используйте fmt.number или fmt.date.

Выражения и формулы XLSX

В шаблонах XLSX плейсхолдеры-выражения и формулы Excel служат разным целям:

  • Плейсхолдер-выражение ({{=price * quantity}}) вычисляется движком шаблонов при формировании и записывает в ячейку статическое значение.

  • Формула Excel (=A2*B2) сохраняется в итоговом файле, и Excel пересчитывает её при открытии файла.

Если нужно, чтобы в ячейке итогового файла была живая формула Excel, запишите её в ячейке шаблона как обычную формулу Excel, а не как плейсхолдер-выражение.

Чтобы построить формулу, диапазон которой зависит от данных, начните ячейку с префикса формулы {{=}} и запишите формулу после него — остаток по-прежнему остаётся шаблоном, и в этом весь смысл префикса. Обратите внимание на закрывающие скобки: {{=}}SUM(D2:{{lastRow}}) — это формула, а {{=price * quantity}} — выражение JavaScript. Формуле с фиксированным диапазоном префикс не нужен вообще — введите её в ячейку как =SUM(D2:D100), и движок её не тронет.

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

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