Перейти к содержимому

TypeScript

Astro по умолчанию поддерживает TypeScript. Вы можете импортировать .ts и .tsx файлы в свой проект, писать Typescript код прямо внутри своего компонента Astro, и даже использовать файл astro.config.ts (EN), если это необходимо.

Используя Typescript, вы можете предотвратить ошибки во время выполнения, описывая типы объектов и компонентов в коде. К примеру, если вы используете Typescript для типизации параметров компонента, то редактор выведет ошибку, если вы попытаетесь передать параметр, который компонент не принимает.

Чтобы пользоваться преимуществами Typescript, не обязательно писать код на нем в Astro проектах. Astro всегда воспринимает код компонентов как Typescript, и расширение Astro для VSCode будет стараться определяться типы насколько это возможно, чтобы обеспечить автодополнение, показывать подсказки и ошибки в вашем редакторе.

Astro dev-сервер не выполняет никакой проверки типов, но вы можете использовать отдельный скрипт для проверки ошибок типизации прямо из командной строки.

Настройка

Заголовок раздела Настройка

Стартовые проекты Astro добавляют tsconfig.json файл в ваш проект по умолчанию. Даже если вы не планируете использовать Typescript, не удаляйте его, потому что такие инструменты как Astro и VS Code с помощью него получают информацию о проекте. Некоторые функции (например, импорт пакетов npm) не полностью поддерживаются в редакторе без файла tsconfig.json. Если вы устанавливаете Astro вручную, не забудьте создать этот файл самостоятельно.

Шаблоны TSConfig

Заголовок раздела Шаблоны TSConfig

Astro поддерживает три расширяемых шаблона tsconfig.json: base, strict и strictest. Шаблон base обеспечивает поддержку современных возможностей JavaScript, а также используется в качестве основы для других шаблонов. Мы рекомендуем использовать strict или strictest шаблоны, если вы планируете писать Typescript код в своем проекте. Вы можете посмотреть и сравнить эти шаблоны в директории astro/tsconfigs/.

Для наследования от одного из шаблонов используйте синтаксис extends:

tsconfig.json
{
  "extends": "astro/tsconfigs/base"
}

Кроме того, мы рекомендуем настроить include и exclude следующим образом, чтобы воспользоваться преимуществами типов Astro и избежать проверки собранных файлов:

tsconfig.json
{
  "extends": "astro/tsconfigs/base",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

Вы можете создать файл src/env.d.ts как стандартный способ добавления пользовательских объявлений типов или для использования типов Astro, если у вас нет tsconfig.json:

src/env.d.ts
// Пользовательские объявления типов
declare var myString: string;


// Типы Astro, не требуются, если у вас уже есть `tsconfig.json`
/// <reference path="../.astro/types.d.ts" />

Плагин TypeScript для редактора

Заголовок раздела Плагин TypeScript для редактора

Плагин TypeScript для Astro может быть установлен отдельно, если вы не используете официальное расширение Astro для VS Code. Этот плагин автоматически устанавливается и настраивается расширением VS Code, и вам не нужно устанавливать оба.

Этот плагин работает только в редакторе. При запуске tsc в терминале файлы .astro полностью игнорируются. Вместо этого вы можете использовать команду CLI astro check для проверки как .astro, так и .ts файлов.

Этот плагин также поддерживает импорт .astro файлов из .ts файлов (что может быть полезно для реэкспорта).

Окно терминала
npm install @astrojs/ts-plugin

Затем, добавьте код ниже в tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }
}

Чтобы проверить, что плагин работает, создайте .ts файл и импортируйте Astro компонент в него. Если вы не увидите ошибок, то плагин работает корректно.

UI-фреймворки

Заголовок раздела UI-фреймворки

Если ваш проект использует UI-фреймворк (EN), то вам может потребоваться дополнительная настройка в зависимости от фреймворка. Пожалуйста, проверьте документацию о работе Typescript вместе с вашим фреймворком для дополнительной информации. (Vue, React, Preact, Solid)

Импорт типов

Заголовок раздела Импорт типов

По возможности используйте явный импорт и экспорт типов.

import { SomeType } from "./script";
import type { SomeType } from "./script";

Таким образом, вы избежите крайних случаев, когда сборщик Astro попытается некорректно собирать импортированные типы, как если бы они были JavaScript файлом.

Вы можете настроить TypeScript на принудительный импорт типов в файле .tsconfig. Установите параметр verbatimModuleSyntax в значение true. TypeScript проверит ваши импорты и сообщит вам, когда следует использовать import type. Эта настройка включена по умолчанию во всех наших пресетах.

tsconfig.json
{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

Импорт алиасов

Заголовок раздела Импорт алиасов

Astro поддерживает импорт алиасов (EN), которые вы определили в секции paths в файлах tsconfig.json и jsconfig.json. Прочитайте наш гайд (EN), чтобы узнать больше.

src/pages/about/nate.astro
---
import HelloWorld from "@components/HelloWorld.astro";
import Layout from "@layouts/Layout.astro";
---
tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

Расширение window и globalThis

Заголовок раздела Расширение window и globalThis

Если вы захотите добавить свойство к глобальному объекту, то это можно сделать, добавив ключевое слово declare в файл env.d.ts:

env.d.ts
declare const myString: string;
declare function myFunction(): boolean;

Это обеспечит типизацию globalThis.myString и globalThis.myFunction, а также window.myString и window.myFunction.

Обратите внимание, что window доступно только в коде на стороне клиента. Функция globalThis доступна как на стороне сервера, так и на стороне клиента, но ее значение на стороне сервера не будет передано клиенту.

Если вы хотите добавить свойство только для объекта window, создайте вместо global интерфейс Window:

env.d.ts
interface Window {
  myFunction(): boolean;
}

Параметры компонентов

Заголовок раздела Параметры компонентов

Astro поддерживает типизацию параметров (пропсов) компонентов с помощью TypeScript. Для типизации добавьте TypeScript интерфейс Props в метаданных вашего компонента. Вы можете использовать выражение export, но это не обязательно. Расширение Astro для VSCode будет автоматически искать интерфейс Props и обеспечивать соответствующую поддержку TS при использовании этого компонента внутри другого шаблона.

src/components/HelloProps.astro
---
interface Props {
  name: string;
  greeting?: string;
}


const { greeting = "Привет", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Распространённые паттерны типизации пропсов

Заголовок раздела Распространённые паттерны типизации пропсов
  • Если ваш компонент не принимает пропсов или слотов, вы можете использовать type Props = Record<string, never>.
  • Если ваш компонент должен передавать дочерние элементы в свой слот, вы можете явно указать это через type Props = { children: any; };.

Утилиты типизации

Заголовок раздела Утилиты типизации

Добавлено в: astro@1.6.0

Astro предоставляет встроенные типы для распространённых паттернов типизации пропсов. Они доступны в astro/types.

Встроенные HTML атрибуты

Заголовок раздела Встроенные HTML атрибуты

Astro предоставляет тип HTMLAttributes для проверки того, что в вашей разметке используются валидные HTML-атрибуты. Эти типы можно использовать для создания пропсов компонентов.

К примеру, если вы создаете компонент <Link>, вы можете добавить стандартные HTML атрибуты для тега <a> в тип пропсов вашего компонента.

src/components/Link.astro
---
import type { HTMLAttributes } from "astro/types";


// используйте `type`
type Props = HTMLAttributes<"a">;


// или extends с `interface`
interface Props extends HTMLAttributes<"a"> {
  myProp?: boolean;
}


const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

Также можно расширить стандартные JSX выражения для того, чтобы добавить нестандартные атрибуты с помощью переопределения пространства имен astroHTML.JSX в файле .d.ts.

src/custom-attributes.d.ts
declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    "data-count"?: number;
    "data-label"?: string;
  }


  // Добавляем пользовательское CSS-свойство в объект `style`
  interface CSSProperties {
    "--theme-color"?: "black" | "white";
  }
}

Тип ComponentProps

Заголовок раздела Тип ComponentProps

Добавлено в: astro@4.3.0

Этот тип экспорта позволяет вам ссылаться на Props, принятый другим компонентом, даже если этот компонент не экспортирует этот тип Props напрямую.

В следующем примере показано использование утилиты ComponentProps из astro/types для ссылки на типы Props компонента <Button />:

src/pages/index.astro
---
import type { ComponentProps } from "astro/types";
import Button from "./Button.astro";


type ButtonProps = ComponentProps<typeof Button>;
---

Полиморфный тип

Заголовок раздела Полиморфный тип

Добавлено в: astro@2.5.0

Astro имеет хелпер, чтобы сделать проще создание компонентов, которые могут быть различными HTML элементами с полной безопасностью типов. Это может быть полезно для компонентов как <Link>, которые могут быть элементами <a> или <button> в зависимости от пропсов, переданных в него.

Пример ниже использует полностью типизированный полиморфный компонент, который может быть любым HTML элементом. HTMLTag тип используется для того, чтобы быть уверенным, что параметр as — это валидный HTML элемент.

---
import type { HTMLTag, Polymorphic } from "astro/types";


type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;


const { as: Tag, ...props } = Astro.props;
---
<Tag {...props} />

Определение типов getStaticPaths()

Заголовок раздела Определение типов getStaticPaths()

Добавлено в: astro@2.1.0

Astro имеет хелперы для работы с типами, которые возвращаются из функции getStaticPaths() (EN), используемой для динамических путей.

Вы можете получить тип Astro.params с помощью InferGetStaticParamsType и тип Astro.props с помощью InferGetStaticPropsType, или вы можете использовать GetStaticPaths, чтобы вывести оба типа сразу::

src/pages/posts/[...id].astro
---
import type {
  InferGetStaticParamsType,
  InferGetStaticPropsType,
  GetStaticPaths,
} from "astro";


export const getStaticPaths = (async () => {
  const posts = await getCollection("blog");
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;


type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;


const { id } = Astro.params as Params;
//                   ^? { id: string; }


const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---

Проверка типов

Заголовок раздела Проверка типов

Чтобы проверить ошибки в вашем проекте, пожалуйста убедитесь, что вы установили расширение Astro VSCode. Обратите внимание, что команды astro start и astro build соберут код с помощью esbuild, но не запустят проверку типов. Чтобы избежать сборки кода, содержащего ошибки TypeScript, измените команду «build» в package.json файле на следующую:

package.json
{
  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },
}
Подробнее об импортах .ts файлов (EN) в Astro.
Подробнее о конфигурации TypeScript.

Решение проблем

Заголовок раздела Решение проблем

Ошибки типизации при использовании нескольких JSX фреймворков

Заголовок раздела Ошибки типизации при использовании нескольких JSX фреймворков

Проблема может возникнуть при использовании нескольких JSX фреймворков в одном проекте, так как каждый фреймворк требует различных, иногда конфликтующих настроек в tsconfig.json.

Решение: Установите для ключа jsxImportSource значение react (стандартное), preact или solid-js в зависимости от используемого фреймворка в проекте. Затем используйте pragma-комментарий внутри всех конфликтующих файлов других фреймворков.

Для стандартного значения jsxImportSource: react следует использовать:

// Для Preact
/** @jsxImportSource preact */


// Для Solid
/** @jsxImportSource solid-js */
Внести свой вклад Сообщество Sponsor