Справочник по функциям шаблонизации
В конструкции обращения к параметрам контекста (шаблонизации) доступны различные функции работы со строками, числами и датами.
Принцип их использования похож на стандартное обращение к параметрам контекста, однако перед аргументами нужно указать название функции. Например {{ wrapName last_name }}. Данная конструкция вызовет функцию wrapName, в которую передаст параметр last_name. В ответ мы получим содержимое параметра last_name, но первая буква у него будет заглавная, остальные — строчные.
Общая конструкция вызова функций: {{ function_name arg1 arg2 ... argN }}, количество аргументов зависит от функции.
Как передавать аргументы
Чтобы функции отрабатывали корректно, важно правильно указывать аргументы:
- Источник данных (первый аргумент) указывается именем параметра контекста, без кавычек. Например
{{ trim address }}, а не{{ trim 'текст' }}. Если передать первым аргументом текст в кавычках, функция вернёт пустое значение. - Текст в кавычках используется только для аргументов-настроек: шаблон поиска и замены, формат даты, единица измерения, разделитель и т. п.
- Числовые аргументы (номера символов, индексы) указывайте без кавычек.
- Исключение — функции работы с датами (
parseDt,addDate,subtractDate,isBefore,isAfter) и функцияdefaultIsNull: в них значение можно передать как параметром контекста, так и текстом в кавычках.
В настоящий момент поддерживаются следующие функции:
| Тип | Функция | Описание | Пример | Пример преобразования |
|---|---|---|---|---|
| Строковые | wrapName | Принимает параметр строки, в результате превращает первую букву в заглавную, остальные — строчные | {{ wrapName last_name }} | ИВАНОВ → Иванов |
| trim | Удаляет пробелы, табуляции и переносы строк только в начале и конце строки. Другие символы (например «+») функция не удаляет. | {{ trim address }} | " Улица Пушкина, 12 " → "Улица Пушкина, 12" | |
| replace | Заменяет в строке все совпадения с шаблоном поиска. 1 — параметр контекста с исходной строкой. 2 — шаблон поиска. Это регулярное выражение, поэтому спецсимволы (плюс, точка, звёздочка, вопрос, скобки и т. п.) нужно экранировать обратным слэшем — например, плюс записывается как '\+' (в одинарных кавычках). 3 — текст замены, указывается в кавычках (пустые кавычки '' удаляют найденное). | {{ replace phone '\+' '' }}{{ replace text 'N' '20' }} | +79991234567 → 79991234567 «Скидка N%» → «Скидка 20%» | |
| substring | Возвращает фрагмент строки по номерам символов (нумерация с 0). 1 — параметр контекста с исходной строкой. 2 — номер первого символа фрагмента. 3 — номер символа, перед которым фрагмент заканчивается. Номера указывайте без кавычек и задавайте оба значения. | {{ substring phone 1 12 }} | +79991234567 → 79991234567 | |
| toLowerCase | Принимает параметр контекста. Возвращает строку в нижнем регистре. | {{ toLowerCase address }} | ВНИМАНИЕ → внимание | |
| toUpperCase | Принимает параметр контекста. Возвращает строку в верхнем регистре. | {{ toUpperCase address }} | внимание → ВНИМАНИЕ | |
| defaultIsNull | Принимает 2 значения. Если значение 1 существует — возвращается оно. Если его нет или это пустая строка — возвращается значение 2. Здесь оба значения можно задавать как параметром контекста, так и текстом в кавычках. | {{ defaultIsNull a 'default' }}{{ defaultIsNull a b }} | Если a не существует — вернётся default Если a не существует — будет взято значение b | |
| cutWords | Отрезает указанное количество слов, начиная с заданного индекса. 1 — параметр контекста со строкой (слова разделены пробелами). 2 — номер слова, с которого начать (индексация с 0). 3 — количество слов в результате. | {{ cutWords string 2 1 }} | "Один два три четыре" → "три" | |
| countWords | Возвращает количество слов в строке. Принимает параметр контекста. | {{ countWords string }} | "Один два три четыре" → 4 | |
| countUniqueValues | Возвращает количество уникальных значений в строке. Принимает параметр контекста — строку значений, разделённых запятой. | {{ countUniqueValues array }} | 1,2,3,4,1,1,3 → 4 | |
| stringDistance | Определяет лексикографическое расстояние между строками. Поддерживается 5 алгоритмов, результат зависит от выбранного. 1 — параметр контекста, первая строка. 2 — параметр контекста, вторая строка. 3 — номер алгоритма (от 1 до 5). | {{ stringDistance strA strB 3 }} | Алгоритмы 1, 2 и 5 не чувствительны к регистру. 1. Расстояние Хэмминга — количество различных символов в строках одинаковой длины. Чем меньше, тем ближе строки. (100 / 100 → 3) 2. Джаро-Уинклер — число от 0 до 1 (0 — нет совпадения, 1 — точное). (dixon / dicksonx → 0.746…) 3. Левенштейн — чем больше, тем больше различие. (памятка / память → 2) 4. Дамерау-Левенштейн (огранич.) — учитывает перестановку соседних символов. (памятка / памякта → 1) 5. Коэффициент Дайса — от 0 (нет совпадения) до 1 (точное). (вещь / вещдок → 0.5) | |
| slice | Берёт диапазон элементов из строки с разделителями. 1 — параметр контекста, строка значений с разделителями. 2 — начало диапазона (можно отрицательное — отсчёт с конца), по умолчанию 0. 3 — конец диапазона (можно отрицательное); если не указан — до предпоследнего элемента. 4 — разделитель в кавычках, по умолчанию запятая. Рекомендуется указывать и начало, и конец диапазона. | {{ slice array 0 4 }}{{ slice array 4 -1 ';' }} | 1,2,3,4,5,6,7 → 1,2,3,4 1;3;4;2;1;14;11;4;5 → 1;14;11;4 | |
| random | Вызывает методы библиотеки faker версии 7. Первый параметр — модуль, второй — метод модуля. <https://v7.fakerjs.dev/api/> | {{ random datatype uuid }}{{ random address city }} | ||
| Числовые | mathStd | Среднее квадратичное отклонение ряда чисел. На вход — параметр контекста со строкой чисел, разделённых запятой без пробела. | {{ mathStd array }} | 12,100,141,300 → 104.37 |
| mathAvg | Среднее арифметическое ряда чисел (результат округляется до целого). На вход — параметр контекста со строкой чисел, разделённых запятой без пробела. | {{ mathAvg array }} | 12,100,141,300 → 138.00 | |
| Дата | parseDt | Форматирование даты. Принимает 3 параметра: date — дата строкой (можно как параметр контекста, так и текстом в кавычках). Можно указать now — будет взята текущая дата. fromFormat — формат входной даты (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). toFormat — формат результата (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). Токены форматирования — в таблице ниже. | {{ parseDt '2021-10-10 10:14:21' 'YYYY-MM-DD HH:mm:ss' 'YYYY/DD/MM' }}{{ parseDt 'now' 'YYYY-MM-DD HH:mm:ss' 'HH:mm:ss' }} | 2021-10-10 10:14:21 → 2021/10/10 текущая дата → 13:14:21 |
| getUnit | Получение элемента даты. Принимает 3 параметра: date — параметр контекста с датой, либо now для текущей даты. unit — элемент даты: year, month (от 0 до 11), day, date, hour, minute, second, millisecond. format — формат входной даты (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). | {{ getUnit date 'minute' }}{{ getUnit 'now' 'month' }} | при date = 2021-10-10 10:14:21 → 14 | |
| dateDiff | Разница между двумя датами (вычисляется как date1 − date2). Принимает 4 параметра: date1, date2 — параметры контекста с датами. unit — единица: years, months, weeks, days, hours, minutes, seconds. format — формат входных дат (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). | {{ dateDiff date_end date_start 'days' 'YYYY-MM-DD' }} | date_end = 2021-10-21, date_start = 2021-10-10 → 11 | |
| addDate | Прибавить к дате период. Принимает 4 параметра: date — дата (можно как параметр контекста, так и текстом в кавычках). number — на сколько увеличить. unit — единица: year, month, day, date, hour, minute, second, millisecond. format — формат входной и выходной даты (по умолчанию YYYY-MM-DD HH:mm:ss.SSS). | {{ addDate '2023-01-12 10:00:13' '5' 'second' 'YYYY-MM-DD HH:mm:ss' }} | 2023-01-12 10:00:13 → 2023-01-12 10:00:18 | |
| subtractDate | Вычесть из даты период. Параметры — как у addDate. | {{ subtractDate '2023-01-12 10:00:13' '10' 'minute' 'YYYY-MM-DD HH:mm:ss' }} | 2023-01-12 10:00:13 → 2023-01-12 09:50:13 | |
| isAfter | Возвращает true, если date1 позже date2, иначе false. Даты можно задавать как параметром контекста, так и текстом в кавычках. Третий аргумент — формат даты (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). | {{ isAfter 'now' '2023-01-12 10:00:13' }}{{ isAfter '2020-10-10 10:00:13' '2022-01-12 10:00:13' 'YYYY-MM-DD HH:mm:ss.SSS' }} | true false | |
| isBefore | Возвращает true, если date1 раньше date2, иначе false. Даты можно задавать как параметром контекста, так и текстом в кавычках. Третий аргумент — формат даты (опционально, по умолчанию YYYY-MM-DD HH:mm:ss.SSS). | {{ isBefore 'now' '2023-01-12 10:00:13' }}{{ isBefore '2023-10-10 10:00:13' '2022-01-12 10:00:13' 'YYYY-MM-DD HH:mm:ss.SSS' }} | true false | |
| Массив | array | Обращение к элементу массива из контекста по индексу (нумерация с 0). | {{ array.1 }} | ['A', 'B', 'C', 'D'] → B |
| toArray | Переводит строку в массив, разбивая её по разделителю (по умолчанию запятая). На вход — параметр контекста со строкой. | {{ toArray context_string }} | a,b,c → массив [a, b, c] |
Токены для форматирования даты (для функций parseDt, getUnit, addDate, subtractDate, dateDiff):
| Токен | Вывод | |
|---|---|---|
| Месяц | M | 1 2 .. 11 12 |
| MM | 01 02 .. 11 12 | |
| MMM | январь февраль .. декабрь | |
| Квартал | Q | 1 2 3 4 |
| День месяца | D | 1 2 .. 30 31 |
| DDDD | 01 02 .. 30 31 | |
| День года | DDD | 1 2 .. 364 365 |
| DDDD | 001 002 .. 364 365 | |
| День недели | d | 0 1 .. 5 6 |
| dd | пн вт .. сб вс | |
| dddd | понедельник ... воскресенье | |
| Неделя в году | w | 1 2 .. 52 53 |
| ww | 01 02 .. 52 53 | |
| Год | YY | 70 71 .. 29 30 |
| YYYY | 1970 1971 .. 2029 2030 | |
| Час | H | 0 1 .. 22 23 |
| HH | 00 01 .. 22 23 | |
| h | 1 2 .. 11 12 | |
| hh | 01 02 .. 11 12 | |
| Минута | m | 0 1 .. 58 59 |
| mm | 00 01 .. 58 59 | |
| Секунда | s | 0 1 .. 58 59 |
| ss | 00 01 .. 58 59 | |
| Миллисекунда | SSS | 000 001 .. 998 999 |
| Временная зона | Z | -07:00 -06:00 .. +06:00 +07:00 |
| ZZ | -0700 -0600 .. +0600 +0700 | |
| Unix timestamp | X | 1360013296 |