TypeScript JSON Builder
TypeScript JSON Builder — это npm-пакет @divkitframework/jsonbuilder для описания верстки DivKit на TypeScript. Он предназначен для бэкенда на Node.js: карточка описывается объектами в коде, а библиотека формирует из них JSON для клиента. Классы и типы библиотеки сгенерированы из схемы DivKit, поэтому ошибки в названиях и типах свойств обнаруживает компилятор.
Исходный код библиотеки опубликован на GitHub. Аналогичный инструмент для Kotlin описан на странице Kotlin DSL.
Установка
Установите пакет из npm:
npm install @divkitframework/jsonbuilder
В пакет входят сборки в форматах CommonJS и ES-модулей и описания типов TypeScript.
Создание карточки
Карточку собирает функция divCard. Первый аргумент — шаблоны (пустой объект, если шаблонов нет), второй — объект со структурой div-data. Элементы верстки создаются через конструкторы классов DivText, DivContainer, DivImage и других. Имена свойств совпадают с именами в JSON.
import { divCard, DivText } from '@divkitframework/jsonbuilder';
const card = divCard({}, {
// Идентификатор карточки, обязательное свойство.
log_id: 'hello_card',
states: [
{
state_id: 0,
// Карточка состоит из одного текстового элемента.
div: new DivText({
font_size: 18,
text: 'Hello, world!',
}),
},
],
});
// Сериализация карточки в JSON.
const json = JSON.stringify(card);
Результат сериализации (отформатирован для удобства чтения):
{
"templates": {},
"card": {
"log_id": "hello_card",
"states": [
{
"state_id": 0,
"div": {
"type": "text",
"font_size": 18,
"text": "Hello, world!"
}
}
]
}
}
Полученную строку остается передать клиенту. Пример бэкенда, который отдает верстку, и способ посмотреть результат в демо-приложении описаны в инструкции по развертыванию простого бэкенда.
Шаблоны
Шаблоны описываются объектом, в котором ключ — имя шаблона, а значение — элемент или другой шаблон. Параметр шаблона объявляет функция reference: ее вызов ставится на место значения свойства. Элемент из шаблона создает функция template, она принимает имя шаблона и значения его параметров и свойств.
import {
divCard,
DivContainer,
DivText,
reference,
rewriteRefs,
template,
templateHelper,
wrapContent,
} from '@divkitframework/jsonbuilder';
const templates = {
// Шаблон title на основе текстового элемента.
title: new DivText({
font_size: 18,
width: wrapContent(),
// Значение свойства text задается параметром title_text.
text: reference('title_text'),
}),
// Шаблон greeting использует шаблон title.
greeting: new DivContainer({
items: [
template('title', {
// Параметр title_text получает значение параметра greeting_text.
title_text: reference('greeting_text'),
}),
template('title', {
title_text: 'Hello, DivKit!',
// Переопределение свойства шаблона.
font_size: 14,
}),
],
}),
};
Перед передачей в divCard шаблоны нужно обработать функцией rewriteRefs. Она возвращает копию шаблонов, в которой вызовы reference заменены на свойства с префиксом $. Без этого параметры шаблонов попадут в JSON в неверном виде.
Функция templateHelper возвращает объект с функцией для каждого шаблона. Вызов tHelper.greeting({...}) равнозначен вызову template('greeting', {...}), но имя шаблона проверяет компилятор.
const tHelper = templateHelper(templates);
const card = divCard(rewriteRefs(templates), {
log_id: 'template_card',
states: [
{
state_id: 0,
// Создание элемента из шаблона greeting.
div: tHelper.greeting({
// Значение параметра шаблона.
greeting_text: 'Hello, world!',
}),
},
],
});
Шаблоны попадают в секцию templates, а карточка — в секцию card:
{
"templates": {
"title": {
"type": "text",
"font_size": 18,
"width": {
"type": "wrap_content"
},
"$text": "title_text"
},
"greeting": {
"type": "container",
"items": [
{
"type": "title",
"$title_text": "greeting_text"
},
{
"type": "title",
"title_text": "Hello, DivKit!",
"font_size": 14
}
]
}
},
"card": {
"log_id": "template_card",
"states": [
{
"state_id": 0,
"div": {
"type": "greeting",
"greeting_text": "Hello, world!"
}
}
]
}
}
Примечание
Если имя параметра в reference совпадает с именем свойства, свойство с префиксом $ в шаблон не добавляется. Значение такого свойства задается при использовании шаблона напрямую, по имени свойства.
Отбор используемых шаблонов
Если набор шаблонов общий для многих карточек, в JSON можно включить только те шаблоны, которые нужны конкретной карточке. Для этого есть две функции:
thelperWithMemoвозвращает объектthelper, который используется так же, как результатtemplateHelper, и множествоusedс именами вызванных шаблонов. Используйтеthelperтолько при сборке карточки: вызовы внутри описаний шаблонов функцияtemplatesDepsMapне видит.templatesDepsMapдля каждого шаблона возвращает список шаблонов, от которых он зависит, включая его самого. Если шаблон использует необъявленный шаблон или зависимости образуют цикл, функция бросает исключение.
Пример продолжает предыдущий:
import { templatesDepsMap, thelperWithMemo } from '@divkitframework/jsonbuilder';
const { thelper, used } = thelperWithMemo<typeof templates>();
const cardData = {
log_id: 'title_card',
states: [
{
state_id: 0,
div: thelper.title({ title_text: 'Hello, world!' }),
},
],
};
// Шаблоны, вызванные при сборке карточки, и их зависимости.
const deps = templatesDepsMap(templates);
const names = new Set([...used].flatMap((name) => deps[name]));
const usedTemplates = Object.fromEntries(
Object.entries(templates).filter(([name]) => names.has(name)),
);
// В секцию templates попадет только шаблон title.
const titleCard = divCard(rewriteRefs(usedTemplates), cardData);
Переменные и выражения
Переменные объявляются в свойстве variables с помощью классов StringVariable, IntegerVariable, BooleanVariable и других. Чтобы задать свойству вычисляемое выражение, передайте строку с выражением через функцию expression. Ее результат принимают только те свойства, которые поддерживают выражения.
import { divCard, DivText, expression, StringVariable } from '@divkitframework/jsonbuilder';
const card = divCard({}, {
log_id: 'variables_card',
// Объявление переменных.
variables: [
new StringVariable({ name: 'user_name', value: 'DivKit' }),
],
states: [
{
state_id: 0,
div: new DivText({
// Константное свойство.
font_size: 18,
// Вычисляемое свойство.
text: expression('Hello, @{user_name}!'),
}),
},
],
});
Экранирование строк
При сериализации результата divCard обычные строки экранируются: @{ заменяется на \@{, а \ — на \\. Поэтому текст из внешних источников не вычисляется на клиенте как выражение, а отображается как есть. По той же причине выражение, переданное обычной строкой без expression, вычислено не будет.
Строки, созданные функцией expression, попадают в JSON без изменений. Чтобы вставить в выражение произвольный текст, экранируйте его функцией escapeExpression.
import { DivText, escapeExpression, expression } from '@divkitframework/jsonbuilder';
const comment = 'Type @{name} here';
const items = [
// Обычная строка. В JSON: "Type \\@{name} here", на экране: Type @{name} here
new DivText({ text: comment }),
// Выражение с произвольным текстом. В JSON: "Type \\@{name} here: @{user_name}"
new DivText({ text: expression(`${escapeExpression(comment)}: @{user_name}`) }),
];
Проверка типов и значений
Компилятор TypeScript проверяет:
- названия свойств элементов и других объектов верстки;
- типы значений, допустимые значения перечислений и наличие обязательных свойств;
- что результат
expressionпередан в свойство, которое поддерживает выражения; - имена шаблонов при вызове функций
templateHelper. Параметры шаблона при этом не проверяются.
Сущности схемы, у которых есть свойство type, представлены классами: DivText, DivFixedSize, StringVariable. Остальные описываются обычными объектами, их типы — интерфейсы с префиксом I, например IDivData и IDivAction. Для размеров есть короткие функции fixed, matchParent, wrapContent и weighted.
При сериализации результата divCard значения true и false заменяются на 1 и 0.
Важно
Сами значения библиотека не проверяет. При разработке карточек убедитесь, что текстовые строки и массивы не пустые, а URL изображений, действий и других свойств корректны.
Узнать больше
Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: https://t.me/divkit_community_ru.