TypeScript
Astro по умолчанию поддерживает TypeScript. Вы можете импортировать .ts
и .tsx
файлы в свой проект, писать Typescript код прямо внутри своих Astro компонентов, и даже использовать astro.config.ts
файл, если это необходимо.
Используя Typescript, вы можете предотвратить ошибки во время выполнения, описывая типы объектов и компонентов в коде. К примеру, если вы используете Typescript для типизации параметров(пропсов) компонента, то редактор выведет ошибку, если вы попытаетесь передать параметр, который компонент не принимает.
Чтобы пользоваться преимуществами Typescript, не обязательно писать код на нем в Astro проектах. Astro всегда воспринимает код компонентов как Typescript, и расширение Astro для VSCode будет стараться определяться типы насколько это возможно, чтобы обеспечить автодополнение, показывать подсказки и ошибки в вашем редакторе.
Astro dev сервер не выполняет никакой проверки типов, но вы можете использовать отдельный скрипт для проверки ошибок типизации прямо из командной строки.
Настройка
Заголовок раздела НастройкаСтартовые проекты Astro добавляют tsconfig.json
файл в ваш проект по умолчанию. Даже если вы не планируете использовать Typescript, не удаляйте его, потому что такие инструменты как Astro и VS Code с помощью него получают информацию о проекте. Некоторые функции (например импорт npm пакетов) поддерживаются не полностью без tsconfig.json
файла. Если вы устанавливаете Astro вручную, не забудьте создать этот файл самостоятельно.
Astro поддерживает три расширяемых tsconfig.json
шаблона: base
, strict
и strictest
. Шаблон base
обеспечивает поддержку современных возможностей JavaScript, а также используется в качестве основы для других шаблонов. Мы рекомендуем использовать strict
или strictest
шаблоны, если вы планируете писать Typescript код в своем проекте. Вы можете посмотреть и сравнить эти шаблоны на гитхабе в директории astro/tsconfigs/.
Для наследования от одного из шаблонов используйте синтаксис extends
:
Кроме того, наши шаблоны включают в себя файл env.d.ts
внутри src
директории для обеспечения клиентских типов Vite в вашем проекте:
Если вы не используете VS Code, вы можете установить Astro TypeScript плагин для поддержки импортов .astro
файлов из .ts
файлов (что может быть полезно при переиспользовании).
Затем, добавьте код ниже в tsconfig.json
:
Чтобы проверить, что плагин работает, создайте .ts
файл и импортируйте Astro компонент в него. Если вы не увидите ошибок, то плагин работает корректно.
UI-фреймворки
Заголовок раздела UI-фреймворкиЕсли ваш проект использует UI-фреймворк, то вам может потребоваться дополнительная настройка в зависимости от фреймворка. Пожалуйста, проверьте документацию о работе Typescript вместе с вашим фреймворком для дополнительной информации. (Vue, React, Preact, Solid)
Импорт типов
Заголовок раздела Импорт типовПо возможности используйте явный импорт и экспорт типов.
Таким образом, вы избежите крайних случаев, когда сборщик Astro попытается некорректно собирать импортированные типы, как если бы они были JavaScript файлом.
Вы можете настроить TypeScript на принудительный импорт типов в файле .tsconfig
. Установите параметр verbatimModuleSyntax
в значение true
. TypeScript проверит ваши импорты и сообщит вам, когда следует использовать import type
. Эта настройка включена по умолчанию во всех наших пресетах.
Импорт алиасов
Заголовок раздела Импорт алиасовAstro поддерживает импорт алиасов, которые вы определили в секции paths
в файлах tsconfig.json
и jsconfig.json
. Прочитайте наш гайд, чтобы узнать больше.
Расширение window
и globalThis
Заголовок раздела Расширение window и globalThisЕсли вы захотите добавить свойство к глобальному объекту, то это можно сделать, добавив ключевое слово declare
в файл env.d.ts
:
Это обеспечит типизацию globalThis.myString
и globalThis.myFunction
, а также window.myString
и window.myFunction
.
Обратите внимание, что window
доступно только в коде на стороне клиента. Функция globalThis
доступна как на стороне сервера, так и на стороне клиента, но ее значение на стороне сервера не будет передано клиенту.
Если вы хотите добавить свойство только для объекта window
, создайте вместо global
интерфейс Window
:
Параметры компонентов
Заголовок раздела Параметры компонентовAstro поддерживает типизацию параметров (пропсов) компонентов с помощью TypeScript. Для типизации добавьте TypeScript интерфейс Props
в метаданных вашего компонента. Вы можете использовать выражение export
, но это не обязательно. Расширение Astro для VSCode будет автоматически искать интерфейс Props
и обеспечивать соответствующую поддержку TS при использовании этого компонента внутри другого шаблона.
Распространённые паттерны типизации пропсов
Заголовок раздела Распространённые паттерны типизации пропсов- Если ваш компонент не принимает пропсов или слотов, вы можете использовать
type Props = Record<string, never>
. - Если ваш компонент должен передавать дочерние элементы в свой слот, вы можете явно указать это через
type Props = { children: any; };
.
Утилиты типизации
Заголовок раздела Утилиты типизации
Добавлено в:
astro@1.6.0
Astro предоставляет встроенные типы для распространённых паттернов типизации пропсов. Они доступны в astro/types
.
Встроенные HTML атрибуты
Заголовок раздела Встроенные HTML атрибутыAstro предоставляет тип HTMLAttributes
для проверки того, что в вашей разметке используются валидные HTML-атрибуты. Эти типы можно использовать для создания пропсов компонентов.
К примеру, если вы создаете компонент <Link>
, вы можете добавить стандартные HTML атрибуты для тега <a>
в тип пропсов вашего компонента.
Также можно расширить стандартные JSX выражения для того, чтобы добавить нестандартные атрибуты с помощью переопределения пространства имен astroHTML.JSX
в файле .d.ts
.
astroHTML
глобально инжектирован в .astro
компоненты. Чтобы использовать их в TypeScript файлах, используйте директиву triple-slash:
Тип ComponentProps
Заголовок раздела Тип ComponentProps
Добавлено в:
astro@4.3.0
Этот тип экспорта позволяет вам ссылаться на Props
, принятый другим компонентом, даже если этот компонент не экспортирует этот тип Props
напрямую.
В следующем примере показано использование утилиты ComponentProps
из astro/types
для ссылки на типы Props
компонента <Button />
:
Полиморфный тип
Заголовок раздела Полиморфный тип
Добавлено в:
astro@2.5.0
Astro имеет хелпер, чтобы сделать проще создание компонентов, которые могут быть различными HTML элементами с полной безопасностью типов. Это может быть полезно для компонентов как <Link>
, которые могут быть элементами <a>
или <button>
в зависимости от пропсов, переданных в него.
Пример ниже использует полностью типизированный полиморфный компонент, который может быть любым HTML элементом. HTMLTag
тип используется для того, чтобы быть уверенным, что параметр as
— это валидный HTML элемент.
Определение типов getStaticPaths()
Заголовок раздела Определение типов getStaticPaths()
Добавлено в:
astro@2.1.0
Astro имеет хелперы для работы с типами, которые возвращаются из функции getStaticPaths()
, используемой для динамических путей.
Вы можете получить тип Astro.params
с помощью InferGetStaticParamsType
и тип Astro.props
с помощью InferGetStaticPropsType
:
Проверка типов
Заголовок раздела Проверка типовЧтобы проверить ошибки в вашем проекте, пожалуйста убедитесь, что вы установили расширение Astro VSCode. Обратите внимание, что команды astro start
и astro build
соберут код с помощью esbuild, но не запустят проверку типов. Чтобы избежать сборки кода, содержащего ошибки TypeScript, измените команду «build» в package.json
файле на следующую:
astro check
проверяет все файлы, включенные в ваш проект TypeScript. Для проверки типов в файлах Svelte и Vue можно использовать пакеты svelte-check
и vue-tsc
соответственно.
.ts
файлов в Astro.
Решение проблем
Заголовок раздела Решение проблемОшибки типизации при использовании нескольких JSX фреймворков
Заголовок раздела Ошибки типизации при использовании нескольких JSX фреймворковПроблема может возникнуть при использовании нескольких JSX фреймворков в одном проекте, так как каждый фреймворк требует различных, иногда конфликтующих настроек в tsconfig.json
.
Решение: Установите ключу jsxImportSource
значение react
(стандартное), preact
или solid-js
в зависимости от самого используемого фреймворка в проекте. Затем, используйте pragma comment внутри всех конфликтующих файлов других фреймворков.
Для стандартного значения jsxImportSource: react
следует использовать: