title | i18nReady |
---|---|
Справочник API |
true |
import Since from '/components/Since.astro';
import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
Глобальный объект Astro
доступен во всех контекстах в файлах .astro
. Он обладает следующими функциями:
Astro.glob()
— это способ загрузить множество локальных файлов в ваш статический сайт.
---
// src/components/my-component.astro
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()
.
:::note
Вы также можете использовать 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 имеют следующий интерфейс:
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 имеют следующий интерфейс:
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
— это объект, содержащий любые значения, которые были переданы в качестве атрибутов компонента. Компоненты макета для файлов .md
и .mdx
получают значения frontmatter в качестве props.
---
// src/components/Heading.astro
const { title, date } = Astro.props;
---
<div>
<h1>{title}</h1>
<p>{date}</p>
</div>
---
// src/pages/index.astro
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />
Узнайте больше о том, как макеты Markdown и MDX обрабатывают props.
Узнайте, как добавить определения типов TypeScript для ваших props.
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
— это стандартный объект 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
:::note
С опцией по умолчанию output: 'static'
, Astro.request.url
не содержит параметров поиска, таких как ?foo=bar
, так как невозможно определить их заранее во время статической сборки. Однако в режиме output: 'server'
, Astro.request.url
содержит параметры поиска, так как их можно определить из запроса сервера.
:::
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
содержит утилиты для чтения и работы с куки в режиме серверного рендеринга.
**Тип:** `(key: string, options?: CookieGetOptions) => AstroCookie`
Получает куки в виде объекта AstroCookie
, который содержит value
и служебные функции для преобразования куки в нестроковые типы.
**Тип:** `(key: string) => boolean`
Существует ли данный куки. Если куки были установлены через Astro.cookies.set()
, то возвращается true, в противном случае проверяются куки в Astro.request
.
**Тип:** `(key: string, value: string | number | boolean | object, options? CookieSetOptions) => void`
Устанавливает для key
куки заданное значение. При этом будет сделана попытка преобразовать значение куки в строку. Опции позволяют установить характеристики куки, такие как maxAge
или httpOnly
.
**Тип:** `(key: string, options?: CookieDeleteOptions) => void`
Помечает куки как удаленный. После удаления куки Astro.cookies.has()
вернет false
, а Astro.cookies.get()
вернет AstroCookie
с значением
undefined
. Опции позволяют задать domain
и path
удаляемого куки.
**Тип:** `() => Iterator`
Получает значения заголовков Set-Cookie
, которые будут отправлены вместе с ответом.
Получение куки с помощью Astro.cookies.get()
возвращает тип AstroCookie
. Он имеет следующую структуру.
**Тип:** `string | undefined`
Необработанное строковое значение куки.
**Тип:** `() => Record`
Разбирает значение куки с помощью JSON.parse()
, возвращая объект. Выбрасывает исключение, если значение куки не является корректным JSON.
**Тип:** `() => number`
Разбирает значение куки как число. Возвращает NaN, если число не является действительным.
**Тип:** `() => boolean`
Преобразует значение куки в логическое значение.
Получение куки также позволяет указать опции через интерфейс CookieGetOptions
:
**Тип:** `(value: string) => string`
Позволяет настраивать способ десериализации куки в значение.
Установка куки с помощью Astro.cookies.set()
позволяет передать CookieSetOptions
для настройки того, как куки будет сериализована.
**Тип:** `string`
Указывает домен. Если домен не задан, большинство клиентов будут интерпретировать применение к текущему домену.
**Тип:** `Date`
Указывает дату истечения срока действия файла куки.
**Тип:** `boolean`
Если значение равно true, куки не будет доступен на стороне клиента.
**Тип:** `number`
Указывает число в секундах, в течение которого куки будет действителен.
**Тип:** `string`
Указывает подпункт домена, в котором применяется куки.
**Тип:** `boolean | 'lax' | 'none' | 'strict'`
Определяет значение заголовка куки SameSite.
**Тип:** `boolean`
Если значение равно true, то куки будет устанавливаться только на https-сайтах.
**Тип:** `(value: string) => string`
Позволяет настроить способ сериализации куки.
Astro.redirect()
позволяет перенаправить вас на другую страницу.
Страница (а не дочерний компонент) должна возвращать
результат Astro.redirect()
, чтобы произошла переадресация.
---
import { isLoggedIn } from '../utils';
const cookie = Astro.request.headers.get('cookie');
// Если пользователь не вошел в систему, перенаправьте его на страницу входа в систему
if (!isLoggedIn(cookie)) {
return Astro.redirect('/login');
}
---
:::caution[Исправлено]
Используйте Astro.url
для построения собственного канонического URL.
:::
Канонический URL текущей страницы.
Объект 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} />
Указывает IP-адрес запроса. Это свойство доступно только при сборке для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.
---
const ip = Astro.clientAddress;
---
<div>Your IP address is: <span class="address">{ ip }</span></div>
Astro.site
возвращает URL
, созданный из site
в вашей конфигурации Astro. Если site
в вашем конфиге Astro не определен, то Astro.site
не будет определен.
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.
Тип: (slotName: string) => boolean
С помощью функции Astro.slots.has()
можно проверить, существует ли содержимое для определенного имени слота. Это может быть полезно, когда вы хотите обернуть содержимое слота, но хотите выводить элементы обертки только тогда, когда слот используется.
---
---
<slot />
{Astro.slots.has('more') && (
<aside>
<h2>More</h2>
<slot name="more" />
</aside>
)}
Тип: (slotName: string, args?: any[]) => Promise<string>
.
Вы можете асинхронно вывести содержимое слота в строку HTML с помощью Astro.slots.render()
.
---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />
:::note
Это для продвинутых случаев использования! В большинстве случаев проще выводить содержимое слота с помощью элемента <slot />
.
:::
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. Такое поведение позволяет вызывать компонент Astro изнутри самого себя, используя <Astro.self>
в шаблоне компонента. Это может быть полезно для итераций по большим хранилищам данных и вложенным структурам данных.
---
// NestedList.astro
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
— это объект, содержащий любые значения из объекта 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
— это вычисляемое значение, которое представляет предпочтительную локаль пользователя.
Оно вычисляется путем проверки настроенных локалей в вашем массиве i18n.locales
и локалей, поддерживаемых браузером пользователя через заголовок Accept-Language
. Это значение является undefined
, если такого соответствия нет.
Это свойство доступно только при создании для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.
Astro.preferredLocaleList
представляет собой массив всех локалей, которые запрашиваются браузером и поддерживаются вашим сайтом. Это позволяет получить список всех совместимых языков между вашим сайтом и посетителем.
Если ни один из запрошенных браузером языков не найден в вашем массиве локалей, то значение будет []
: вы не поддерживаете ни один из предпочитаемых посетителем локалей.
Если браузер не указывает предпочтительные языки, то это значение будет i18n.locales
: все поддерживаемые вами локали будут считаться одинаково предпочтительными для посетителя, не имеющего предпочтений.
Это свойство доступно только при создании для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.
Локаль, вычисленная из текущего URL, с использованием синтаксиса, указанного в вашей конфигурации locales
. Если URL не содержит префикса /[locale]/
, то значение по умолчанию будет равно i18n.defaultLocale
.
Функции конечных точек получают в качестве первого параметра объект контекста. Он отражает многие глобальные свойства Astro
.
import type { APIContext } from 'astro';
export function GET(context: APIContext) {
// ...
}
context.params
— это объект, содержащий значения динамических сегментов маршрута, найденных для данного запроса.
В статических сборках это будут params
, возвращаемые getStaticPaths()
, используемые для пререндеринга динамических маршрутов.
В сборках 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
— это объект, содержащий любые 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
Стандартный объект Request. С его помощью можно получить url
, headers
, method
и даже тело запроса.
import type { APIContext } from 'astro';
export function GET({ request }: APIContext) {
return new Response(`Hello ${request.url}`);
}
См. также: Astro.request
context.cookies
содержит утилиты для чтения и работы с куки.
См. также: Astro.cookies
Объект URL, построенный из текущего значения строки URL context.request.url
.
См. также: Astro.url
Указывает IP-адрес запроса. Это свойство доступно только при построении для SSR (рендеринг на стороне сервера) и не должно использоваться для статических сайтов.
import type { APIContext } from 'astro';
export function GET({ clientAddress }: APIContext) {
return new Response(`Your IP address is: ${clientAddress}`);
}
См. также: Astro.clientAddress
context.site
возвращает URL
, созданный из site
в конфигурации Astro. Если значение не определено, то возвращается URL, сгенерированный с localhost
.
См. также: Astro.site
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()
возвращает объект Response, который позволяет перенаправить вас на другую страницу. Эта функция доступна только при построении для SSR (рендеринг на стороне сервера) и не должна использоваться для статических сайтов.
import type { APIContext } from 'astro';
export function GET({ redirect }: APIContext) {
return redirect('/login', 302);
}
См. также: Astro.redirect()
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()
.
Эта функция необходима, поскольку Astro является статическим конструктором сайтов. Это означает, что весь ваш сайт создается заранее. Если Astro не знает, что нужно сгенерировать страницу во время создания, пользователи не увидят ее, когда посетят ваш сайт.
---
export async function getStaticPaths() {
return [
{ params: { /* required */ }, props: { /* optional */ } },
{ params: { ... } },
{ params: { ... } },
// ...
];
}
---
<!-- Ваш HTML-шаблон здесь. -->
Функция getStaticPaths()
должна возвращать массив объектов, чтобы определить, какие пути будут предварительно рендериться Astro.
Его также можно использовать в статических файловых конечных точках для динамической маршрутизации.
:::caution
Функция getStaticPaths()
выполняется в своей собственной изолированной области видимости один раз, до загрузки страницы. Поэтому вы не можете ссылаться на что-либо из ее родительской области, кроме импорта файлов. Компилятор выдаст предупреждение, если вы нарушите это требование.
:::
Ключ 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
для каждого возвращаемого объекта 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
:
Пагинация является распространенным случаем использования для веб-сайтов, который 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.data
), а также метаданные для страницы (page.url
, page.start
, page.end
, page.total
и т. д.). Эти метаданные полезны для таких вещей, как кнопка "Следующая страница" или сообщение "Показано 1-10 из 100".
**Тип:** `Array`
Массив данных, возвращаемых из data()
для текущей страницы.
**Тип:** `number`
Индекс первого элемента на текущей странице, начиная с 0
. (например, если pageSize: 25
, это будет 0
на странице 1, 25
на странице 2 и т. д.)
**Тип:** `number`
Индекс последнего элемента на текущей странице.
**Тип:** `number`
Сколько элементов на странице.
**Тип:** `number`
Общее количество элементов на всех страницах.
**Тип:** `number`
Номер текущей страницы, начиная с 1
.
**Тип:** `number`
Общее количество страниц.
**Тип:** `string`
Получите URL текущей страницы (полезно для канонических URL).
**Тип:** `string | undefined`
Получите URL предыдущей страницы (будет undefined
, если на странице 1).
**Тип:** `string | undefined`
Получение URL следующей страницы (будет undefined
, если больше нет страниц).
Все модули 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 />;
}
:::caution
getImage()
зависит от API, доступных только на сервере, и вызывает ошибку сборки при использовании на клиенте.
:::
Функция 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-атрибуты, необходимые для отображения изображения (ширина, высота, стиль и т. д.)
}
Коллекции контента предлагают API для настройки и запросов к вашим документам Markdown или MDX в src/content/
. О возможностях и примерах использования [см. наше руководство по коллекциям контента] (/ru/guides/content-collections/).
defineCollection()
— это утилита для настройки коллекции в файле src/content/config.*
.
// src/content/config.ts
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 };
Эта функция принимает следующие свойства:
Тип: 'content' | 'data'
По умолчанию: 'content'
type
— это строка, определяющая тип записей, хранящихся в коллекции:
'content'
— для форматов с авторским контентом, таких как Markdown (.md
), MDX (.mdx
) или Markdoc (.mdoc
)'data'
— для форматов, содержащих только данные, таких как JSON (.json
) или YAML (.yaml
)
:::tip Это означает, что коллекции не могут хранить смесь содержимого и форматов данных. Вы должны разделить эти записи на отдельные коллекции по типам. :::
Тип: TSchema extends ZodType
schema
— необязательный объект Zod для настройки типа и формы frontmatter документа для коллекции. Каждое значение должно использовать валидатор Zod.
Примеры использования см. в руководстве по коллекциям контента
.
Тип: (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 };
Примеры использования см. в руководстве Коллекции контента
.
Тип: (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;
});
---
Примеры использования см. в руководстве Коллекции контента
.
Типы:
(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);
---
Примеры запросов к записям коллекции см. в руководстве Коллекции контента
.
Типы:
(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);
---
Тип: (collection: string, slug: string) => CollectionEntry<collection>
:::caution[Исправлено]
Используйте функцию getEntry()
для запроса записей контента. Она принимает те же аргументы, что и getEntryBySlug()
, и поддерживает запрос по id
для коллекций JSON или YAML.
:::
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'>
).
Доступно для коллекций: type: 'content'
и type: 'data'
Примеры типов:
- коллекции контента:
'entry-1.md' |
'entry-2.md' | ...` - коллекции данных:
'author-1' | 'author-2' | ...
Уникальный идентификатор, использующий путь к файлу относительно src/content/[collection]
. Перечисляет все возможные строковые значения, основанные на путях к файлам записей коллекции. Обратите внимание, что коллекции определенные как type: 'content'
включают расширение файла в свой идентификатор, а коллекции, определенные как type: 'data'
, нет.
Доступно для коллекций: type: 'content'
и type: 'data'
Пример типа: 'blog' | 'authors' | ...
Имя папки верхнего уровня в разделе src/content/
, в которой находятся записи. Это имя используется для ссылок на коллекцию в вашей схеме и в функциях запросов.
Доступно для коллекций: type: 'content'
и type: 'data'
Тип: CollectionSchema<TCollectionName>
Объект свойств frontmatter, выведенных из схемы вашей коллекции (см. ссылку defineCollection()
). По умолчанию принимает значение any
, если схема не задана.
Доступно только для коллекций: type: 'content'
Пример типа: 'entry-1' | 'entry-2' | ...
Готовый к использованию в URL слаг для документов Markdown или MDX. По умолчанию используется id
без расширения файла, но может быть переопределено установкой свойства slug
в frontmatter файла.
Доступно только для коллекций: type: 'content'
Тип: string
Строка, содержащая необработанное, некомпилированное тело документа Markdown или MDX.
Доступно только для коллекций: type: 'content'
Тип: () => Promise<RenderedEntry>
Функция для компиляции заданного документа Markdown или MDX для визуализации. Возвращает следующие свойства:
<Content />
— компонент, используемый для отображения содержимого документа в файле Astro.Заголовки
— Сгенерированный список заголовков, зеркальное отражение утилиты AstrogetHeadings()
при импорте 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:
Строковое объединение всех имен коллекций, определенных в вашем файле src/content/config.*
. Этот тип может быть полезен при определении общей функции, принимающей любое имя коллекции.
import type { CollectionKey, getCollection } from 'astro:content';
async function getCollection(collection: CollectionKey) {
return getCollection(collection);
}
Строковое объединение всех имен коллекций type: 'content'
, определенных в вашем файле src/content/config.*
.
Строковое объединение всех имен коллекции type: 'data'
, определенных в вашем файле src/content/config.*
.
Объект 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 })
}),
});
Промежуточное ПО позволяет перехватывать запросы и ответы и динамически внедрять поведение каждый раз, когда страница или конечная точка собираются быть отображенными. О возможностях и примерах использования [см. наше руководство по промежуточному ПО](/ru /guides/middleware/).
Необходимая экспортируемая функция из src/middleware.js
, которая будет вызываться перед рендерингом каждой страницы или маршрута API. Она принимает два необязательных аргумента: context и next(). onRequest()
должен возвращать Response
: либо напрямую, либо через вызов next()
.
export function onRequest (context, next) {
// перехватываем данные ответа на запрос
// по желанию преобразует ответ
// возвращаем непосредственно ответ или результат вызова `next()`.
return next();
};
Функция, которая перехватывает (читает и изменяет) Response
от Request
или вызывает "следующее" промежуточное ПО в цепочке и возвращает Response
. Например, эта функция может изменять HTML-тело ответа.
Это необязательный аргумент onRequest()
, который может содержать требуемый Response
, возвращаемый промежуточным ПО.
Функция, принимающая функции промежуточного ПО в качестве аргументов и выполняющая их в том порядке, в котором они были переданы.
import { sequence } from "astro:middleware";
async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}
export const onRequest = sequence(validation, auth, greeting);
Низкоуровневый API для создания APIContext
для передачи в функцию промежуточного ПО Astro onRequest()
.
Эта функция может использоваться интеграциями/адаптерами для программного выполнения промежуточного программного обеспечения Astro.
Низкоуровневый API, который принимает любое значение и пытается вернуть его сериализованную версию (строку). Если значение не может быть сериализовано, функция выдает ошибку времени выполнения.
Этот модуль предоставляет функции, помогающие создавать URL-адреса с использованием настроенных локалей вашего проекта.
Создание маршрутов для вашего проекта с помощью маршрутизатора i18n будет зависеть от некоторых установленных вами значений конфигурации, которые влияют на маршруты страниц. При создании маршрутов с помощью этих функций обязательно учитывайте индивидуальные настройки для:
Также обратите внимание, что возвращаемые URL, созданные этими функциями для вашей defaultLocale
, будут отражать вашу конфигурацию i18n.routing
.
Про возможности и примеры использования см. в нашем руководстве по многоязычной маршрутизации.
getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string
Используйте эту функцию для получения относительного пути к локали. Если локаль не существует, Astro выдает ошибку.
---
getRelativeLocaleUrl("fr");
// возвращает /fr
getRelativeLocaleUrl("fr", "");
// возвращает /fr
getRelativeLocaleUrl("fr", "getting-started");
// возвращает /fr/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
// возвращает /blog/fr-ca/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
// возвращает /blog/fr_CA/getting-started
---
getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string
Используйте эту функцию для получения абсолютного пути к локали, если для параметра [site
] установлено значение. Если параметр [site
] не задан, функция возвращает относительный URL-адрес. Если локаль не существует, Astro выдает ошибку.
---
// Если для параметра `site` задано значение `https://example.com`
getAbsoluteLocaleUrl("fr");
// возвращает https://example.com/fr
getAbsoluteLocaleUrl("fr", "");
// возвращает https://example.com/fr
getAbsoluteLocaleUrl("fr", "getting-started");
// возвращает https://example.com/fr/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
// возвращает https://example.com/blog/fr-ca/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
// возвращает https://example.com/blog/fr_CA/getting-started
---
getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]
Используйте это как getRelativeLocaleUrl
, чтобы вернуть список относительных путей для всех локалей.
getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]
Используйте это как getAbsoluteLocaleUrl
, чтобы вернуть список абсолютных путей для всех локалей.
getPathByLocale(locale: string): string
Функция, возвращающая path
, связанный с одним или несколькими codes
, когда настроены пользовательские пути локалей.
export default defineConfig({
i18n: {
locales: ["es", "en", {
path: "french",
codes: ["fr", "fr-BR", "fr-CA"]
}]
}
})
---
getPathByLocale("fr"); // возвращает "french"
getPathByLocale("fr-CA"); // возвращает "french"
---
getLocaleByPath(path: string): string
Функция, возвращающая code
, связанный с path
локали.
export default defineConfig({
i18n: {
locales: ["es", "en", {
path: "french",
codes: ["fr", "fr-BR", "fr-CA"]
}]
}
})
---
getLocaleByPath("french"); // возвращает "fr", потому что это первый настроенный код
---
redirectToDefaultLocale(context: APIContext, statusCode?: ValidRedirectStatus): Promise<Response>
:::note
Доступно только если для параметра i18n.routing
установлено значение "manual"
.
:::
Функция, возвращающая Response
, который перенаправляет на настроенный defaultLocale
. Он принимает необязательный действительный код состояния перенаправления.
import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";
export const onRequest = defineMiddleware((context, next) => {
if (context.url.pathname.startsWith("/about")) {
return next();
} else {
return redirectToDefaultLocale(context, 302);
}
})
redirectToFallback(context: APIContext, response: Response): Promise<Response>
:::note
Доступно только если для параметра i18n.routing
установлено значение "manual"
.
:::
Функция, позволяющая использовать вашу конфигурацию i18n.fallback
в вашем собственном промежуточном ПО.
import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";
export const onRequest = defineMiddleware(async (context, next) => {
const response = await next();
if (response.status >= 300) {
return redirectToFallback(context, response)
}
return response;
})
notFound(context: APIContext, response: Response): Promise<Response>
:::note
Доступно только если для параметра i18n.routing
установлено значение "manual"
.
:::
Используйте эту функцию в промежуточном ПО маршрутизации, чтобы возвращать сообщение 404, когда:
- текущий путь не является корневым, например:
/
или/<base>
- URL-адрес не содержит локали
Когда передается Response
, новый Response
, выдаваемый этой функцией, будет содержать те же заголовки, что и исходный ответ.
import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";
export const onRequest = defineMiddleware((context, next) => {
const pathNotFound = notFound(context);
if (pathNotFound) {
return pathNotFound;
}
return next();
})
middleware(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean })
:::note
Доступно только если для параметра i18n.routing
установлено значение "manual"
.
:::
Функция, позволяющая программно создать промежуточное ПО Astro i18n.
Это удобно, когда вы хотите использовать стандартную логику i18n, но добавить лишь несколько исключений на свой сайт.
import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";
const customLogic = defineMiddleware(async (context, next) => {
const response = await next();
// Пользовательская логика после разрешения ответа.
// Можно перехватить ответ, приходящий от промежуточного ПО Astro i18n.
return response;
});
export const onRequest = sequence(customLogic, middleware({
prefixDefaultLocale: true,
redirectToDefaultLocale: false
}))
requestHasLocale(context: APIContext): boolean
:::note
Доступно только если для параметра i18n.routing
установлено значение "manual"
.
:::
Проверяет, содержит ли текущий URL-адрес настроенную локаль. Внутренне эта функция будет использовать APIContext#url.pathname
.
import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";
export const onRequest = defineMiddleware(async (context, next) => {
if (requestHasLocale(context)) {
return next();
}
return new Response("Not found", { status: 404 });
})
Astro включает в себя несколько встроенных компонентов, которые вы можете использовать в своих проектах. Все встроенные компоненты доступны в файлах .astro
через команду import {} from 'astro:components';
.
---
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
соответственно.
Компонент, используемый с директивами set:*
для вывода HTML-контента без дополнительных элементов обертки:
---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />
Подробнее об использовании фрагментов смотрите в разделе синтаксис Astro.
Чтобы использовать компонент подсветки Prism
, сначала установите пакет @astrojs/prism
:
---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />
Этот компонент обеспечивает подсветку синтаксиса для блоков кода с применением CSS-классов Prism. Обратите внимание, что вам необходимо предоставить таблицу стилей Prism CSS (или использовать собственную), чтобы подсветка синтаксиса появилась! См. раздел Настройка Prism для получения более подробной информации.
Смотрите список языков, поддерживаемых Prism, где вы можете найти соответствующий языку псевдоним. Кроме того, вы можете отображать блоки кода Astro с lang="astro"
!
---
// импортируем компонент 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 для отображения отзывчивого изображения с несколькими форматами и/или размерами.
---
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>
Смотрите больше в Путеводителе по изображениям.
<Picture />
принимает все свойства компонента <Image />
, плюс следующие:
Массив форматов изображений, используемых для тегов <source>
. По умолчанию установлено значение ['webp']
.
Формат, используемый в качестве запасного значения для тега <img>
. По умолчанию используется .png
для статичных изображений, .gif
для анимированных изображений и .svg
для SVG-файлов.
Объект атрибутов, добавляемых к тегу <picture>
. Используйте это свойство для применения атрибутов к самому внешнему элементу <picture>
. Атрибуты, примененные непосредственно к компоненту <Picture />
, будут применяться и к внутреннему элементу <img>
, за исключением тех, которые используются для преобразования изображения.
Общий компонент, используемый для отображения содержимого записи коллекции контента.
Сначала запросите одну или несколько записей с помощью 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 />
в <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>
Подробнее о том, как управлять маршрутизатором и добавлять директивы перехода к элементам и компонентам страницы.
---
import { Debug } from 'astro:components';
const serverObject = {
a: 0,
b: "string",
c: {
nested: "object"
}
}
---
<Debug {serverObject} />
Этот компонент позволяет проверять значения на стороне клиента без использования JavaScript.