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.

Репозиторий DivKit