Справочник API

Глобальный объект `Astro`

Глобальный объект Astro доступен во всех контекстах в файлах .astro. Он обладает следующими функциями:

`Astro.glob()`

Astro.glob() — это способ загрузить множество локальных файлов в ваш статический сайт.

---
const posts = await Astro.glob('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md
---

<div>
{posts.slice(0, 3).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Read more</a>
  </article>
))}
</div>

.glob() принимает только один параметр: относительный URL-шаблон локальных файлов, которые вы хотите импортировать. Она работает асинхронно и возвращает массив экспортов из соответствующих файлов.

.glob() не может принимать переменные или строки, которые интерполируют их, поскольку они не поддаются статическому анализу. (Обходной путь см. в руководстве по устранению неполадок). Это происходит потому, что Astro.glob() является оберткой Vite’s import.meta.glob().

Вы также можете использовать import.meta.glob() в вашем проекте Astro. Вы можете захотеть сделать это, когда:

Вам нужна эта функция в файле, который не является .astro, например, в маршруте API. Astro.glob() доступен только в файлах .astro, в то время как import.meta.glob() доступен в любом месте проекта.
Вы не хотите загружать каждый файл сразу. import.meta.glob() может возвращать функции, которые импортируют содержимое файла, а не возвращают само содержимое. Обратите внимание, что этот импорт включает все стили и скрипты для всех импортированных файлов. Они будут собраны и добавлены на страницу независимо от того, используется ли файл на самом деле, так как это решается статическим анализом, а не во время выполнения.
Вам нужен доступ к пути каждого файла. import.meta.glob() возвращает карту пути файла к его содержимому, а Astro.glob() возвращает список содержимого.
Вы хотите передать несколько шаблонов; например, вы хотите добавить “отрицательный шаблон”, который отфильтровывает определенные файлы. В качестве опции import.meta.glob() может принимать массив строк glob, а не одну строку.

Подробнее в документации Vite.

Файлы Markdown

Файлы Markdown имеют следующий интерфейс:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Любые данные, указанные в YAML frontmatter этого файла */
  frontmatter: T;
  /* Путь к этому файлу */
  file: string;
  /* Отрендеренный путь этого файла */
  url: string | undefined;
  /* Компонент Astro, который отображает содержимое этого файла */
  Content: AstroComponent;
  /* Функция, возвращающая массив элементов h1...h6 в этом файле */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
}

Вы можете указать тип для переменной frontmatter, используя TypeScript generic.

---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Файлы Astro

Файлы Astro имеют следующий интерфейс:

export interface AstroInstance {
  /* Путь к этому файлу */
  file: string;
  /* URL-адрес этого файла (если он находится в директории pages) */
  url: string | undefined;
  default: AstroComponent;
}

Другие файлы

Другие файлы могут иметь различные интерфейсы, но Astro.glob() принимает TypeScript-обобщение, если вы точно знаете, что содержит неизвестный тип файла.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---

`Astro.props`

Astro.props — это объект, содержащий любые значения, которые были переданы в качестве атрибутов компонента. Компоненты макета для файлов .md и .mdx получают значения frontmatter в качестве props.

---
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>

---
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />

Узнайте больше о том, как макеты Markdown и MDX обрабатывают props.

Узнайте, как добавить определения типов TypeScript для ваших props.

`Astro.params`

Astro.params — это объект, содержащий значения сегментов динамического маршрута, найденных для данного запроса.

В статических сборках это будут params, возвращаемые getStaticPaths(), используемые для пререндеринга динамических маршрутов.

В сборках SSR это может быть любое значение, соответствующее сегментам пути в шаблоне динамического маршрута.

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

См. также: params

`Astro.request`

Astro.request — это стандартный объект Request. С его помощью можно получить url, headers, method и даже тело запроса.

<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
<p>Received request headers: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

См. также: Astro.url

`Astro.response`

Astro.response — это стандартный объект ResponseInit. Он имеет следующую структуру.

status: Числовой код статуса ответа, например, 200.
statusText: Сообщение о статусе, связанное с кодом статуса, например, 'OK'.
headers: Экземпляр Headers, который можно использовать для установки HTTP-заголовков ответа.

Astro.response используется для установки status, statusText и headers для ответа страницы.

---
if(condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---

Или чтобы установить заголовок:

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

`Astro.cookies`

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

Astro.cookies содержит утилиты для чтения и работы с куки в режиме серверного рендеринга.

`get`

Тип: (key: string, options?: CookieGetOptions) => AstroCookie

Получает куки в виде объекта AstroCookie, который содержит value и служебные функции для преобразования куки в нестроковые типы.

`has`

Тип: (key: string) => boolean

Существует ли данный куки. Если куки были установлены через Astro.cookies.set(), то возвращается true, в противном случае проверяются куки в Astro.request.

`set`

Тип: (key: string, value: string | number | boolean | object, options? CookieSetOptions) => void

Устанавливает для key куки заданное значение. При этом будет сделана попытка преобразовать значение куки в строку. Опции позволяют установить характеристики куки, такие как maxAge или httpOnly.

`delete`

Тип: (key: string, options?: CookieDeleteOptions) => void

Помечает куки как удаленный. После удаления куки Astro.cookies.has() вернет false, а Astro.cookies.get() вернет AstroCookie с значением undefined. Опции позволяют задать domain и path удаляемого куки.

`headers`

Тип: () => Iterator<string>

Получает значения заголовков Set-Cookie, которые будут отправлены вместе с ответом.

`AstroCookie`

Получение куки с помощью Astro.cookies.get() возвращает тип AstroCookie. Он имеет следующую структуру.

`value`

Тип: string | undefined

Необработанное строковое значение куки.

`json`

Тип: () => Record<string, any>

Разбирает значение куки с помощью JSON.parse(), возвращая объект. Выбрасывает исключение, если значение куки не является корректным JSON.

`number`

Тип: () => number

Разбирает значение куки как число. Возвращает NaN, если число не является действительным.

`boolean`

Тип: () => boolean

Преобразует значение куки в логическое значение.

`CookieGetOptions`

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

Получение куки также позволяет указать опции через интерфейс CookieGetOptions:

`decode`

Тип: (value: string) => string

Позволяет настраивать способ десериализации куки в значение.

`CookieSetOptions`

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

Установка куки с помощью Astro.cookies.set() позволяет передать CookieSetOptions для настройки того, как куки будет сериализована.

`domain`

Тип: string

Указывает домен. Если домен не задан, большинство клиентов будут интерпретировать применение к текущему домену.

`expires`

Тип: Date

Указывает дату истечения срока действия файла куки.

`httpOnly`

Тип: boolean

Если значение равно true, куки не будет доступен на стороне клиента.

`maxAge`

Тип: number

Указывает число в секундах, в течение которого куки будет действителен.

`path`

Тип: string

Указывает подпункт домена, в котором применяется куки.

`sameSite`

Тип: boolean | 'lax' | 'none' | 'strict'

Определяет значение заголовка куки SameSite.

`secure`

Тип: boolean

Если значение равно true, то куки будет устанавливаться только на https-сайтах.

`encode`

Тип: (value: string) => string

Позволяет настроить способ сериализации куки.

`Astro.redirect()`

Astro.redirect() позволяет перенаправить вас на другую страницу. Страница (а не дочерний компонент) должна возвращать результат Astro.redirect(), чтобы произошла переадресация.

---
import { isLoggedIn } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// Если пользователь не вошел в систему, перенаправьте его на страницу входа в систему
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---

`Astro.canonicalURL`

Канонический URL текущей страницы.

`Astro.url`

Добавлено в: astro@1.0.0-rc

Объект URL, созданный из текущего значения строки URL Astro.request.url. Используется для работы с отдельными свойствами URL запроса, такими как имя пути и происхождение.

Эквивалентно выполнению new URL(Astro.request.url).

<h1>The current URL is: {Astro.url}</h1>
<h1>The current URL pathname is: {Astro.url.pathname}</h1>
<h1>The current URL origin is: {Astro.url.origin}</h1>

Вы также можете использовать Astro.url для создания новых URL, передавая его в качестве аргумента в new URL().

---
// Пример: Создание канонического URL с использованием production домена
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Пример: Создание URL для метатегов SEO с использованием текущего домена
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`Astro.clientAddress`

Добавлено в: astro@1.0.0-rc

Указывает IP-адрес запроса. Это свойство доступно только при сборке для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.

---
const ip = Astro.clientAddress;
---

<div>Your IP address is: <span class="address">{ ip }</span></div>

`Astro.site`

Astro.site возвращает URL, созданный из site в вашей конфигурации Astro. Если site в вашем конфиге Astro не определен, то Astro.site не будет определен.

`Astro.generator`

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

Astro.generator — это удобный способ добавить тег <meta name="generator"> с вашей текущей версией Astro. Он имеет формат "Astro v1.x.x".

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Built with <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

`Astro.slots`

Astro.slots содержит служебные функции для изменения дочерних слотов компонента Astro.

`Astro.slots.has()`

Тип: (slotName: string) => boolean

С помощью функции Astro.slots.has() можно проверить, существует ли содержимое для определенного имени слота. Это может быть полезно, когда вы хотите обернуть содержимое слота, но хотите выводить элементы обертки только тогда, когда слот используется.

---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>More</h2>
    <slot name="more" />
  </aside>
)}

`Astro.slots.render()`

Тип: (slotName: string, args?: any[]) => Promise<string>.

Вы можете асинхронно вывести содержимое слота в строку HTML с помощью Astro.slots.render().

---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />

Astro.slots.render() опционально принимает второй аргумент: массив параметров, которые будут переданы всем дочерним функциям. Это может быть полезно для компонентов пользовательских утилит.

Например, этот компонент <Shout /> преобразует свое свойство message в верхний регистр и передает его в слот по умолчанию:

---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />

Функция обратного вызова, переданная в качестве дочерней функции <Shout />, получит параметр message со всеми заглавными буквами:

---
import Shout from "../components/Shout.astro";
---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- отображается как <div>SLOTS!</div> -->

`Astro.self`

Astro.self позволяет рекурсивно вызывать компоненты Astro. Такое поведение позволяет вызывать компонент Astro изнутри самого себя, используя <Astro.self> в шаблоне компонента. Это может быть полезно для итераций по большим хранилищам данных и вложенным структурам данных.

---
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- Если есть вложенная структура данных, мы отображаем `<Astro.self>` -->
      <!-- и можем передавать реквизиты с помощью рекурсивного вызова -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

Этот компонент можно использовать следующим образом:

---
import NestedList from './NestedList.astro';
---
<NestedList items={['A', ['B', 'C'], 'D']} />

При этом HTML будет выглядеть следующим образом:

<ul class="nested-list">
  <li>A</li>
  <li>
    <ul class="nested-list">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

`Astro.locals`

Astro.locals — это объект, содержащий любые значения из объекта context.locals от промежуточного ПО. Используйте его для доступа к данным, возвращаемым промежуточным ПО, в ваших файлах .astro.

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<ul>
    {orders.map(order => {
        return <li>{/* делаем что-то с каждым заказом */}</li>
    })}
</ul>

`Astro.preferredLocale`

Astro.preferredLocale — это вычисляемое значение, которое представляет предпочтительную локаль пользователя.

Оно вычисляется путем проверки настроенных локалей в вашем массиве i18n.locales и локалей, поддерживаемых браузером пользователя через заголовок Accept-Language. Это значение является undefined, если такого соответствия нет.

Это свойство доступно только при создании для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.

`Astro.preferredLocaleList`

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

Если ни один из запрошенных браузером языков не найден в вашем массиве локалей, то значение будет []: вы не поддерживаете ни один из предпочитаемых посетителем локалей.

Если браузер не указывает предпочтительные языки, то это значение будет i18n.locales: все поддерживаемые вами локали будут считаться одинаково предпочтительными для посетителя, не имеющего предпочтений.

`Astro.currentLocale`

Локаль, вычисленная из текущего URL, с использованием синтаксиса, указанного в вашей конфигурации locales. Если URL не содержит префикса /[locale]/, то значение по умолчанию будет равно i18n.defaultLocale.

Контекст конечной точки

Функции конечных точек получают в качестве первого параметра объект контекста. Он отражает многие глобальные свойства Astro.

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`context.params`

context.params — это объект, содержащий значения динамических сегментов маршрута, найденных для данного запроса.

В сборках SSR это может быть любое значение, соответствующее сегментам пути в шаблоне динамического маршрута.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

export function GET({ params }: APIContext) {
  return new Response(
    JSON.stringify({ id: params.id }),
  );
}

См. также: params

`context.props`

context.props — это объект, содержащий любые props, переданные из getStaticPaths(). Поскольку getStaticPaths() не используется при сборке для SSR (рендеринг на стороне сервера), context.props доступен только в статических сборках.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' }, props: { author: 'Blu' } },
    { params: { id: '2' }, props: { author: 'Erika' } },
    { params: { id: '3' }, props: { author: 'Matthew' } }
  ];
}

export function GET({ props }: APIContext) {
  return new Response(
    JSON.stringify({ author: props.author }),
  );
}

См. также: Передача данных с props

`context.request`

Стандартный объект Request. С его помощью можно получить url, headers, method и даже тело запроса.

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Hello ${request.url}`);
}

См. также: Astro.request

`context.cookies`

context.cookies содержит утилиты для чтения и работы с куки.

См. также: Astro.cookies

`context.url`

Объект URL, построенный из текущего значения строки URL context.request.url.

См. также: Astro.url

`context.clientAddress`

Указывает IP-адрес запроса. Это свойство доступно только при построении для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Your IP address is: ${clientAddress}`);
}

См. также: Astro.clientAddress

`context.site`

context.site возвращает URL, созданный из site в конфигурации Astro. Если значение не определено, то возвращается URL, сгенерированный с localhost.

См. также: Astro.site

`context.generator`

context.generator — это удобный способ указать версию Astro, на которой работает ваш проект. Он имеет формат "Astro v1.x.x".

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

См. также: Astro.generator

`context.redirect()`

context.redirect() возвращает объект Response, который позволяет перенаправить вас на другую страницу. Эта функция доступна только при построении для SSR (рендеринг на стороне сервера) и не должна использоваться для статических сайтов.

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

См. также: Astro.redirect()

`context.locals`

context.locals — это объект, используемый для хранения и доступа к произвольной информации во время жизненного цикла запроса.

Функции промежуточного ПО могут читать и записывать значения context.locals:

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Заголовок по умолчанию";
  }
  return next();
}

Конечные точки API могут читать информацию только из context.locals:

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Заголовок по умолчанию"
}

См. также: Astro.locals

`getStaticPaths()`

Если страница использует динамические параметры в имени файла, этот компонент должен экспортировать функцию getStaticPaths().

Эта функция необходима, поскольку Astro является статическим конструктором сайтов. Это означает, что весь ваш сайт создается заранее. Если Astro не знает, что нужно сгенерировать страницу во время создания, пользователи не увидят ее, когда посетят ваш сайт.

---
export async function getStaticPaths() {
  return [
    { params: { /* required */ }, props: { /* optional */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- Ваш HTML-шаблон здесь. -->

Функция getStaticPaths() должна возвращать массив объектов, чтобы определить, какие пути будут предварительно рендериться Astro.

Его также можно использовать в статических файловых конечных точках для динамической маршрутизации.

`params`

Ключ params каждого возвращаемого объекта указывает Astro, какие маршруты строить. Возвращаемые параметры должны соответствовать динамическим параметрам и остальным параметрам, определенным в файловом каталоге вашего компонента.

params кодируются в URL, поэтому в качестве значений поддерживаются только строки. Значение каждого объекта params должно совпадать с параметрами, используемыми в имени страницы.

Например, предположим, что у вас есть страница по адресу src/pages/posts/[id].astro. Если вы экспортируете getStaticPaths с этой страницы и вернете следующие значения для путей:

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

Тогда Astro будет статически генерировать posts/1, posts/2 и posts/3 во время сборки.

Передача данных с помощью `props`

Чтобы передать дополнительные данные каждой сгенерированной странице, вы также можете установить значение props для каждого возвращаемого объекта path. В отличие от params, props не кодируются в URL и поэтому не ограничиваются только строками.

Например, предположим, что вы генерируете страницы на основе данных, полученных из удаленного API. Вы можете передать полный объект данных компоненту страницы внутри getStaticPaths:

---
export async function getStaticPaths() {
  const data = await fetch('...').then(response => response.json());

  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}

const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>

Вы также можете передать обычный массив, что может быть полезно при генерации или создании заглушки для известного списка маршрутов.

---
export async function getStaticPaths() {
  const posts = [
    {id: '1', category: "astro", title: "API Reference"},
    {id: '2', category: "react", title: "Creating a React Counter!"}
  ];
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { post }
    };
  });
}
const {id} = Astro.params;
const {post} = Astro.props;
---
<body>
  <h1>{id}: {post.title}</h1>
  <h2>Category: {post.category}</h2>
</body>

Тогда Astro будет статически генерировать posts/1 и posts/2 во время сборки, используя компонент страницы в pages/posts/[id].astro. Страница может ссылаться на эти данные с помощью Astro.props:

`paginate()`

Пагинация является распространенным случаем использования для веб-сайтов, который Astro поддерживает с помощью функции paginate(). paginate() автоматически генерирует массив для возврата из getStaticPaths(), который создает один URL для каждой страницы пагинируемой коллекции. Номер страницы будет передан в качестве параметра, а данные о странице будут переданы в качестве параметра page.

export async function getStaticPaths({ paginate }) {
  // Загрузите данные с помощью fetch(), Astro.glob() и т.д.
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;

  // Возвращаем постраничную коллекцию путей для всех постов
  return paginate(allPokemon, { pageSize: 10 });
}

// Если все настроено правильно, то в свойстве страницы теперь есть все, что
// необходимо для рендеринга одной страницы (см. следующий раздел).
const { page } = Astro.props;

paginate() предполагает имя файла [page].astro или [...page].astro. Параметр page становится номером страницы в вашем URL:

/posts/[page].astro будет генерировать URL /posts/1, /posts/2, /posts/3 и т.д.
/posts/[...page].astro сгенерирует URL /posts, /posts/2, /posts/3 и т. д.

У paginate() есть следующие аргументы:

pageSize - Количество элементов, отображаемых на странице
params - Отправка дополнительных параметров для создания динамических маршрутов
props - Отправка дополнительных свойств, которые должны быть доступны на каждой странице

Свойство пагинации `page`

При пагинации каждой отрисованной странице передается параметр page, который представляет одну страницу данных в пагинируемой коллекции. Он включает в себя данные, которые вы пагинировали (page.data), а также метаданные для страницы (page.url, page.start, page.end, page.total и т. д.). Эти метаданные полезны для таких вещей, как кнопка “Следующая страница” или сообщение “Показано 1-10 из 100”.

`page.data`

Тип: Array

Массив данных, возвращаемых из data() для текущей страницы.

`page.start`

Тип: number

Индекс первого элемента на текущей странице, начиная с 0. (например, если pageSize: 25, это будет 0 на странице 1, 25 на странице 2 и т.д.)

`page.end`

Тип: number

Индекс последнего элемента на текущей странице.

`page.size`

Тип: number

Сколько элементов на странице.

`page.total`

Тип: number

Общее количество элементов на всех страницах.

`page.currentPage`

Тип: number

Номер текущей страницы, начиная с 1.

`page.lastPage`

Тип: number

Общее количество страниц.

`page.url.current`

Тип: string

Получите URL текущей страницы (полезно для канонических URL).

`page.url.prev`

Тип: string | undefined

Получите URL предыдущей страницы (будет undefined, если на странице 1).

`page.url.next`.

Тип: string | undefined

Получение URL следующей страницы (будет undefined, если больше нет страниц).

`import.meta`

Все модули ESM включают свойство import.meta. Astro добавляет import.meta.env через Vite.

import.meta.env.SSR можно использовать, чтобы знать, когда рендерить на сервере. Иногда вам может понадобиться другая логика, например, компонент, который должен отображаться только на клиенте:

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <FancyComponent />;
}

Изображения (`astro:assets`)

`getImage()`

Функция getImage() предназначена для генерации изображений, предназначенных для использования не непосредственно в HTML, а где-то еще, например, в API Route. Она также позволяет создавать собственные компоненты <Image />.

getImage() принимает объект options с теми же свойствами, что и компонент Image (кроме alt).

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>

Он возвращает объект со следующими свойствами:

{
  options: {...} // Передаваемые исходные параметры
  src: "https//..." // Путь к сгенерированному изображению
  attributes: {...} // Дополнительные HTML-атрибуты, необходимые для отображения изображения (ширина, высота, стиль и т. д.)
}

Коллекции контента (`astro:content`)

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

Коллекции контента предлагают API для настройки и запросов к вашим документам Markdown или MDX в src/content/. О возможностях и примерах использования [см. наше руководство по коллекциям контента] (/ru/guides/content-collections/).

`defineCollection()`

defineCollection() — это утилита для настройки коллекции в файле src/content/config.*.

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Представьте определенную вами коллекцию в Astro
// с помощью экспорта `collections`
export const collections = { blog };

Эта функция принимает следующие свойства:

`type`

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

Тип: 'content' | 'data'
По умолчанию: 'content'

type — это строка, определяющая тип записей, хранящихся в коллекции:

'content' — для форматов с авторским контентом, таких как Markdown (.md), MDX (.mdx) или Markdoc (.mdoc)
'data' — для форматов, содержащих только данные, таких как JSON (.json) или YAML (.yaml)

`schema`

Тип: TSchema extends ZodType

schema — необязательный объект Zod для настройки типа и формы frontmatter документа для коллекции. Каждое значение должно использовать валидатор Zod.

Примеры использования см. в руководстве по коллекциям контента.

`reference()`

Тип: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

Функция reference() используется в конфигурации содержимого для определения связи, или “ссылки”, от одной коллекции к другой. Она принимает имя коллекции и проверяет идентификатор(ы) записи, указанный(ые) в вашем frontmatter контента или файле данных.

Этот пример определяет ссылки автора блога на коллекцию authors и массив связанных постов на ту же коллекцию blog:

import { defineCollection, reference, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // Ссылка на одного автора из коллекции `authors` по `id`.
    author: reference('authors'),
    // Ссылка на массив связанных постов из коллекции `blog` по `slug`.
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

Примеры использования см. в руководстве Коллекции контента.

`getCollection()`

Тип: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

getCollection() — это функция, которая получает список записей коллекции контента по имени коллекции.

По умолчанию он возвращает все элементы коллекции, а также принимает дополнительную функцию filter для сужения списка по свойствам элементов. Это позволяет запрашивать только некоторые элементы коллекции на основе значений id, slug или frontmatter через объект data.

---
import { getCollection } from 'astro:content';

// Получение всех записей `src/content/blog/`
const allBlogPosts = await getCollection('blog');

// Возвращаем только посты с `draft: true` во frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

Примеры использования см. в руководстве Коллекции контента.

`getEntry()`

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

Типы:

(collection: string, contentSlugOrDataId: string) => CollectionEntry<collection>
({ collection: string, id: string }) => CollectionEntry<collection>
({ collection: string, slug: string }) => CollectionEntry<collection>

getEntry() — это функция, которая извлекает одну запись коллекции по имени коллекции и либо по id (для коллекций type: 'data'), либо по slug (для коллекций type: 'content'). Функция getEntry() также может использоваться для получения ссылок на записи для доступа к свойствам data, body или render():

---
import { getEntry } from 'astro:content';

// Получаем `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Получаем `src/content/captains/picard.yaml`.
const picardProfile = await getEntry('captains', 'picard');

// Получаем профиль, на который ссылается `data.captain`.
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

Примеры запросов к записям коллекции см. в руководстве Коллекции контента.

`getEntries()`

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

Типы:

(Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>
(Array<{ collection: string, slug: string }>) => Array<CollectionEntry<collection>>

getEntries() — это функция, которая извлекает несколько записей коллекции из одной и той же коллекции. Это полезно для возврата массива ссылающихся записей, чтобы получить доступ к связанным с ними свойствам data, body и render().

---
import { getEntries } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// Получение связанных постов, на которые ссылается `data.relatedPosts`.
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`getEntryBySlug()`

Тип: (collection: string, slug: string) => CollectionEntry<collection>

getEntryBySlug() — это функция, которая извлекает один элемент коллекции по имени коллекции и slug элемента.

---
import { getEntryBySlug } from 'astro:content';

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

Примеры использования см. в руководстве Коллекции контента.

Тип элемента коллекции

Функции запросов, включая getCollection(), getEntry() и getEntries(), возвращают записи с типом CollectionEntry. Этот тип доступен как утилита из astro:content:

import type { CollectionEntry } from 'astro:content';

Тип CollectionEntry<TCollectionName> — это объект со следующими значениями. TCollectionName — это имя коллекции, к которой вы делаете запрос (например, CollectionEntry<'blog'>).

`id`

Доступно для коллекций: type: 'content' и type: 'data' Примеры типов:

коллекции контента: 'entry-1.md' | ‘entry-2.md’ | …`
коллекции данных: 'author-1' | 'author-2' | ...

Уникальный идентификатор, использующий путь к файлу относительно src/content/[collection]. Перечисляет все возможные строковые значения, основанные на путях к файлам записей коллекции. Обратите внимание, что коллекции определенные как type: 'content' включают расширение файла в свой идентификатор, а коллекции, определенные как type: 'data', нет.

`collection`

Доступно для коллекций: type: 'content' и type: 'data' Пример типа: 'blog' | 'authors' | ...

Имя папки верхнего уровня в разделе src/content/, в которой находятся записи. Это имя используется для ссылок на коллекцию в вашей схеме и в функциях запросов.

`data`

Доступно для коллекций: type: 'content' и type: 'data' Тип: CollectionSchema<TCollectionName>

Объект свойств frontmatter, выведенных из схемы вашей коллекции (см. ссылку defineCollection()). По умолчанию принимает значение any, если схема не задана.

`slug`

Доступно только для коллекций: type: 'content' Пример типа: 'entry-1' | 'entry-2' | ...

Готовый к использованию в URL слаг для документов Markdown или MDX. По умолчанию используется id без расширения файла, но может быть переопределено установкой свойства slug в frontmatter файла.

`body`

Доступно только для коллекций: type: 'content' Тип: string

Строка, содержащая необработанное, некомпилированное тело документа Markdown или MDX.

`render()`

Доступно только для коллекций: type: 'content' Тип: () => Promise<RenderedEntry>

Функция для компиляции заданного документа Markdown или MDX для визуализации. Возвращает следующие свойства:

<Content /> — компонент, используемый для отображения содержимого документа в файле Astro.
Заголовки — Сгенерированный список заголовков, зеркальное отражение утилиты Astro getHeadings() при импорте Markdown и MDX.
remarkPluginFrontmatter — Измененный объект frontmatter после применения любых плагинов remark или rehype. Устанавливается в тип any.

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

Пример использования см. в руководстве Коллекции контента.

Другие типы коллекций контента

Модуль astro:content также экспортирует следующие типы для использования в вашем проекте Astro:

`CollectionKey`

Строковое объединение всех имен коллекций, определенных в вашем файле src/content/config.*. Этот тип может быть полезен при определении общей функции, принимающей любое имя коллекции.

import type { CollectionKey, getCollection } from 'astro:content';

async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

`ContentCollectionKey`

Строковое объединение всех имен коллекций type: 'content', определенных в вашем файле src/content/config.*.

`DataCollectionKey`

Строковое объединение всех имен коллекции type: 'data', определенных в вашем файле src/content/config.*.

`SchemaContext`

Объект context, который defineCollection использует для формы функции schema. Этот тип может быть полезен при создании многократно используемых схем для нескольких коллекций.

Это включает следующее свойство:

image — Вспомогательная схема image(), которая позволяет использовать локальные изображения в коллекциях контента

import type { SchemaContext } from 'astro:content';

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});

Промежуточное ПО (`astro:middleware`)

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

Промежуточное ПО позволяет перехватывать запросы и ответы и динамически внедрять поведение каждый раз, когда страница или конечная точка собираются быть отображенными. О возможностях и примерах использования [см. наше руководство по промежуточному ПО](/ru /guides/middleware/).

`onRequest()`

Необходимая экспортируемая функция из src/middleware.js, которая будет вызываться перед рендерингом каждой страницы или маршрута API. Она принимает два необязательных аргумента: context и next(). onRequest() должен возвращать Response: либо напрямую, либо через вызов next().

export function onRequest (context, next) {
    // перехватываем данные ответа на запрос
    // по желанию преобразует ответ
    // возвращаем непосредственно ответ или результат вызова `next()`.
    return next();
};

`next()`

Функция, которая перехватывает (читает и изменяет) Response от Request или вызывает “следующее” промежуточное ПО в цепочке и возвращает Response. Например, эта функция может изменять HTML-тело ответа.

Это необязательный аргумент onRequest(), который может содержать требуемый Response, возвращаемый промежуточным ПО.

`sequence()`

Функция, принимающая функции промежуточного ПО в качестве аргументов и выполняющая их в том порядке, в котором они были переданы.

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

export const onRequest = sequence(validation, auth, greeting);

`createContext()`

Низкоуровневый API для создания APIContext для передачи в функцию промежуточного ПО Astro onRequest().

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

`trySerializeLocals()`

Низкоуровневый API, который принимает любое значение и пытается вернуть его сериализованную версию (строку). Если значение не может быть сериализовано, функция выдает ошибку времени выполнения.

Встроенные компоненты

Astro включает в себя несколько встроенных компонентов, которые вы можете использовать в своих проектах. Все встроенные компоненты доступны в файлах .astro через команду import {} from 'astro:components';.

`<Code />`

---
import { Code } from 'astro:components';
---
<!-- Синтаксическая подсветка некоторого кода JavaScript. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Дополнительно: Настройте свою тему. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Необязательно: Включите обертку слов. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- Необязательно: Вывод инлайн-кода. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  будет выведен в строку.
</p>

Этот компонент обеспечивает подсветку синтаксиса для блоков кода во время сборки (без использования JavaScript на стороне клиента). Компонент работает на базе Shiki и поддерживает все популярные темы и языки. Кроме того, вы можете добавлять свои собственные темы и языки, передавая их в theme и lang соответственно.

`<Fragment />`

Компонент, используемый с директивами set:* для вывода HTML-контента без дополнительных элементов обертки:

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

Подробнее об использовании фрагментов смотрите в разделе синтаксис Astro.

`<Prism />`

Чтобы использовать компонент подсветки Prism, сначала установите пакет @astrojs/prism:

npm install @astrojs/prism

pnpm add @astrojs/prism

yarn add @astrojs/prism

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

Этот компонент обеспечивает подсветку синтаксиса для блоков кода с применением CSS-классов Prism. Обратите внимание, что вам необходимо предоставить таблицу стилей Prism CSS (или использовать собственную), чтобы подсветка синтаксиса появилась! См. раздел Настройка Prism для получения более подробной информации.

Смотрите список языков, поддерживаемых Prism, где вы можете найти соответствующий языку псевдоним. Кроме того, вы можете отображать блоки кода Astro с lang="astro"!

`<Image />`

---
// импортируем компонент Image и изображение
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Изображение имеет размер 1600x900
---

<!-- `alt` является обязательным для компонента Image -->
<Image src={myImage} alt="Описание моего изображения." />

<!-- Выходные данные -->
<!-- Изображение оптимизировано, применены соответствующие атрибуты -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Описание моего изображения."
/>

Свойства

src (обязательно)
alt (обязательно)
width and height (требуется для public/ и внешних изображений)
format
quality
densities
widths

В дополнение к вышеперечисленным свойствам, компонент <Image /> принимает все свойства, принимаемые тегом HTML <img>.

Смотрите больше в Путеводителе по изображениям.

`<Picture />`

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

Используйте встроенный компонент <Picture /> Astro для отображения отзывчивого изображения с несколькими форматами и/или размерами.

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Изображение имеет размер 1600x900
---

<!-- `alt` является обязательным для компонента Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Описание моего изображения." />

<!-- Выходные данные -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Описание моего изображения".
  />
</picture>

Смотрите больше в Путеводителе по изображениям.

Properties

<Picture /> принимает все свойства компонента <Image />, плюс следующие:

`formats`

Массив форматов изображений, используемых для тегов <source>. По умолчанию установлено значение ['webp'].

`fallbackFormat`

Формат, используемый в качестве запасного значения для тега <img>. По умолчанию используется .png для статичных изображений, .gif для анимированных изображений и .svg для SVG-файлов.

`pictureAttributes`

Объект атрибутов, добавляемых к тегу <picture>. Используйте это свойство для применения атрибутов к самому внешнему элементу <picture>. Атрибуты, примененные непосредственно к компоненту <Picture />, будут применяться и к внутреннему элементу <img>, за исключением тех, которые используются для преобразования изображения.

`<Content />`

Общий компонент, используемый для отображения содержимого записи коллекции контента.

Сначала запросите одну или несколько записей с помощью getCollection() или getEntry(). Затем функция entry.render() может вернуть компонент <Content /> для использования в шаблоне файла .astro.

---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'post-1');
const { Content } = await entry.render();
---
<p>Published on: {entry.data.published.toDateString()}</p>
<Content />

`<ViewTransitions />`

Перейдите к использованию анимации переходов между страницами, импортировав и добавив компонент маршрутизации <ViewTransitions /> в <head> на каждой нужной странице.

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

Подробнее о том, как управлять маршрутизатором и добавлять директивы перехода к элементам и компонентам страницы.

`<Debug />`

---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

Этот компонент позволяет проверять значения на стороне клиента без использования JavaScript.

Справочник API

Глобальный объект Astro

Astro.glob()

Файлы Markdown

Файлы Astro

Другие файлы

Astro.props

Astro.params

Astro.request

Astro.response

Astro.cookies

get

has

set

delete

headers

AstroCookie

value

json

number

boolean

CookieGetOptions

decode

CookieSetOptions

domain

expires

httpOnly

maxAge

path

sameSite

secure

encode

Astro.redirect()

Astro.canonicalURL

Astro.url

Astro.clientAddress

Astro.site

Astro.generator

Astro.slots

Astro.slots.has()

Astro.slots.render()

Astro.self

Astro.locals

Astro.preferredLocale

Astro.preferredLocaleList

Astro.currentLocale

Контекст конечной точки

context.params

context.props

context.request

context.cookies

context.url

context.clientAddress

context.site

context.generator

context.redirect()

context.locals

getStaticPaths()

params

Передача данных с помощью props

paginate()

Свойство пагинации page

page.data

page.start

page.end

page.size

page.total

page.currentPage

page.lastPage

page.url.current

page.url.prev

page.url.next.

import.meta

Изображения (astro:assets)

getImage()

Коллекции контента (astro:content)

defineCollection()

type

schema

reference()

Глобальный объект `Astro`

`Astro.glob()`

`Astro.props`

`Astro.params`

`Astro.request`

`Astro.response`

`Astro.cookies`

`get`

`has`

`set`

`delete`

`headers`

`AstroCookie`

`value`

`json`

`number`

`boolean`

`CookieGetOptions`

`decode`

`CookieSetOptions`

`domain`

`expires`

`httpOnly`

`maxAge`

`path`

`sameSite`

`secure`

`encode`

`Astro.redirect()`

`Astro.canonicalURL`

`Astro.url`

`Astro.clientAddress`

`Astro.site`

`Astro.generator`

`Astro.slots`

`Astro.slots.has()`

`Astro.slots.render()`

`Astro.self`

`Astro.locals`

`Astro.preferredLocale`

`Astro.preferredLocaleList`

`Astro.currentLocale`

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.locals`

`getStaticPaths()`

`params`

Передача данных с помощью `props`

`paginate()`

Свойство пагинации `page`

`page.data`

`page.start`

`page.end`

`page.size`

`page.total`

`page.currentPage`

`page.lastPage`

`page.url.current`

`page.url.prev`

`page.url.next`.

`import.meta`

Изображения (`astro:assets`)

`getImage()`

Коллекции контента (`astro:content`)

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`getEntryBySlug()`

`id`