Как пользоваться: JSON в TypeScript
- Вставьте типичный образец JSON, например ответ, скопированный из вкладки Network в браузере.
- Укажите имя корневого типа (например
UserилиApiResponse). - Выберите
interfaceилиtype, синтаксис массивов и нужно ли экспортировать объявления или сделать свойства readonly. - Скопируйте сгенерированный код в файл
.tsили скачайте его.
Что делает конвертер JSON в TypeScript?
Он выводит статические типы по примерам данных. Вместо того чтобы вручную писать интерфейс для каждого ответа API, вставьте один реальный ответ и получите соответствующие объявления TypeScript: отдельный именованный интерфейс для каждого вложенного объекта, типизированные массивы и union-типы там, где значения различаются. Это самый быстрый способ получить автодополнение и проверки на этапе компиляции для данных, которые приходят из REST API, вебхука или JSON-конфига.
Как выводятся типы
| Значение JSON | Тип TypeScript |
|---|---|
"text" | string |
42, 3.14 | number |
true | boolean |
null | null (в сочетании с другими типами, например string | null) |
{ … } | Именованный интерфейс (ключ profile → Profile) |
["a", "b"] | string[] |
[1, "two"] | (number | string)[] |
[] | unknown[] (нет образца для вывода) |
Массивы объектов объединяются
Если массив содержит несколько объектов, генератор объединяет их в один интерфейс, а не берёт только первый элемент. Ключ, который встречается не во всех элементах, становится необязательным (archived?: boolean), а ключ с разными значениями получает union-тип (license: string | null). Интерфейсы элементов массива называются по единственному числу ключа: repos → Repo, categories → Category. Одинаковые структуры, встречающиеся в разных местах, объявляются один раз и переиспользуются.
interface или type
Для описания объектов оба варианта почти взаимозаменяемы. Объявления interface можно расширять через extends и объединять повторным объявлением, а сообщения об ошибках у них обычно понятнее. Алиасы type умеют описывать union-типы, кортежи и mapped-типы. Многие команды используют интерфейсы для моделей данных. Выбирайте вариант, который соответствует правилам вашего линтера (например, @typescript-eslint/consistent-type-definitions).
Ограничения вывода — проверяйте результат
Образец показывает только то, что было в нём. Поле, которое в образце равно null, получит тип null. Исправьте его на реальный тип, например string | null. Даты приходят как ISO-строки и типизируются как string, так как в JSON нет типа даты. Ключи, которые не являются допустимыми идентификаторами, например social-links, автоматически заключаются в кавычки. Для проверки ненадёжных входящих данных в рантайме сочетайте эти типы со схемным валидатором, например Zod. Сначала приведите образец в порядок с помощью JSON Formatter, а YAML-конфиги предварительно конвертируйте через YAML to JSON.
Также ищут как: json в interface, генератор interface typescript, json2ts, json в type typescript, создать типы из json, конвертер json в ts.
Инструменты, которые хорошо сочетаются с JSON в TypeScript
- CSV в JSON — Вставьте CSV или TSV и получите JSON-массив объектов.
- SVG в JSX — Вставьте SVG из Figma, Illustrator или набора иконок и получите готовый React-компонент (JSX или TSX) с безопасным предпросмотром иконки.
- cURL в код — Вставьте команду curl из документации к API или пункт «Copy as cURL» из DevTools браузера, и вы получите готовый код для шести языков с сохранёнными заголовками, телом запроса и авторизацией.
- Валидатор JSON Schema — Вставьте схему и JSON, чтобы увидеть, какие значения нарушают какие правила, или сгенерируйте стартовую схему по примеру данных.
Часто задаваемые вопросы
Что использовать для JSON-данных: interface или type?
extends, а алиасы type также описывают union-типы и mapped-типы. Выбирайте тот вариант, который предпочитает гайд по стилю вашего проекта. Переключатель меняет весь результат целиком.Как определяются необязательные свойства?
?. Также можно сделать все nullable-свойства необязательными с помощью флажка под результатом.Почему свойство имеет тип null?
null, и информации о реальном типе нет. Замените null на ожидаемый тип, например string | null, или вставьте образец, где значение заполнено.