Подстановки {{ … }}

предупреждение

В этой статье описано использование подстановок в проектах с движком версии 2. Подстановки для этой версии реализованы на основе Pebble Templates.

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

Доступные данные

• previousResult — результат выполнения предыдущего блока: функции или агента.

• Данные запроса, отправленного клиентом (набор полей может отличаться в зависимости от канала):

  Имя	Описание
  request.query	Текст запроса
  request.requestId	Идентификатор запроса
  request.botId	Идентификатор канала
  request.channelType	Тип канала (telegram, chatwidget, …)
  request.channelTypeIsAsync	Асинхронный ли канал
  request.isTestChannel	Тестовый ли канал
  request.chatId	Идентификатор чата
  request.sessionId	Идентификатор сессии
  request.clientInfo.id	ID клиента
  request.clientInfo.firstName	Имя клиента
  request.clientInfo.lastName	Фамилия клиента

  Пример:

  Здравствуйте, {{ request.clientInfo.firstName }}! Канал: {{ request.channelType }}

• Ключи, установленные с помощью встроенной функции Context.set(key, value), доступны по имени:

  // В коде:
  Context.set({key: "name", value: "Alice" });
  Context.set({key: "address", value: { "city": "Moscow" }});

  {{ name }} → Alice
  {{ address.city }} → Moscow

Подстановки, которые не удалось разрешить, остаются в строке «как есть».

Синтаксис подстановок

Синтаксис	Описание	Пример
{{ variable }}	Переменная, см. Доступные данные выше	{{ name }} → Alice
{{ a.b.c }}	Доступ по вложенному пути	{{ user.address.city }} → Berlin
{{ list[0] }}	Доступ по индексу массива	{{ items[1] }} → beta
{{ map["key"] }}	Доступ по строковому ключу	{{ headers["Content-Type"] }} → application/json
{{ a + b }}	Арифметика (+, -, *, /, %)	{{ price * qty }} → 30
{{ a >= b }}	Сравнение (==, !=, >, <, >=, <=)	{{ age >= 18 }} → true
{{ a and b }}	Логические операторы (and, or, not)	{{ a and b }} → false
{{ a ~ " " ~ b }}	Конкатенация строк (оператор ~)	{{ first ~ " " ~ last }} → John Doe
{{ val | filter }}	Применение фильтра	{{ name | upper }} → ALICE См. Фильтры
{{ val | f1 | f2 }}	Цепочка фильтров	{{ name | trim | upper }} → ALICE
{% if %}...{% endif %}	Условный блок	См. Условия и циклы
{% for %}...{% endfor %}	Цикл	См. Условия и циклы
{{ "literal" }}	Строковый литерал	{{ "hello" }} → hello
{{ 42 }}	Числовой литерал	{{ 42 }} → 42

Фильтры

Встроенные фильтры Pebble

Фильтр	Описание	Пример
upper	Верхний регистр	{{ name | upper }} → ALICE
lower	Нижний регистр	{{ name | lower }} → alice
capitalize	Первая буква заглавная	{{ name | capitalize }} → Alice
trim	Удаление пробелов по краям	{{ text | trim }} → hello
title	Каждое слово с заглавной	{{ text | title }}
default(val)	Значение по умолчанию (если null)	{{ name | default("Guest") }} → Guest
first	Первый элемент коллекции	{{ items | first }}
last	Последний элемент коллекции	{{ items | last }}
join(sep)	Объединение коллекции в строку	{{ items | join(", ") }} → a, b, c
split(sep)	Разбиение строки в список	{{ text | split(",") }}
reverse	Обратный порядок	{{ items | reverse }}
sort	Сортировка	{{ items | sort }}
slice(from, to)	Подмассив	{{ items | slice(0, 2) }}
replace(map)	Замена подстрок	{{ text | replace({"old": "new"}) }}
length	Длина строки/коллекции	{{ items | length }} → 3

Фильтры Agent Platform

Фильтр	Описание	Пример
json	Сериализация значения в JSON-строку	{{ obj | json }} → {"key":"value"}
parseJson	Парсинг JSON-строки в объект	{{ '{"a":1}' | parseJson }}
string	Приведение к строке (пустая строка для null)	{{ count | string }}
truncate(length, suffix?)	Обрезка строки до указанной длины с добавлением суффикса (по умолчанию ...), который учитывается в длине	{{ text | truncate(12) }} → Once upon...

Условия и циклы

Условный блок {% if %}

{% if age >= 18 %}adult{% else %}minor{% endif %}

Поддерживаются вложенные {% elseif %}:

{% if score >= 90 %}отлично{% elseif score >= 70 %}хорошо{% else %}удовлетворительно{% endif %}

Условие может быть любым выражением, включая логические операторы:

{% if show %}visible{% endif %}

предупреждение

Шаблоны с управляющими блоками {% %} вычисляются целиком, а не по отдельным выражениям. Неизвестные переменные внутри таких блоков трактуются как null/false.

Цикл {% for %}

{% for item in items %}{{ item }},{% endfor %}

Внутри цикла доступна переменная loop:

Переменная	Описание
loop.index	Индекс текущей итерации (с 0)
loop.length	Общее количество элементов
loop.first	true для первой итерации
loop.last	true для последней итерации

Пример с индексом:

{% for item in items %}{{ loop.index }}:{{ item }},{% endfor %}

При items = ["x", "y"] результат: 0:x,1:y,.

Примеры

Инструкция агента

Ты — ассистент службы поддержки {{ companyName }}.

Текст TTS с условиями

{% if request.clientInfo.firstName %}Здравствуйте, {{ request.clientInfo.firstName }}!
{% else %}Здравствуйте!{% endif %} Чем могу помочь?

JavaScript-код

const count = {{ items | length }}

Фильтрация и форматирование

Описание: {{ description | truncate(200) }}
Данные: {{ previousResult | json }}