---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.2
alternate:
  - https://divkit.tech/docs/en/quickstart/typescript-json-builder.md
  - https://divkit.tech/docs/ru/quickstart/typescript-json-builder.md
  - href: https://divkit.tech/docs/ru/quickstart/typescript-json-builder.md
    type: text/markdown
    title: Markdown version
  - href: https://divkit.tech/docs/ru/llms.txt?revision=r22138801
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/ru/llms.txt?revision=r22138801

# TypeScript JSON Builder

TypeScript JSON Builder — это npm-пакет `@divkitframework/jsonbuilder` для описания верстки DivKit на TypeScript. Он предназначен для бэкенда на Node.js: карточка описывается объектами в коде, а библиотека формирует из них JSON для клиента. Классы и типы библиотеки сгенерированы из схемы DivKit, поэтому ошибки в названиях и типах свойств обнаруживает компилятор.

Исходный код библиотеки опубликован на [GitHub](https://github.com/divkit/divkit/tree/main/json-builder/typescript). Аналогичный инструмент для Kotlin описан на странице [Kotlin DSL](https://divkit.tech/docs/ru/quickstart/kotlin-dsl.md).

## Установка {#installation}

Установите пакет из npm:

```bash translate=no
npm install @divkitframework/jsonbuilder
```

В пакет входят сборки в форматах CommonJS и ES-модулей и описания типов TypeScript.

## Создание карточки {#usage}

Карточку собирает функция `divCard`. Первый аргумент — [шаблоны](#templates) (пустой объект, если шаблонов нет), второй — объект со структурой [`div-data`](https://divkit.tech/docs/ru/concepts/divs/2/div-data.md). Элементы верстки создаются через конструкторы классов `DivText`, `DivContainer`, `DivImage` и других. Имена свойств совпадают с именами в JSON.

```ts translate=no
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);
```

Результат сериализации (отформатирован для удобства чтения):

```json translate=no
{
  "templates": {},
  "card": {
    "log_id": "hello_card",
    "states": [
      {
        "state_id": 0,
        "div": {
          "type": "text",
          "font_size": 18,
          "text": "Hello, world!"
        }
      }
    ]
  }
}
```

Полученную строку остается передать клиенту. Пример бэкенда, который отдает верстку, и способ посмотреть результат в демо-приложении описаны в [инструкции по развертыванию простого бэкенда](https://divkit.tech/docs/ru/quickstart/simple-backend.md).

## Шаблоны {#templates}

[Шаблоны](https://divkit.tech/docs/ru/concepts/templates.md) описываются объектом, в котором ключ — имя шаблона, а значение — элемент или другой шаблон. Параметр шаблона объявляет функция `reference`: ее вызов ставится на место значения свойства. Элемент из шаблона создает функция `template`, она принимает имя шаблона и значения его параметров и свойств.

```ts translate=no
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', {...})`, но имя шаблона проверяет компилятор.

```ts translate=no
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`:

```json translate=no
{
  "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!"
        }
      }
    ]
  }
}
```

{% note info %}

Если имя параметра в `reference` совпадает с именем свойства, свойство с префиксом `$` в шаблон не добавляется. Значение такого свойства задается при использовании шаблона напрямую, по имени свойства.

{% endnote %}

### Отбор используемых шаблонов {#used-templates}

Если набор шаблонов общий для многих карточек, в JSON можно включить только те шаблоны, которые нужны конкретной карточке. Для этого есть две функции:

- `thelperWithMemo` возвращает объект `thelper`, который используется так же, как результат `templateHelper`, и множество `used` с именами вызванных шаблонов. Используйте `thelper` только при сборке карточки: вызовы внутри описаний шаблонов функция `templatesDepsMap` не видит.
- `templatesDepsMap` для каждого шаблона возвращает список шаблонов, от которых он зависит, включая его самого. Если шаблон использует необъявленный шаблон или зависимости образуют цикл, функция бросает исключение.

Пример продолжает предыдущий:

```ts translate=no
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-and-expressions}

[Переменные](https://divkit.tech/docs/ru/concepts/variables.md) объявляются в свойстве `variables` с помощью классов `StringVariable`, `IntegerVariable`, `BooleanVariable` и других. Чтобы задать свойству [вычисляемое выражение](https://divkit.tech/docs/ru/concepts/expressions.md), передайте строку с выражением через функцию `expression`. Ее результат принимают только те свойства, которые поддерживают выражения.

```ts translate=no
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}!'),
            }),
        },
    ],
});
```

### Экранирование строк {#escaping}

При сериализации результата `divCard` обычные строки экранируются: `@{` заменяется на `\@{`, а `\` — на `\\`. Поэтому текст из внешних источников не вычисляется на клиенте как выражение, а отображается как есть. По той же причине выражение, переданное обычной строкой без `expression`, вычислено не будет.

Строки, созданные функцией `expression`, попадают в JSON без изменений. Чтобы вставить в выражение произвольный текст, экранируйте его функцией `escapeExpression`.

```ts translate=no
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}`) }),
];
```

## Проверка типов и значений {#type-safety}

Компилятор TypeScript проверяет:

- названия свойств элементов и других объектов верстки;
- типы значений, допустимые значения перечислений и наличие обязательных свойств;
- что результат `expression` передан в свойство, которое поддерживает выражения;
- имена шаблонов при вызове функций `templateHelper`. Параметры шаблона при этом не проверяются.

Сущности схемы, у которых есть свойство `type`, представлены классами: `DivText`, `DivFixedSize`, `StringVariable`. Остальные описываются обычными объектами, их типы — интерфейсы с префиксом `I`, например `IDivData` и `IDivAction`. Для размеров есть короткие функции `fixed`, `matchParent`, `wrapContent` и `weighted`.

При сериализации результата `divCard` значения `true` и `false` заменяются на `1` и `0`.

{% note warning %}

Сами значения библиотека не проверяет. При разработке карточек убедитесь, что текстовые строки и массивы не пустые, а URL изображений, действий и других свойств корректны.

{% endnote %}

<!-- source: ru/_includes/index/troubleshooting.md -->
## Узнать больше {#troubleshooting}

Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: [https://t.me/divkit_community_ru](https://t.me/divkit_community_ru).



[Репозиторий DivKit](https://github.com/divkit/divkit)




<!-- endsource: ru/_includes/index/troubleshooting.md -->
