diff --git a/src/content/docs/ru/basics/astro-components.mdx b/src/content/docs/ru/basics/astro-components.mdx index 7f7ab3ed42dfc..106b0e6939f7f 100644 --- a/src/content/docs/ru/basics/astro-components.mdx +++ b/src/content/docs/ru/basics/astro-components.mdx @@ -73,7 +73,7 @@ const data = await fetch('SOME_SECRET_API_URL/users').then(r => r.json()); Если вы напишете здесь простой HTML, ваш компонент будет отображать этот HTML на любой странице Astro, в которую он импортирован и используется. -Однако, [синтаксис Astro](/ru/reference/astro-syntax/) так же поддерживает **JavaScript выражения**, теги [` - ``` - - - -## Использование Fontsource - -Проект [Fontsource](https://fontsource.org/) упрощает использование Google Fonts и других шрифтов с открытым исходным кодом. Он предоставляет npm-модули, которые вы можете установить для нужных вам шрифтов. - - -1. Найдите шрифт, который хотите использовать, в [каталоге Fontsource](https://fontsource.org/). В этом примере будет использоваться [Twinkle Star](https://fontsource.org/fonts/twinkle-star). - -2. Установите пакет для выбранного вами шрифта. - - - - ```shell - npm install @fontsource/twinkle-star - ``` - - - ```shell - pnpm add @fontsource/twinkle-star - ``` - - - ```shell - yarn add @fontsource/twinkle-star - ``` - - - - :::tip - Вы найдете правильное имя пакета в разделе "Быстрая установка" на странице каждого шрифта на сайте Fontsource. Оно начнется с `@fontsource/`, за которым следует название шрифта. - ::: - -3. Импортируйте пакет шрифта в компонент, где хотите использовать шрифт. Обычно это нужно сделать в общем компоненте макета, чтобы шрифт был доступен на всем сайте. - - Импорт автоматически добавит правила `@font-face`, необходимые для установки шрифта. - - ```astro title="src/layouts/BaseLayout.astro" - --- - import '@fontsource/twinkle-star'; - --- - ``` - -4. В качестве значения `font-family` используйте название шрифта, как показано в примере `body` на странице Fontsource. Это будет работать везде, где вы можете написать CSS в вашем проекте Astro. - - ```css - h1 { - font-family: "Twinkle Star", cursive; - } - ``` - - - -## Добавление шрифтов с Tailwind - -Если вы используете интеграцию [Tailwind](/ru/guides/integrations-guide/tailwind/), вы можете использовать любой из предыдущих методов на этой странице для установки вашего шрифта, с некоторыми изменениями. Вы можете либо добавить [`@font-face` правило для локального шрифта](#использование-локального-файла-шрифта), либо использовать стратегию [`импорта` Fontsource](#использование-fontsource) для установки шрифта. - -Чтобы добавить ваш шрифт в Tailwind: - - -1. Следуйте любому из приведенных выше руководств, но пропустите последний шаг добавления `font-family` в CSS. -2. Добавьте название шрифта в файл `tailwind.config.mjs`. - - Этот пример добавляет шрифт `Inter` в стек шрифтов sans-serif, со шрифтами по умолчанию из Tailwind CSS. - - ```js title="tailwind.config.mjs" ins={1,8-10} - import defaultTheme from 'tailwindcss/defaultTheme' - - /** @type {import('tailwindcss').Config} */ - export default { - content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'], - theme: { - extend: { - fontFamily: { - sans: ['Inter', ...defaultTheme.fontFamily.sans], - }, - }, - }, - plugins: [], - } - ``` - - - -Теперь весь текст sans-serif (по умолчанию в Tailwind) в вашем проекте будет использовать выбранный вами шрифт, а класс `font-sans` будет также применять шрифт Inter. - -Дополнительные сведения см. в [Документации Tailwind по добавлению пользовательских шрифтов](https://tailwindcss.com/docs/font-family#using-custom-values). - -## Дополнительные ресурсы - -- Узнайте, как работают веб-шрифты, в [Руководстве MDN по веб-шрифтам](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts). -- Сгенерируйте CSS для своего шрифта с помощью [Font Squirrel's Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator). \ No newline at end of file diff --git a/src/content/docs/ru/guides/integrations-guide/db.mdx b/src/content/docs/ru/guides/integrations-guide/db.mdx deleted file mode 100644 index 20f3b64df247b..0000000000000 --- a/src/content/docs/ru/guides/integrations-guide/db.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -type: integration -title: '@astrojs/db' -description: Узнайте, как использовать интеграцию @astrojs/db в вашем проекте Astro. -githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/db/' -category: other -i18nReady: true ---- -import { FileTree } from '@astrojs/starlight/components'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; -import ReadMore from '~/components/ReadMore.astro'; - - - -Astro DB - это полностью управляемая база данных SQL, разработанная для экосистемы Astro: разрабатывайте локально в Astro и развертывайте из вашей [панели управления Astro Studio](/ru/guides/astro-db/#astro-studio). - -С Astro DB у вас есть мощное, локальное, типобезопасное средство для запросов и моделирования контента в виде реляционной базы данных. Просматривайте, управляйте и развертывайте свои удаленные хостинговые данные через вашу интерактивную панель управления Studio. - -См. [руководство по Astro DB](/ru/guides/astro-db/) для полного описания использования и примеров. - -## Установка - -Astro включает команду `astro add` для автоматизации установки официальных интеграций. При желании вы также можете [установить интеграции вручную](#установка-вручную). - -Запустите одну из следующих команд в новом окне терминала. - - - - ```sh - npx astro add db - ``` - - - ```sh - pnpm astro add db - ``` - - - ```sh - yarn astro add db - ``` - - - -#### Установка вручную - -Если вы предпочитаете устанавливать все с нуля самостоятельно, пропустите `astro add` и следуйте этим инструкциям, чтобы установить Astro DB самостоятельно. - -##### 1. Установите интеграцию из npm с помощью менеджера пакетов - - - - ```shell - npm install @astrojs/db - ``` - - - ```shell - pnpm add @astrojs/db - ``` - - - ```shell - yarn add @astrojs/db - ``` - - - -##### 2. Добавьте интеграцию в `astro.config.mjs` - - ```js title="astro.config.mjs" ins={2,6} - import { defineConfig } from 'astro/config'; - import db from '@astrojs/db'; - - export default defineConfig({ - integrations: [ - db() - ] - }); - ``` - -##### 3. Настройте вашу базу данных - -Создайте файл `db/config.ts` в корне вашего проекта. Это специальный файл, который Astro будет автоматически загружать и использовать для настройки таблиц вашей базы данных. - -```ts -// db/config.ts -import { defineDb } from 'astro:db'; - -export default defineDb({ - tables: {}, -}) -``` - -## Справочник по конфигурации таблиц - -### `columns` - -Столбцы таблицы настраиваются с использованием объекта `columns`: - -```ts -import { defineTable, column, NOW } from 'astro:db'; - -const Comment = defineTable({ - columns: { - id: column.number({ primaryKey: true }), - author: column.text(), - content: column.text({ optional: true }), - published: column.date({ default: NOW }), - }, -}); -``` - -Столбцы настраиваются с использованием утилиты `column`. `column` поддерживает следующие типы: - -- **`column.text(...)`** - храните простой или разнообразный текстовый контент -- **`column.number(...)`** - храните целочисленные и числовые значения с плавающей запятой -- **`column.boolean(...)`** - храните значения true / false -- **`column.date(...)`** - храните объекты `Date`, разобранные как строковые значения ISO для хранения данных -- **`column.json(...)`** - храните произвольные JSON-объекты, разобранные как строковые JSON для хранения данных - -Есть несколько общих значений конфигурации для всех столбцов: - -- `primaryKey` - Установите столбец типа `number` или `text` как уникальный идентификатор. -- `optional` - По умолчанию Astro DB использует `NOT NULL` для всех столбцов. Установите `optional` в `true`, чтобы разрешить значения null. -- `default` - Установите значение по умолчанию для новых записей. Это принимает либо статическое значение, либо строку `sql` для сгенерированных значений, таких как метки времени. -- `unique` - Пометьте столбец как уникальный. Это предотвращает дублирование значений в таблице. -- `references` - Ссылка на связанную таблицу по столбцу. Это создает ограничение внешнего ключа, что означает, что каждое значение столбца должно иметь соответствующее значение в ссылочной таблице. - -### `indexes` - -Индексы таблиц используются для повышения скорости поиска по заданному столбцу или комбинации столбцов. Свойство `indexes` принимает объект с уникальным именем индекса в качестве ключа: - -```ts title="db/config.ts" {6-8} -import { defineTable, column } from 'astro:db'; - -const Comment = defineTable({ - columns: { - authorId: column.number(), - body: column.text(), - }, - indexes: { - author_idx: { on: ["authorId"], unique: true }, - }, -}); -``` - -Для каждого индекса доступны следующие параметры конфигурации: - -- `on`: `string | string[]` - Один столбец или массив имен столбцов для индексации. -- `unique`: `boolean` - Установите значение `true` для обеспечения уникальности значений в индексируемых столбцах. - -### `foreignKeys` - -:::tip - -`foreignKeys` - это расширенный API для связи нескольких столбцов таблицы. Если вам нужно сослаться только на один столбец, попробуйте использовать [свойство столбца `references`](#columns) - -::: - -Внешние ключи используются для установления связи между двумя таблицами. Свойство `foreignKeys` принимает массив объектов конфигурации, которые могут связывать один или несколько столбцов между таблицами: - -```ts title="db/config.ts" {12-20} -import { defineTable, column } from 'astro:db'; - -const Author = defineTable({ - columns: { - firstName: column.text(), - lastName: column.text(), - }, -}); - -const Comment = defineTable({ - columns: { - authorFirstName: column.text(), - authorLastName: column.text(), - body: column.text(), - }, - foreignKeys: [ - { - columns: ["authorFirstName", "authorLastName"], - references: () => [Author.columns.firstName, Author.columns.lastName], - }, - ], -}); -``` - -Каждый объект конфигурации внешнего ключа принимает следующие свойства: - -- `columns`: `string[]` - Массив имен столбцов для связи со ссылающейся таблицей. -- `references`: `() => Column[]` - Функция, возвращающая массив столбцов из таблицы, на которую ссылается объект. - -## Справочник по CLI Astro DB - -Astro DB включает в себя набор команд CLI для взаимодействия с базой данных вашего проекта на хостинге и учетной записью [Astro Studio](/ru/guides/astro-db/#astro-studio). - -Эти команды вызываются автоматически при использовании действия GitHub CI, а также могут быть вызваны вручную с помощью CLI `astro db`. - -### `astro db push` - -**Флаги:** - -- `--force-reset` Сбросьте все производственные данные, если требуется изменение структуры данных. - -Безопасно отправьте изменения конфигурации базы данных в вашу проектную базу данных. Это проверит наличие риска потери данных и поможет вам с любыми рекомендуемыми шагами миграции. Если необходимо сделать изменение структуры данных, используйте флаг `--force-reset`, чтобы сбросить все производственные данные. - - -### `astro db verify` - -Проверьте, нет ли различий между конфигурациями локальной и удаленной баз данных. Эта проверка выполняется автоматически при запуске `astro db push`. `verify` сравнит ваш локальный файл `db/config.ts` с удаленной базой данных и предупредит, если будут обнаружены изменения. - -### `astro db execute ` - -**Флаги:** - -- `--remote` Выполнить в вашей проектной базе данных Studio. Не указывайте для запуска на вашем сервере разработки. - -Выполняет файл `.ts` или `.js` для чтения или записи в вашу базу данных. Принимает путь к файлу в качестве аргумента и поддерживает использование модуля `astro:db` для написания безопасных для типов запросов. Используйте флаг `--remote` для запуска с базой данных проекта Studio, или опустите этот флаг для запуска с сервером разработки. Пример файла см. в разделе [заполнить данные разработки](/ru/guides/astro-db/#заполнение-вашей-базы-данных). - - -### `astro db shell --query ` - -**Флаги:** - -- `--query` Сырой SQL-запрос для выполнения. -- `--remote` Выполнить в вашей проектной базе данных Studio. Опустите, чтобы выполнить на вашем сервере разработки. - -Выполните необработанный SQL-запрос к вашей базе данных. Используйте флаг `--remote` для выполнения в базе данных проекта Studio или опустите этот флаг для выполнения на сервере разработки. - -## Справочник по утилитам Astro DB - -### `isDbError()` - -Функция `isDbError()` проверяет, является ли ошибка исключением базы данных libSQL. Это может быть ошибка ограничения внешнего ключа при использовании ссылок или отсутствие полей при вставке данных. Вы можете комбинировать `isDbError()` с блоком try / catch для обработки ошибок базы данных в вашем приложении: - -```ts title="src/pages/api/comment/[id].ts" "idDbError" -import { db, Comment, isDbError } from 'astro:db'; -import type { APIRoute } from 'astro'; - -export const POST: APIRoute = (ctx) => { - try { - await db.insert(Comment).values({ - id: ctx.params.id, - content: 'Hello, world!' - }); - } catch (e) { - if (isDbError(e)) { - return new Response(`Невозможно вставить комментарий с id ${id}\n\n${e.message}`, { status: 400 }); - } - return new Response('Произошла непредвиденная ошибка', { status: 500 }); - } - - return new Response(null, { status: 201 }); -}; -``` diff --git a/src/content/docs/ru/guides/integrations-guide/index.mdx b/src/content/docs/ru/guides/integrations-guide/index.mdx deleted file mode 100644 index 2af95215bd265..0000000000000 --- a/src/content/docs/ru/guides/integrations-guide/index.mdx +++ /dev/null @@ -1,269 +0,0 @@ ---- -title: Добавление интеграций -i18nReady: true ---- - -import IntegrationsNav from '~/components/IntegrationsNav.astro' -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' -import { Steps } from '@astrojs/starlight/components' - - -**Интеграции Astro** добавляют новый функционал и возможности в ваш проект всего за несколько строк кода. Вы можете написать собственную интеграцию, использовать официальную интеграцию или интеграцию, созданную сообществом. - -Интеграции могут... - -- Добавить React, Vue, Svelte, Solid и другие популярные фреймворки пользовательского интерфейса. -- Интегрировать такие инструменты, как Tailwind и Partytown, с помощью нескольких строк кода. -- Добавлять новые функции в ваш проект, например автоматическую генерацию карты сайта. -- Писать пользовательский код, который встраивается в процесс сборки, серверу разработки и т. д. - -:::tip[Каталог интеграций] -Просматривайте или выполняйте поиск по полному набору сотен официальных и общественных интеграций в нашем [каталоге интеграций](https://astro.build/integrations/). Найдите пакеты для добавления в ваш проект Astro для аутентификации, аналитики, производительности, SEO, доступности, пользовательского интерфейса, инструментов разработчика и многого другого. -::: - - -## Официальные интеграции - -Следующие интеграции поддерживаются Astro. - - - -## Автоматическая настройка интеграций - -Astro включает команду `astro add` для автоматической установки официальных интеграций. Некоторые плагины сообщества также могут быть добавлены с помощью этой команды. Пожалуйста, проверьте в документации к каждой интеграции, поддерживается ли `astro add`, или вы должны [установить вручную](#установка-вручную). - -Запустите команду `astro add` с помощью выбранного вами менеджера пакетов, и наш автоматический мастер интеграции обновит ваш конфигурационный файл и установит все необходимые зависимости. - - - - ```shell - npx astro add react - ``` - - - ```shell - pnpm astro add react - ``` - - - ```shell - yarn astro add react - ``` - - - -Можно даже добавить несколько интеграций одновременно! - - - - ```shell - npx astro add react tailwind partytown - ``` - - - ```shell - pnpm astro add react tailwind partytown - ``` - - - ```shell - yarn astro add react tailwind partytown - ``` - - - -:::note[Обработка интеграционных зависимостей] -Если после добавления интеграции вы видите предупреждения вроде `Cannot find package '[package-name]'`, ваш менеджер пакетов, возможно, не установил для вас [peer зависимости](https://nodejs.org/en/blog/npm/peer-dependencies/). Чтобы установить эти недостающие пакеты, выполните команду `npm install [имя-пакета]`. -::: - -### Установка вручную - -Интеграции Astro всегда добавляются через свойство `integrations` в вашем файле `astro.config.mjs`. - -Существует три основных способа импортировать интеграцию в ваш проект Astro: -1. [Установить интеграцию из пакета npm](#установка-пакета-npm). -2. Импортировать собственную интеграцию из локального файла внутри проекта. -3. Написать свою интеграцию встроенно, прямо в вашем конфигурационном файле. - - ```js - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import installedIntegration from '@astrojs/vue'; - import localIntegration from './my-integration.js'; - - export default defineConfig({ - integrations: [ - // 1. Импортируется из установленного пакета npm - installedIntegration(), - // 2. Импортируется из локального JS-файла - localIntegration(), - // 3. Встроенный объект - {name: 'namespace:id', hooks: { /* ... */ }}, - ] - }); - ``` - -Ознакомьтесь со справочником [API интеграций](/ru/reference/integrations-reference/), чтобы узнать о различных способах написания интеграции. - -#### Установка пакета NPM - -Установите интеграцию пакета NPM с помощью менеджера пакетов, а затем обновите `astro.config.mjs` вручную. - -Например, чтобы установить интеграцию `@astrojs/sitemap`: - - -1. Установите интеграцию в зависимости проекта с помощью предпочитаемого менеджера пакетов: - - - - ```shell - npm install @astrojs/sitemap - ``` - - - ```shell - pnpm add @astrojs/sitemap - ``` - - - ```shell - yarn add @astrojs/sitemap - ``` - - - -2. Импортируйте интеграцию в файл `astro.config.mjs` и добавьте ее в массив `integrations[]` вместе с любыми параметрами конфигурации: - - ```js title="astro.config.mjs" ins={2} ins="sitemap()" - import { defineConfig } from 'astro/config'; - import sitemap from '@astrojs/sitemap'; - - export default defineConfig({ - // ... - integrations: [sitemap()], - // ... - }); - ``` - - Обратите внимание, что у разных интеграций могут быть разные настройки конфигурации. Прочитайте документацию по каждой интеграции и примените все необходимые параметры конфигурации к выбранной вами интеграции в файле `astro.config.mjs`. - - -### Пользовательские опции - -Интеграции почти всегда создаются как фабричные функции, которые возвращают фактический объект интеграции. Это позволяет передавать в функцию аргументы и параметры, которые настраивают интеграцию для вашего проекта. - -```js -integrations: [ - // Пример: Настройка интеграции с помощью аргументов функции - sitemap({filter: true}) -] -``` - -### Переключить интеграцию - -Интеграции, возвращающие ложные значения, игнорируются, поэтому вы можете включать и отключать интеграции без беспокойства об оставленных `undefined` и булевых значениях. - -```js -integrations: [ - // Пример: Пропуск создания карты сайта в Windows - process.platform !== 'win32' && sitemap() -] -``` - -## Обновление интеграций - -Чтобы обновить все официальные интеграции сразу, выполните команду `@astrojs/upgrade`. Это приведет к обновлению Astro и всех официальных интеграций до последних версий. - -### Автоматическое обновление - - - - ```shell - # Обновление Astro и официальных интеграций до последних версий - npx @astrojs/upgrade - ``` - - - ```shell - # Обновление Astro и официальных интеграций до последних версий - pnpm dlx @astrojs/upgrade - ``` - - - ```shell - # Обновление Astro и официальных интеграций до последних версий - yarn dlx @astrojs/upgrade - ``` - - - -### Обновление вручную - -Чтобы обновить одну или несколько интеграций вручную, используйте соответствующую команду для вашего менеджера пакетов. - - - - ```shell - # Пример: обновление интеграций React и Tailwind - npm install @astrojs/react@latest @astrojs/tailwind@latest - ``` - - - ```shell - # Пример: обновление интеграций React и Tailwind - pnpm add @astrojs/react@latest @astrojs/tailwind@latest - ``` - - - ```shell - # Пример: обновление интеграций React и Tailwind - yarn add @astrojs/react@latest @astrojs/tailwind@latest - ``` - - - -## Удаление интеграции - -Чтобы удалить интеграцию, сначала удалите ее из проекта - - - - ```shell - npm uninstall @astrojs/react - ``` - - - ```shell - pnpm remove @astrojs/react - ``` - - - ```shell - yarn remove @astrojs/react - ``` - - - -Далее удалите интеграцию из файла `astro.config.*`: - -```js title="astro.config.mjs" del={3,7} -import { defineConfig } from 'astro/config'; - -import react from '@astrojs/react'; - -export default defineConfig({ - integrations: [ - react() - ] -}); -``` - -## Поиск Дополнительных Интеграций - -Вы можете найти множество интеграций, разработанных сообществом, в [Каталоге Интеграций Astro](https://astro.build/integrations/). Переходите по ссылкам, чтобы получить подробные инструкции по использованию и настройке. - -## Создание Собственной Интеграции - -API Интеграции Astro вдохновлен Rollup и Vite и разработан так, чтобы быть знакомым любому, кто когда-либо писал плагин Rollup или Vite. - -Ознакомьтесь со справочником [по API Интеграций](/ru/reference/integrations-reference/), чтобы узнать, что могут делать интеграции и как написать свою собственную. \ No newline at end of file diff --git a/src/content/docs/ru/guides/internationalization.mdx b/src/content/docs/ru/guides/internationalization.mdx index 9198522774e9f..096306d346b68 100644 --- a/src/content/docs/ru/guides/internationalization.mdx +++ b/src/content/docs/ru/guides/internationalization.mdx @@ -15,7 +15,7 @@ import Since from '~/components/Since.astro' ## Логика маршрутизации -Astro использует [мидлвары](/ru/guides/middleware/) для реализации своей логики маршрутизации. Функция мидлвара размещается в [первой позиции](/ru/guides/middleware/#цепочка-мидлваров), где она ожидает каждого `Response`, поступающего от любого дополнительного мидлвара, и каждого маршрута страницы, прежде чем, наконец, выполнить свою собственную логику. +Astro использует [мидлвары](/ru/guides/middleware/) для реализации своей логики маршрутизации. Функция мидлвара размещается в [первой позиции](/ru/guides/middleware/#chaining-middleware), где она ожидает каждого `Response`, поступающего от любого дополнительного мидлвара, и каждого маршрута страницы, прежде чем, наконец, выполнить свою собственную логику. Это означает, что сначала выполняются операции (например, перенаправления) из вашего собственного мидлвара и логики вашей страницы, визуализируются ваши маршруты, а затем мидлвар i18n выполняет свои собственные действия, такие как проверка соответствия локализованного URL-адреса допустимому маршруту. @@ -292,7 +292,7 @@ export default defineConfig({ Когда страница на одном языке не существует (например, страница, которая ещё не переведена), вместо отображения страницы 404 вы можете выбрать отображение резервного контента из другой `locale` на основе языка. Это полезно, когда у вас ещё нет страницы для каждого маршрута, но вы хотите предоставить некоторый контент вашим посетителям. -Ваша стратегия резервирования состоит из двух частей: выбор языков, которые должны стать резервными ([`i18n.fallback`](/ru/reference/configuration-reference/#i18nfallback)), и включение [перенаправления](/ru/guides/routing/#переадресация) или [переписывание](/ru/guides/routing/#переписывания) для отображения резервного контента ([`i18n.routing.fallbackType`](/ru/reference/configuration-reference/#i18nroutingfallbacktype) — это было добавлено в Astro v4.15.0). +Ваша стратегия резервирования состоит из двух частей: выбор языков, которые должны стать резервными ([`i18n.fallback`](/ru/reference/configuration-reference/#i18nfallback)), и включение [перенаправления](/ru/guides/routing/#redirects) или [переписывание](/ru/guides/routing/#rewrites) для отображения резервного контента ([`i18n.routing.fallbackType`](/ru/reference/configuration-reference/#i18nroutingfallbacktype) — это было добавлено в Astro v4.15.0). Например, когда вы настраиваете `i18n.fallback: { fr: "ru" }`, Astro обеспечит создание страницы в `src/pages/fr/` для каждой страницы, которая существует в `src/pages/ru/`. diff --git a/src/content/docs/ru/guides/markdown-content.mdx b/src/content/docs/ru/guides/markdown-content.mdx deleted file mode 100644 index a4462d3b7ccb7..0000000000000 --- a/src/content/docs/ru/guides/markdown-content.mdx +++ /dev/null @@ -1,417 +0,0 @@ ---- -title: Markdown в Astro -sidebar: - label: Markdown -description: Узнайте о встроенной поддержке Markdown в Astro. -i18nReady: true ---- -import Since from '~/components/Since.astro'; -import { FileTree } from '@astrojs/starlight/components'; -import RecipeLinks from "~/components/RecipeLinks.astro"; -import ReadMore from '~/components/ReadMore.astro'; -import { Steps } from '@astrojs/starlight/components'; - -[Markdown](https://daringfireball.net/projects/markdown/) часто используется для создания текстового контента, такого как посты в блогах и документация. Astro включает встроенную поддержку файлов Markdown, которые также могут содержать [метаданные YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) (или [TOML](https://toml.io)) для определения пользовательских свойств, таких как заголовок, описание и теги. - -В Astro вы можете создавать контент в [GitHub Flavored Markdown](https://github.github.com/gfm/), а затем отображать его в компонентах `.astro`. Это сочетает привычный формат написания, предназначенный для контента, с гибкостью синтаксиса и архитектуры компонентов Astro. - -:::tip -Для дополнительной функциональности, такой как включение компонентов и выражений JSX в Markdown, добавьте интеграцию [`@astrojs/mdx`](/ru/guides/integrations-guide/mdx/), чтобы писать ваш Markdown-контент с использованием [MDX](https://mdxjs.com/). -::: - -## Организация файлов Markdown - -Ваши локальные файлы Markdown могут находиться в любом месте внутри директории `src/`. Файлы Markdown, расположенные в `src/pages/`, автоматически генерируют [страницы Markdown на вашем сайте](#отдельные-страницы-markdown). - -Ваш Markdown-контент и метаданные доступны для использования в компонентах через [импорт локальных файлов](#импорт-markdown) или при [запросе и отображении данных, полученных с помощью функций-хелперов коллекций контента](#markdown-из-запросов-коллекций-контента). - -### Импорт файлов в сравнении с запросами коллекций контента - -Локальные файлы Markdown можно импортировать в компонентах `.astro` с использованием оператора `import` для одного файла и [функции `import.meta.glob()` от Vite](/ru/guides/imports/#importmetaglob) для запроса нескольких файлов одновременно. [Экспортированные данные из этих файлов Markdown](#импорт-markdown) затем можно использовать в компоненте `.astro`. - -Если у вас есть группы связанных файлов Markdown, рассмотрите возможность [определения их как коллекций](/ru/guides/content-collections/). Это даёт несколько преимуществ, включая возможность хранить файлы Markdown в любом месте файловой системы или удалённо. - -Коллекции используют специализированные API для [запроса и отображения вашего Markdown-контента](#markdown-из-запросов-коллекций-контента) вместо импорта файлов. Коллекции предназначены для наборов данных, которые имеют одинаковую структуру, например, посты в блогах или товары. Когда вы определяете эту структуру в схеме, вы также получаете валидацию, типобезопасность и IntelliSense в вашем редакторе. - -Узнайте больше о [том, когда использовать коллекции контента](/ru/guides/content-collections/#когда-создавать-коллекцию) вместо импорта файлов. - -## Динамические выражения, похожие на JSX - -После импорта или запроса файлов Markdown вы можете писать динамические HTML-шаблоны в ваших компонентах `.astro`, включая метаданные и содержимое `body`. - -```md title="src/pages/posts/great-post.md" ---- -title: 'Лучший пост всех времён' -author: 'Бен' ---- - -Вот мой _замечательный_ пост! -``` - -```astro title="src/pages/my-posts.astro" ---- -import * as greatPost from './posts/great-post.md'; -const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true })); ---- - -

{greatPost.frontmatter.title}

-

Автор: {greatPost.frontmatter.author}

- -

Архив записей:

- -``` - -### Доступные свойства - -#### Markdown из запросов коллекций контента - -При получении данных из ваших коллекций с помощью хелперов `getCollection()` или `getEntry()`, метаданные вашего Markdown доступны в объекте `data` (например, `post.data.title`). Дополнительно, `body` содержит необработанное, несобранное содержимое `body` в виде строки. - -Функция [`render()`](/ru/reference/modules/astro-content/#render) возвращает содержимое `body` вашего Markdown, сгенерированный список заголовков, а также изменённый объект метаданных после применения любых плагинов remark или rehype. - -Узнайте больше об [использовании контента, возвращённого запросом коллекций](/ru/guides/content-collections/#использование-содержимого-в-шаблонах-astro). - -#### Импорт Markdown - -Следующие экспортированные свойства доступны в вашем компоненте `.astro` при импорте Markdown с использованием `import` или `import.meta.glob()`: - -- **`file`** — Абсолютный путь к файлу (например, `/home/user/projects/.../file.md`). -- **`url`** — URL страницы (например, `/en/guides/markdown-content`). -- **`frontmatter`** — Содержит любые данные, указанные в метаданных YAML (или TOML) файла. -- **``** — Компонент, который возвращает полное, отрендеренное содержимое файла. -- **`rawContent()`** — Функция, которая возвращает необработанный Markdown-документ в виде строки. -- **`compiledContent()`** — Асинхронная функция, которая возвращает Markdown-документ, скомпилированный в строку HTML. -- **`getHeadings()`** — Асинхронная функция, которая возвращает массив всех заголовков (`

` до `

`) в файле с типом: `{ depth: number; slug: string; text: string }[]`. `slug` каждого заголовка соответствует сгенерированному ID для данного заголовка и может использоваться для якорных ссылок. - -Пример Markdown-поста в блоге может передавать следующий объект `Astro.props`: - -```js -Astro.props = { - file: "/home/user/projects/.../file.md", - url: "/en/guides/markdown-content/", - frontmatter: { - /** Метаданные из поста блога */ - title: "Astro 0.18 Release", - date: "Tuesday, July 27 2021", - author: "Matthew Phillips", - description: "Astro 0.18 is our biggest release since Astro launch.", - }, - getHeadings: () => [ - {"depth": 1, "text": "Astro 0.18 Release", "slug": "astro-018-release"}, - {"depth": 2, "text": "Responsive partial hydration", "slug": "responsive-partial-hydration"} - /* ... */ - ], - rawContent: () => "# Astro 0.18 Release\nA little over a month ago, the first public beta [...]", - compiledContent: () => "

Astro 0.18 Release

\n

A little over a month ago, the first public beta [...]

", -} -``` - - -## Компонент `` - -Компонент `` доступен при импорте `Content` из файла Markdown. Этот компонент возвращает полное содержимое тела файла, отрендеренное в HTML. При желании вы можете переименовать `Content` в любое предпочитаемое имя компонента. - -Аналогично вы можете [отображать HTML-содержимое записи коллекции Markdown](/ru/guides/content-collections/#рендеринг-содержимого-body), используя компонент ``. - -```astro title="src/pages/content.astro" "Content" ---- -// Импорт -import {Content as PromoBanner} from '../components/promoBanner.md'; - -// Запрос коллекции -import { getEntry, render } from 'astro:content'; - -const product = await getEntry('products', 'shirt'); -const { Content } = await render(product); ---- -

Сегодняшняя акция

- - -

Акция заканчивается: {product.data.saleEndDate.toDateString()}

- -``` - -### Идентификаторы заголовков - -Использование заголовков в Markdown и MDX автоматически дает вам якорные ссылки, чтобы вы могли напрямую ссылаться на определённые разделы вашей страницы. - -```markdown title="src/pages/page-1.md" ---- -title: Моя страница с контентом ---- -## Введение - -Я могу ссылаться внутри страницы на [мое заключение](#заключение) при написании Markdown. - -## Заключение - -Я могу перейти по ссылке `https://example.com/page-1/#введение` в браузере, чтобы сразу перейти к разделу «Введение». -``` - -Astro генерирует `id` заголовков на основе `github-slugger`. Больше примеров вы можете найти в [документации github-slugger](https://github.com/Flet/github-slugger#usage). - -### Идентификаторы заголовков и плагины - -Astro добавляет атрибут `id` во все элементы заголовков (`

` до `

`) в файлах Markdown и MDX. Вы можете получить эти данные с помощью утилиты `getHeadings()`, доступной как [экспортированное свойство Markdown](#доступные-свойства) из импортированного файла, или через функцию `render()` при [использовании Markdown, возвращённого запросом коллекций контента](#markdown-из-запросов-коллекций-контента). - -Вы можете настроить эти идентификаторы заголовков, добавив плагин rehype, который внедряет атрибуты `id` (например, `rehype-slug`). Ваши пользовательские идентификаторы, вместо стандартных значений Astro, будут отражены в HTML-выводе и элементах, возвращаемых `getHeadings()`. - -По умолчанию Astro добавляет атрибуты `id` после выполнения ваших плагинов rehype. Если один из ваших пользовательских плагинов rehype нуждается в доступе к ID, добавленным Astro, вы можете импортировать и использовать плагин `rehypeHeadingIds` от Astro напрямую. Убедитесь, что `rehypeHeadingIds` добавлен перед любыми плагинами, которые зависят от него: - -```js title="astro.config.mjs" ins={2, 8} -import { defineConfig } from 'astro/config'; -import { rehypeHeadingIds } from '@astrojs/markdown-remark'; -import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source'; - -export default defineConfig({ - markdown: { - rehypePlugins: [ - rehypeHeadingIds, - otherPluginThatReliesOnHeadingIDs, - ], - }, -}); -``` - -## Плагины Markdown - -Поддержка Markdown в Astro обеспечивается [remark](https://remark.js.org/), мощным инструментом для парсинга и обработки с активной экосистемой. Другие парсеры Markdown, такие как Pandoc и markdown-it, в настоящее время не поддерживаются. - -Astro по умолчанию применяет плагины [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) и [SmartyPants](https://github.com/silvenon/remark-smartypants). Это добавляет такие удобства, как создание кликабельных ссылок из текста и форматирование для [кавычек и тире](https://daringfireball.net/projects/smartypants/). - -Вы можете настроить, как remark обрабатывает ваш Markdown, в файле `astro.config.mjs`. См. полный список [опций конфигурации Markdown](/ru/reference/configuration-reference/#markdown-options). - -### Добавление remark и rehype плагинов - -Astro поддерживает добавление сторонних плагинов [remark](https://github.com/remarkjs/remark) и [rehype](https://github.com/rehypejs/rehype) для Markdown. Эти плагины позволяют расширить возможности вашего Markdown, например, [автоматически генерировать оглавление](https://github.com/remarkjs/remark-toc), [добавлять доступные метки для эмодзи](https://github.com/florianeckerstorfer/remark-a11y-emoji) и [стилизовать ваш Markdown](/ru/guides/styling/#стилизация-markdown). - -Мы рекомендуем ознакомиться с [awesome-remark](https://github.com/remarkjs/awesome-remark) и [awesome-rehype](https://github.com/rehypejs/awesome-rehype) для поиска популярных плагинов! Ознакомьтесь с README каждого плагина для получения конкретных инструкций по установке. - -Этот пример применяет [`remark-toc`](https://github.com/remarkjs/remark-toc) и [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) к файлам Markdown: - -```js title="astro.config.mjs" -import { defineConfig } from 'astro/config'; -import remarkToc from 'remark-toc'; -import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis'; - -export default defineConfig({ - markdown: { - remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ], - rehypePlugins: [rehypeAccessibleEmojis], - }, -}); -``` - -### Настройка плагина - -Для того чтобы настроить плагин, предоставьте после него объект `options` во вложенном массиве. - -Пример ниже добавляет опцию [`heading` к плагину `remarkToc`](https://github.com/remarkjs/remark-toc#options), чтобы изменить место размещения оглавления, и опцию [`behavior` к плагину `rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings#options), чтобы добавить тег якоря после текста заголовка. - -```js title="astro.config.mjs" -import remarkToc from 'remark-toc'; -import rehypeSlug from 'rehype-slug'; -import rehypeAutolinkHeadings from 'rehype-autolink-headings'; - -export default { - markdown: { - remarkPlugins: [ [remarkToc, { heading: "contents"} ] ], - rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]], - }, -} -``` - -### Программное изменение метаданных - -Вы можете добавить метаданные во все ваши файлы Markdown и MDX с помощью плагина [remark или rehype](#плагины-markdown). - - -1. Добавьте `customProperty` к свойству `data.astro.frontmatter` из аргумента `file` вашего плагина: - - ```js title="example-remark-plugin.mjs" - export function exampleRemarkPlugin() { - // Все плагины remark и rehype возвращают отдельную функцию - return function (tree, file) { - file.data.astro.frontmatter.customProperty = 'Сгенерированное свойство'; - } - } - ``` - - :::tip - - - `data.astro.frontmatter` содержит все свойства данного документа Markdown или MDX. Это позволяет изменять существующие метаданные или вычислять новые свойства из существующих метаданных. - ::: - -2. Примените этот плагин к конфигурации интеграции `markdown` или `mdx`: - - ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin]," - import { defineConfig } from 'astro/config'; - import { exampleRemarkPlugin } from './example-remark-plugin.mjs'; - - export default defineConfig({ - markdown: { - remarkPlugins: [exampleRemarkPlugin] - }, - }); - ``` - - или - - ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin]," - import { defineConfig } from 'astro/config'; - import { exampleRemarkPlugin } from './example-remark-plugin.mjs'; - - export default defineConfig({ - integrations: [ - mdx({ - remarkPlugins: [exampleRemarkPlugin], - }), - ], - }); - ``` - - -Теперь каждый файл Markdown или MDX будет содержать `customProperty` в своих метаданных, что делает его доступным при [импорте вашего markdown](#импорт-markdown) и из [свойства `Astro.props.frontmatter` в ваших макетах](#свойство-layout). - - - -### Расширение конфигурации Markdown из MDX - -Интеграция Astro в MDX по умолчанию расширяет [существующую конфигурацию Markdown вашего проекта](/ru/reference/configuration-reference/#markdown-options). Чтобы отменить отдельные опции, вы можете указать их эквивалент в конфигурации MDX. - -Следующий пример отключает GitHub-Flavored Markdown и применяет другой набор плагинов remark для файлов MDX: - -```ts title="astro.config.mjs" -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; - -export default defineConfig({ - markdown: { - syntaxHighlight: 'prism', - remarkPlugins: [remarkPlugin1], - gfm: true, - }, - integrations: [ - mdx({ - // `syntaxHighlight` унаследован от Markdown - - // Игнорируются `remarkPlugins` из Markdown, - // применяется только `remarkPlugin2`. - remarkPlugins: [remarkPlugin2], - // `gfm` переопределено на `false` - gfm: false, - }) - ] -}); -``` - -Чтобы не расширять конфигурацию Markdown из MDX, установите [опцию `extendMarkdownConfig`](/ru/guides/integrations-guide/mdx/#extendmarkdownconfig) (включенную по умолчанию) в `false`: - -```ts title="astro.config.mjs" -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; - -export default defineConfig({ - markdown: { - remarkPlugins: [remarkPlugin], - }, - integrations: [ - mdx({ - // Конфигурация Markdown теперь игнорируется - extendMarkdownConfig: false, - // Не применяются `remarkPlugins` - }) - ] -}); -``` - -## Отдельные страницы Markdown - -:::tip -[Коллекции контента](/ru/guides/content-collections/) и [импорт Markdown в компоненты `.astro`](#динамические-выражения-похожие-на-jsx) предоставляют больше возможностей для отображения вашего Markdown и являются рекомендуемым способом обработки большей части вашего контента. Однако бывают случаи, когда вам нужно просто добавить файл в `src/pages/`, чтобы автоматически создать страницу. -::: - -Astro рассматривает [любой поддерживаемый файл внутри директории `/src/pages/`](/ru/basics/astro-pages/#поддерживаемые-типы-файлов-страниц) как страницу, включая `.md` и другие типы файлов Markdown. - -Размещение файла в этой директории или любой поддиректории автоматически создаст маршрут страницы, используя путь к файлу, и отобразит содержимое Markdown, преобразованное в HTML. Astro автоматически добавит тег `` на вашу страницу для упрощения написания не-ASCII контента. - -```markdown title="src/pages/page-1.md" ---- -title: Привет, мир ---- - -# Привет! - -Этот файл Markdown создаёт страницу по адресу `your-domain.com/page-1/` - -Она, возможно, не сильно стилизована, но Markdown поддерживает: -- **жирный текст** и _курсив_. -- списки -- [ссылки](https://astro.build) --

HTML-элементы

-- и многое другое! -``` - -### Свойство `layout` - -Чтобы компенсировать ограниченную функциональность отдельных страниц Markdown, Astro предоставляет в метаданных специальное свойство `layout`, которое указывает относительный путь к [компоненту макета Markdown](/ru/basics/layouts/#markdown-макеты) в Astro. `layout` не является специальным свойством при использовании [коллекций контента](/ru/guides/content-collections/) для запроса и отображения вашего Markdown-контента и не гарантирует поддержку за пределами его предполагаемого использования. - -Если ваш файл Markdown находится в `src/pages/`, создайте компонент макета и добавьте его в это свойство `layout`, чтобы предоставить оболочку страницы вокруг вашего Markdown-контента. - -```markdown title="src/pages/posts/post-1.md" {2} ---- -layout: ../../layouts/BlogPostLayout.astro -title: Кратко об Astro -author: Химаншу -description: Узнайте, что делает Astro таким потрясающим! ---- -Это пост, написанный на Markdown. -``` - -Этот компонент макета — это обычный компонент Astro с [определёнными свойствами, автоматически доступными](/ru/basics/layouts/#свойства-макета-markdown) через `Astro.props` для вашего шаблона Astro. Например, вы можете получить доступ к метаданным вашего файла Markdown через `Astro.props.frontmatter`: - -```astro title="src/layouts/BlogPostLayout.astro" /frontmatter(?:.\w+)?/ ---- -const {frontmatter} = Astro.props; ---- - - - - - - -

{frontmatter.title}

-

Автор поста: {frontmatter.author}

-

{frontmatter.description}

- - - -``` - -При использовании свойства фронтматера `layout` вы должны включить тег `` в ваш макет, так как Astro больше не добавляет его автоматически. Теперь вы также можете [стилизовать ваш Markdown](/ru/guides/styling/#стилизация-markdown) в вашем компоненте макета. - -Узнайте больше о [макетах для Markdown](/ru/basics/layouts/#markdown-макеты). - -## Получение удалённого Markdown - -Astro не включает встроенную поддержку удалённого Markdown за пределами [коллекций контента](/ru/guides/content-collections/). - -Чтобы загрузить удалённый Markdown напрямую и отобразить его в HTML, вам нужно будет установить и настроить собственный парсер Markdown из NPM. Это не будет наследовать никаких встроенных настроек Markdown, которые вы настроили в Astro. - -Убедитесь, что вы понимаете эти ограничения перед реализацией этого в вашем проекте, и рассмотрите возможность загрузки удалённого Markdown с помощью загрузчика коллекций контента. - -```astro title="src/pages/remote-example.astro" ---- -// Пример: Получение Markdown с удалённого API -// и рендеринг его в HTML во время выполнения. -// Использование "marked" (https://github.com/markedjs/marked) -import { marked } from 'marked'; -const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md'); -const markdown = await response.text(); -const content = marked.parse(markdown); ---- -
-``` diff --git a/src/content/docs/ru/guides/middleware.mdx b/src/content/docs/ru/guides/middleware.mdx deleted file mode 100644 index ae4f3a648e5bf..0000000000000 --- a/src/content/docs/ru/guides/middleware.mdx +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Мидлвары -description: Узнайте, как использовать мидлвары в Astro. -i18nReady: true ---- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; -import { Steps } from '@astrojs/starlight/components'; -import Since from '~/components/Since.astro'; - -**Мидлвар** позволяет перехватывать запросы и ответы, а также динамически внедрять поведения каждый раз, когда страница или конечная точка собирается быть отрисованной. Эта отрисовка происходит во время сборки для всех предварительно отрисованных страниц, но происходит, когда запрашивается маршрут для страниц, отрисовываемых по запросу, что делает доступными [дополнительные функции SSR, такие как куки и заголовки](/ru/guides/on-demand-rendering/#возможности-рендеринга-по-запросу). - -Мидлвар также позволяет устанавливать и делиться информацией, специфичной для запроса, между конечными точками и страницами, изменяя объект `locals`, который доступен во всех компонентах Astro и API эндпойнтов. Этот объект доступен даже когда этот мидлвар выполняется во время сборки. - -## Базовое использование - - -1. Создайте `src/middleware.js|ts` (или `src/middleware/index.js|ts`). - -2. Внутри этого файла экспортируйте функцию [`onRequest()`](/ru/reference/modules/astro-middleware/#onrequest), которой можно передать объект [`context`](#объект-context) и функцию `next()`. Это не должен быть экспорт по умолчанию. - - ```js title="src/middleware.js" - export function onRequest ({ locals, request }, next) { - // перехват данных из запроса - // меняем свойства в `locals`, если нужно - locals.title = "Новый заголовок"; - - // возвращаем ответ или результат вызова `next()` - return next(); - }; - ``` - -3. В любом файле `.astro` получите данные ответа, используя `Astro.locals`. - - ```astro title="src/components/Component.astro" - --- - const data = Astro.locals; - --- -

{data.title}

-

Это {data.property} из мидлвара.

- ``` - - -### Объект `context` - -Объект [`context`](/ru/reference/api-reference/) содержит информацию, которая будет доступна другому мидлвару, маршрутам API и маршрутам `.astro` в процессе рендеринга. - -Это необязательный аргумент, передаваемый в `onRequest()`, который может содержать объект `locals`, а также любые дополнительные свойства, которые будут переданы во время рендеринга. Например, объект `context` может содержать куки, используемые при аутентификации. - -### Хранение данных в `context.locals` - -`context.locals` — это объект, которым можно манипулировать внутри мидлвара. - -Этот объект `locals` передается в процессе обработки запроса и доступен в качестве свойства для [`APIContext`](/ru/reference/api-reference/#locals) и [`AstroGlobal`](/ru/reference/api-reference/#locals). Это позволяет обмениваться данными между мидлваром, маршрутами API и страницами `.astro`. Это полезно для хранения специфических данных запроса, таких как данные пользователя, на всех этапах рендеринга. - -:::tip[Свойства интеграции] -[Интеграции](/ru/guides/integrations-guide/) могут устанавливать свойства и предоставлять функциональность через объект `locals`. Если вы используете интеграцию, ознакомьтесь с её документацией, чтобы убедиться, что вы не переопределяете её свойства и не выполняете лишнюю работу. -::: - -Внутри `locals` можно хранить любые типы данных: строки, числа и даже сложные типы данных, такие как функции и карты. - -```js title="src/middleware.js" -export function onRequest ({ locals, request }, next) { - // перехват данных из запроса - // меняем свойства в `locals`, если нужно - locals.user.name = "Джон Уик"; - locals.welcomeTitle = () => { - return "С возвращением, " + locals.user.name; - }; - - // возвращаем ответ или результат вызова `next()` - return next(); -}; -``` - -Затем вы можете использовать эту информацию внутри любого файла `.astro` с помощью `Astro.locals`. - -```astro title="src/pages/orders.astro" ---- -const title = Astro.locals.welcomeTitle(); -const orders = Array.from(Astro.locals.orders.entries()); -const data = Astro.locals; ---- -

{title}

-

Это {data.property} из мидлвара.

-
    - {orders.map(order => { - return
  • {/* делаем что-нибудь с каждым заказом */}
    • ; - })} -
-``` - -`locals` — это объект, который живет и умирает в рамках одного маршрута Astro; когда страница вашего маршрута будет отрисована, `locals` перестанет существовать и будет создан новый. Информация, которая должна сохраняться в течение нескольких запросов страницы, должна храниться в другом месте. - -:::note -Значение `locals` не может быть переопределено во время выполнения. Это может привести к удалению всей информации, хранящейся пользователем. Astro выполняет проверку и выдает ошибку, если `locals` переопределен. -::: - -## Пример: редактирование конфиденциальной информации - -В примере ниже используется мидлвар для замены слова «PRIVATE INFO» на слово «REDACTED», что позволяет отображать изменённый HTML на вашей странице: - -```js title="src/middleware.js" -export const onRequest = async (context, next) => { - const response = await next(); - const html = await response.text(); - const redactedHtml = html.replaceAll("PRIVATE INFO", "REDACTED"); - - return new Response(redactedHtml, { - status: 200, - headers: response.headers - }); -}; -``` - -## Типы мидлваров - -Можно импортировать и использовать служебную функцию `defineMiddleware()`, чтобы пользоваться преимуществами типобезопасности: - -```ts -// src/middleware.ts -import { defineMiddleware } from "astro:middleware"; - -// `context` и `next` автоматически типизируются -export const onRequest = defineMiddleware((context, next) => { - -}); -``` - -В противном случае, если вы используете JsDoc для обеспечения типобезопасности, вы можете использовать `MiddlewareHandler`: - -```js -// src/middleware.js -/** - * @type {import("astro").MiddlewareHandler} - */ -// `context` и `next` автоматически типизируются -export const onRequest = (context, next) => { - -}; -``` - -Чтобы типизировать информацию внутри `Astro.locals`, что дает вам автозаполнение внутри файлов `.astro` и кода мидлвара, объявите глобальное пространство имён в файле `env.d.ts`: - -```ts title="src/env.d.ts" -declare namespace App { - interface Locals { - user: { - name: string - }, - welcomeTitle: () => string, - orders: Map - } -} -``` - -Затем, внутри файла мидлвара, вы можете воспользоваться преимуществами автозавершения и типобезопасности. - -## Цепочка мидлваров - -Несколько мидлваров могут быть объединены в определённом порядке с помощью [`sequence()`](/ru/reference/modules/astro-middleware/#sequence): - -```js title="src/middleware.js" -import { sequence } from "astro:middleware"; - -async function validation(_, next) { - console.log("validation request"); - const response = await next(); - console.log("validation response"); - return response; -} - -async function auth(_, next) { - console.log("auth request"); - const response = await next(); - console.log("auth response"); - return response; -} - -async function greeting(_, next) { - console.log("greeting request"); - const response = await next(); - console.log("greeting response"); - return response; -} - -export const onRequest = sequence(validation, auth, greeting); -``` - -Это приведет к следующему порядку в консоли: - -```sh -validation request -auth request -greeting request -greeting response -auth response -validation response -``` - -## Перезапись - -

- -`APIContext` предоставляет метод `rewrite()`, который работает так же, как и [Astro.rewrite](/ru/guides/routing/#переписывания). - -Используйте `context.rewrite()` внутри мидлвара, чтобы отобразить содержимое другой страницы без [перенаправления](/ru/guides/routing/#динамические-переадресации) вашего посетителя на новую страницу. Это вызовет новую фазу отрисовки, что приведет к повторному выполнению любого мидлвара. - -```js title="src/middleware.js" -import { isLoggedIn } from "~/auth.js" -export function onRequest (context, next) { - if (!isLoggedIn(context)) { - // Если пользователь не вошел в систему, обновляем запрос, чтобы отобразить маршрут `/login` и - // добавляем заголовок, чтобы указать, куда пользователь должен быть отправлен после успешного входа. - // Повторно выполняем мидлвар. - return context.rewrite(new Request("/login", { - headers: { - "x-redirect-to": context.url.pathname - } - })); - } - - return next(); -}; -``` - -Вы также можете передать функции `next()` необязательный параметр URL-пути, чтобы переписать текущий `Request` без повторного запуска новой фазы отрисовки. Местоположение пути переписывания может быть указано в виде строки, URL или `Request`: - -```js title="src/middleware.js" -import { isLoggedIn } from "~/auth.js" -export function onRequest (context, next) { - if (!isLoggedIn(context)) { - // Если пользователь не вошел в систему, обновляем запрос, чтобы отобразить маршрут `/login` и - // добавляем заголовок, чтобы указать, куда пользователь должен быть отправлен после успешного входа. - // Возвращаем новый `context` для любых последующих мидлваров. - return next(new Request("/login", { - headers: { - "x-redirect-to": context.url.pathname - } - })); - } - - return next(); -}; -``` - -Функция `next()` принимает тот же набор параметров, что и [функция `Astro.rewrite()`](/ru/reference/api-reference/#rewrite). Местоположение пути переписывания может быть указано в виде строки, URL или `Request`. - -Когда у вас есть несколько функций мидлвара, связанных через [sequence()](#цепочка-мидлваров), передача пути в `next()` перепишет `Request` на месте, и мидлвар не будет выполнен снова. Следующая функция мидлвара в цепочке получит новый `Request` с обновлённым `context`: - -Вызов `next()` с этой сигнатурой создаст новый объект `Request`, используя старый `ctx.request`. Это означает, что попытка получить доступ к `Request.body`, как до, так и после этого переписывания, вызовет ошибку во время выполнения. Эта ошибка часто возникает при использовании [Astro Actions, которые используют HTML-формы](/ru/guides/actions/#call-actions-from-an-html-form-action). В этих случаях мы рекомендуем обрабатывать переписывания из ваших шаблонов Astro, используя `Astro.rewrite()`, вместо использования мидлвара. - -```js title="src/middleware.js" -// Текущий URL-адрес https://example.com/blog - -// Первая функция мидлвара -async function first(_, next) { - console.log(context.url.pathname) // отобразит "/blog" - // Перезаписываем новый маршрут, домашнюю страницу - // Возвращаем обновлённый `context`, который передается функции next - return next("/") -} - -// Текущий URL-адрес всё ещё https://example.com/blog - -// Вторая функция мидлвара -async function second(context, next) { - // Получает обновлённый `context` - console.log(context.url.pathname) // отобразит "/" - return next() -} - -export const onRequest = sequence(first, second); -``` - -## Страницы ошибок - -Мидлвар будет пытаться запустить все страницы по требованию, даже если подходящий маршрут не может быть найден. Это включает в себя стандартную (пустую) страницу 404 в Astro и любые пользовательские страницы 404. Однако решение о том, будет ли выполняться этот код, зависит от [адаптера](/ru/guides/on-demand-rendering/). Некоторые адаптеры могут выдавать вместо этого страницу ошибки, специфичную для конкретной платформы. - -Мидлвар также попытается запуститься перед выдачей страницы ошибки 500, включая пользовательскую страницу 500, если только ошибка сервера не произошла во время выполнения самого мидлвара. Если ваш мидлвар не будет успешно запущен, то у вас не будет доступа к `Astro.locals` для отображения вашей 500-страницы. diff --git a/src/content/docs/ru/guides/migrate-to-astro/index.mdx b/src/content/docs/ru/guides/migrate-to-astro/index.mdx index aeef7d6564f88..fabeda4ce4b96 100644 --- a/src/content/docs/ru/guides/migrate-to-astro/index.mdx +++ b/src/content/docs/ru/guides/migrate-to-astro/index.mdx @@ -27,7 +27,7 @@ Astro предоставляет множество преимуществ: пр - [CSS стили или библиотеки](/ru/guides/styling/), включая Tailwind. -- [Markdown/MDX файлы](/ru/guides/markdown-content/), настроенные с использованием ваших существующих [плагинов remark и rehype](/ru/guides/markdown-content/#плагины-markdown). +- [Markdown/MDX файлы](/ru/guides/markdown-content/), настроенные с использованием ваших существующих [плагинов remark и rehype](/ru/guides/markdown-content/#markdown-plugins). - [Контент из CMS](/ru/guides/cms/) через интеграцию или API. diff --git a/src/content/docs/ru/guides/on-demand-rendering.mdx b/src/content/docs/ru/guides/on-demand-rendering.mdx index 0d7197af7b451..565e921a15336 100644 --- a/src/content/docs/ru/guides/on-demand-rendering.mdx +++ b/src/content/docs/ru/guides/on-demand-rendering.mdx @@ -29,7 +29,7 @@ Astro поддерживает официальные адаптеры для [N ### Добавление адаптера -Вы можете подключить любой из [официальных адаптеров, поддерживаемых Astro](/ru/guides/integrations-guide/#официальные-интеграции) с помощью команды `astro add`. Она автоматически установит адаптер и внесет все необходимые изменения в файл `astro.config.mjs`. +Вы можете подключить любой из [официальных адаптеров, поддерживаемых Astro](/ru/guides/integrations-guide/#official-integrations) с помощью команды `astro add`. Она автоматически установит адаптер и внесет все необходимые изменения в файл `astro.config.mjs`. Например, чтобы установить адаптер Netlify, выполните: @@ -51,7 +51,7 @@ Astro поддерживает официальные адаптеры для [N -Вы также можете [добавить адаптер вручную, установив NPM-пакет](/ru/guides/integrations-guide/#установка-пакета-npm) (например, `@astrojs/netlify`) и самостоятельно обновив файл `astro.config.mjs`. +Вы также можете [добавить адаптер вручную, установив NPM-пакет](/ru/guides/integrations-guide/#installing-an-npm-package) (например, `@astrojs/netlify`) и самостоятельно обновив файл `astro.config.mjs`. Имейте в виду, что у разных адаптеров разные настройки конфигурации. Изучите документацию выбранного адаптера и примените необходимые параметры конфигурации в файле `astro.config.mjs`. diff --git a/src/content/docs/ru/guides/routing.mdx b/src/content/docs/ru/guides/routing.mdx deleted file mode 100644 index f691deb3087dc..0000000000000 --- a/src/content/docs/ru/guides/routing.mdx +++ /dev/null @@ -1,574 +0,0 @@ ---- -title: Маршрутизация -description: Введение в маршрутизацию с Astro. -i18nReady: true ---- -import { FileTree } from '@astrojs/starlight/components'; -import RecipeLinks from "~/components/RecipeLinks.astro" -import Since from '~/components/Since.astro' -import ReadMore from '~/components/ReadMore.astro' - -Astro использует **маршрутизацию на основе файлов** для генерации URL-адресов ваших сборок на основе схемы расположения файлов в каталоге `src/pages/` вашего проекта. - -## Навигация между страницами - -Astro использует стандартные HTML-элементы [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) для навигации между маршрутами. Нет специфического для фреймворка компонента ``. - -```astro title="src/pages/index.astro" -

Читайте далее об Astro!

- - -

Узнайте больше в нашем справочнике!

-``` - -## Статические маршруты - -[Компоненты страниц](/ru/basics/astro-pages/) `.astro`, а также Markdown и MDX файлы (`.md`, `.mdx`) в директории `src/pages/` **автоматически становятся страницами вашего сайта**. Маршрут каждой страницы соответствует ее пути и имени файла в каталоге `src/pages/`. - -```diff -# Пример: Статические маршруты -src/pages/index.astro -> mysite.com/ -src/pages/about.astro -> mysite.com/about -src/pages/about/index.astro -> mysite.com/about -src/pages/about/me.astro -> mysite.com/about/me -src/pages/posts/1.md -> mysite.com/posts/1 -``` - -:::tip -В проекте Astro нет отдельного "конфигурационного файла маршрутизации"! Когда вы добавляете файл в директорию `src/pages/`, для вас автоматически создается новый маршрут. В статических сборках вы можете настроить формат вывода файлов с помощью опции [`build.format`](/ru/reference/configuration-reference/#buildformat). -::: - -## Динамические маршруты - -В имени файла страницы Astro могут быть указаны параметры динамического маршрута для создания нескольких подходящих страниц. Например, `src/pages/authors/[author].astro` генерирует биографическую страницу для каждого автора в вашем блоге. `author` становится _параметром_, к которому вы можете обращаться внутри страницы. - -В стандартном режиме статического вывода Astro эти страницы генерируются во время сборки, поэтому вы должны заранее определить список `авторов`, которые получат соответствующий файл. В режиме SSR страница будет генерироваться по запросу для любого маршрута, который соответствует. - -### Статический (SSG) режим - -Поскольку все маршруты должны быть определены во время сборки, динамический маршрут должен экспортировать функцию `getStaticPaths()`, которая возвращает массив объектов со свойством `params`. Каждый из этих объектов будет генерировать соответствующий маршрут. - -`[dog].astro` определяет динамический параметр `dog` в своем имени, поэтому объекты, возвращаемые `getStaticPaths()`, должны включать `dog` в свои `params`. Затем страница может получить доступ к этому параметру с помощью `Astro.params`. - -```astro title="src/pages/dogs/[dog].astro" ---- -export function getStaticPaths() { - return [ - { params: { dog: "clifford" }}, - { params: { dog: "rover" }}, - { params: { dog: "spot" }}, - ]; -} - -const { dog } = Astro.params; ---- -
Good dog, {dog}!
-``` - -В результате будут сгенерированы три страницы: `/dogs/clifford`, `/dogs/rover` и `/dogs/spot`, каждая из которых отображает соответствующее имя собаки. - -Имя файла может включать несколько параметров, которые должны быть включены в объекты `params` в `getStaticPaths()`: - -```astro title="src/pages/[lang]-[version]/info.astro" ---- -export function getStaticPaths () { - return [ - { params: { lang: "en", version: "v1" }}, - { params: { lang: "fr", version: "v2" }}, - ]; -} - -const { lang, version } = Astro.params; ---- -``` - -В результате будут сгенерированы `/en-v1/info` и `/fr-v2/info`. - -Параметры могут быть включены в отдельные части пути. Например, файл `src/pages/[lang]/[version]/info.astro` с тем же `getStaticPaths()`, что и выше, сгенерирует маршруты `/en/v1/info` и `/fr/v2/info`. - -#### Декодирование `params` - -Параметры, переданные функции `getStaticPaths()`, не декодируются. Используйте функцию [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI), когда вам нужно декодировать значения параметров. - -```astro title="src/pages/[slug].astro" ---- -export function getStaticPaths() { - return [ - { params: { slug: decodeURI("%5Bpage%5D") }}, // декодирует в "[page]" - ] -} ---- -``` - -Узнайте больше о [`getStaticPaths()`](/ru/reference/routing-reference/#getstaticpaths). - - - -#### Rest параметры - -Если вам нужна большая гибкость в маршрутизации URL, вы можете использовать [rest параметры](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) (`[...path]`) в имени файла `.astro` для сопоставления путей файлов любой глубины: - -```astro title="src/pages/sequences/[...path].astro" ---- -export function getStaticPaths() { - return [ - { params: { path: "one/two/three" }}, - { params: { path: "four" }}, - { params: { path: undefined }} - ] -} - -const { path } = Astro.params; ---- -... -``` - -Это сгенерирует `/sequences/one/two/three`, `/sequences/four` и `/sequences`. (Установка параметра rest в значение `undefined` позволяет ему соответствовать странице верхнего уровня). - -Параметры rest можно использовать с **другими именованными параметрами**. Например, просмотрщик файлов GitHub может быть представлен следующим динамическим маршрутом: - -``` -/[org]/[repo]/tree/[branch]/[...file] -``` -В этом примере запрос на `/withastro/astro/tree/main/docs/public/favicon.svg` будет разбит на следующие именованные параметры: - -```js -{ - org: "withastro", - repo: "astro", - branch: "main", - file: "docs/public/favicon.svg" -} -``` - -#### Пример: Динамические страницы на нескольких уровнях - -В следующем примере параметр rest (`[...slug]`) и функция [`props`](/ru/reference/routing-reference/#data-passing-with-props) в `getStaticPaths()` генерируют страницы для слагов разной глубины. - -```astro title="src/pages/[...slug].astro" ---- -export function getStaticPaths() { - const pages = [ - { - slug: undefined, - title: "Магазин Astro", - text: "Добро пожаловать в магазин Astro!", - }, - { - slug: "products", - title: "Продукты Astro", - text: "У нас есть множество продуктов для вас", - }, - { - slug: "products/astro-handbook", - title: "Исчерпывающее руководство по Astro", - text: "Если вы хотите изучить Astro, обязательно прочитайте эту книгу.", - }, - ]; - - return pages.map(({ slug, title, text }) => { - return { - params: { slug }, - props: { title, text }, - }; - }); -} - -const { title, text } = Astro.props; ---- - - - {title} - - -

{title}

-

{text}

- - -``` - -### Режим серверного рендеринга (SSR) - -В режиме [SSR](/ru/guides/on-demand-rendering/) динамические маршруты определяются точно так же: включите в имена файлов скобки `[param]` или `[...path]` для соответствия произвольным строкам или путям. Но поскольку маршруты больше не строятся заранее, страница будет обслуживаться по любому подходящему маршруту. Поскольку это не "статические" маршруты, `getStaticPaths` не следует использовать. - -Для маршрутов, отображаемых по запросу, в имени файла может использоваться только один параметр rest с использованием spread-нотации (например, `src/pages/[locale]/[...slug].astro` или `src/pages/[...locale]/[slug].astro`, но не `src/pages/[...locale]/[...slug].astro`). - -```astro title="src/pages/resources/[resource]/[id].astro" ---- -const { resource, id } = Astro.params; ---- -

{resource}: {id}

-``` - -Эта страница будет предоставлена для любого значения `resource` и `id`: `resources/users/1`, `resources/colors/blue` и т. д. - -#### Модификация примера `[...slug]` для SSR - -Поскольку страницы SSR не могут использовать `getStaticPaths()`, они не могут получать props. [Предыдущий пример](#пример-динамические-страницы-на-нескольких-уровнях) может быть адаптирован для режима SSR путем поиска значения параметра `slug` в объекте. Если маршрут находится в корне ("/"), параметр slug будет иметь значение `undefined`. Если значение не существует в объекте, мы перенаправляем на страницу 404. - -```astro title="src/pages/[...slug].astro" ---- -const pages = [ - { - slug: undefined, - title: "Магазин Astro", - text: "Добро пожаловать в магазин Astro!", - }, - { - slug: "products", - title: "Продукты Astro", - text: "У нас есть множество продуктов для вас", - }, - { - slug: "products/astro-handbook", - title: "Исчерпывающее руководство по Astro", - text: "Если вы хотите изучить Astro, обязательно прочитайте эту книгу.", - } -]; - -const { slug } = Astro.params; -const page = pages.find((page) => page.slug === slug); -if (!page) return Astro.redirect("/404"); -const { title, text } = page; ---- - - - {title} - - -

{title}

-

{text}

- - -``` - -## Переадресация - -Иногда вам нужно перенаправить читателей на новую страницу, либо постоянно, потому что структура сайта изменилась, либо в ответ на действие, такое как вход в авторизованный маршрут. - -Вы можете определить правила для [перенаправления пользователей на постоянно перемещаемые страницы](#настроенные-переадресации) в конфигурации Astro. Или [перенаправлять пользователей динамически](#динамические-переадресации) по мере использования ими вашего сайта. - -### Настроенные переадресации - -

- -Вы можете указать отображение постоянных переадресаций в конфигурации Astro с помощью значения [`redirects`](/ru/reference/configuration-reference/#redirects). - -Для внутренних перенаправлений это сопоставление старого пути маршрута с новым. Начиная с Astro v5.2.0, также можно перенаправлять на внешние URL-адреса, начинающиеся с `http` или `https`, которые [могут быть обработаны](https://developer.mozilla.org/en-US/docs/Web/API/URL/canParse_static). - -```js title="astro.config.mjs" {4-7} -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - redirects: { - "/old-page": "/new-page", - "/blog": "https://example.com/blog" - } -}); -``` - -Эти перенаправления следуют [тем же правилам приоритета, что и маршруты на основе файлов](#порядок-приоритетов-маршрутов) и всегда будут иметь более низкий приоритет, чем существующий файл страницы с тем же именем в вашем проекте. Например, `/old-page` не будет перенаправлено на `/new-page`, если в вашем проекте содержится файл `src/pages/old-page.astro`. - -Динамические маршруты разрешены, при условии, что как новые, так и старые маршруты содержат одни и те же параметры, например: - -```js -{ - "/blog/[...slug]": "/articles/[...slug]" -} -``` - -Используя SSR или статический адаптер, вы также можете предоставить объект в качестве значения, что позволит вам указать код ответа `status` в дополнение к новому адресу `destination`: - -```js title="astro.config.mjs" {5-8} -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - redirects: { - "/old-page": { - status: 302, - destination: "/new-page" - }, - "/news": { - status: 302, - destination: "https://example.com/news" - } - } -}); -``` - -При запуске `astro build`, Astro по умолчанию выводит HTML-файлы с тегом [meta refresh](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#examples). Поддерживаемые адаптеры вместо этого будут выводить конфигурационный файл хоста с переадресацией. - -По умолчанию код состояния будет `301`. При сборке в HTML-файлы код состояния не используется сервером. - -### Динамические переадресации - -В глобальном объекте `Astro` метод `Astro.redirect` позволяет динамически перенаправлять на другую страницу. Вы можете сделать это после проверки того, вошел ли пользователь в систему, получив его сессию из куки. - -```astro title="src/pages/account.astro" {8} ---- -import { isLoggedIn } from '../utils'; - -const cookie = Astro.request.headers.get('cookie'); - -// Если пользователь не вошел в систему, перенаправляем его на страницу входа -if (!isLoggedIn(cookie)) { - return Astro.redirect("/login"); -} ---- -``` - -## Переписывания - -

- -Переписывание позволяет вам обслуживать другой маршрут без перенаправления браузера на другую страницу. Браузер будет показывать оригинальный адрес в строке URL, но вместо этого отобразит содержимое URL, предоставленного функции [`Astro.rewrite()`](/ru/reference/api-reference/#rewrite). - -:::tip -Для контента, который был перемещен навсегда, или для перенаправления пользователя на другую страницу с новым URL (например, на панель управления пользователя после входа в систему), используйте [перенаправление](#переадресация). -::: - -Переписывания могут быть полезны для отображения одного и того же контента по нескольким путям (например, `/products/shoes/men/` и `/products/men/shoes/`), не требуя поддерживать два разных исходных файла. - -Переписывания также полезны для SEO и пользовательского опыта. Они позволяют отображать контент, который в противном случае потребовал бы перенаправления вашего посетителя на другую страницу или вернул бы статус 404. Одним из распространённых способов использования переписываний является отображение одного и того же локализованного контента для различных вариантов языка. - -Следующий пример использует переписывание для отображения версии страницы `/es/`, когда посещается URL-путь `/es-CU/` (кубинский испанский). Когда посетитель переходит по URL-адресу `/es-cu/articles/introduction`, Astro отобразит содержимое, сгенерированное файлом `src/pages/es/articles/introduction.astro`. - -```astro title="src/pages/es-cu/articles/introduction.astro" ---- -return Astro.rewrite("/es/articles/introduction"); ---- -``` - -Используйте `context.rewrite()` в ваших файлах эндпойнтов, чтобы перенаправить на другую страницу: - -```js title="src/pages/api.js" -export function GET(context) { - if (!context.locals.allowed) { - return context.rewrite("/"); - } -} -``` - -Если URL, переданный в `Astro.rewrite()`, вызывает ошибку во время выполнения, Astro покажет ошибку в виде наложения в режиме разработки и вернет код состояния 500 в продакшен-среде. Если URL не существует в вашем проекте, будет возвращен код состояния 404. - -Вы можете намеренно создать переписывание для отображения вашей страницы `/404`, например, чтобы указать, что продукт в вашем интернет-магазине больше недоступен: - -```astro title="src/pages/[item].astro" ---- -const { item } = Astro.params; - -if (!itemExists(item)) { - return Astro.rewrite("/404"); -} ---- -``` - -Вы также можете условно переписывать на основе статуса HTTP-ответа, например, чтобы отобразить определённую страницу на вашем сайте при посещении URL, который не существует: - -```js title="src/middleware.mjs" -export const onRequest = async (context, next) => { - const response = await next(); - if (response.status === 404) { - return context.rewrite("/"); - } - return response; -} -``` - -Перед отображением содержимого из указанного пути переписывания функция `Astro.rewrite()` запустит новую полную фазу отрисовки. Это повторно выполнит любой мидлвар для нового маршрута/запроса. - -Смотрите [справочную информацию по API `Astro.rewrite()`](/ru/reference/api-reference/#rewrite) для получения дополнительной информации. - -## Порядок приоритетов маршрутов - -Возможно, что несколько определённых маршрутов будут пытаться построить один и тот же путь URL. Например, все эти маршруты могут построить `/posts/create`: - - -- src/pages/ - - [...slug].astro - - posts/ - - create.astro - - [page].astro - - [pid].ts - - [...slug].astro - - -Astro необходимо знать, какой маршрут должен быть использован для создания страницы. Для этого он сортирует их по порядку в соответствии со следующими правилами: - -- [Зарезервированные маршруты](#зарезервированные-маршруты) Astro -- Маршруты с большим количеством сегментов пути будут иметь приоритет перед менее специфичными маршрутами. В приведенном выше примере все маршруты в разделе `/posts/` имеют приоритет над корневым `/[...slug].astro`. -- Статические маршруты без параметров пути будут иметь приоритет над динамическими маршрутами. Например, `/posts/create.astro` имеет приоритет над всеми остальными маршрутами в примере. -- Динамические маршруты с именованными параметрами имеют приоритет над остальными параметрами. Например, `/posts/[page].astro` имеет приоритет над `/posts/[...slug].astro`. -- Предрендеренные динамические маршруты имеют приоритет над серверными динамическими маршрутами. -- Эндпоинты имеют приоритет над страницами. -- Маршруты на основе файлов имеют приоритет над перенаправлениями. -- Если ни одно из вышеперечисленных правил не определяет порядок, маршруты сортируются в алфавитном порядке на основе локали по умолчанию вашей установки Node. - -Учитывая приведённый выше пример, вот несколько примеров того, как правила будут сопоставлять запрашиваемый URL с маршрутом, используемым для построения HTML: - -- `pages/posts/create.astro` - Будет построено только `/posts/create`. -- `pages/posts/[pid].ts` - Будет построено `/posts/abc`, `/posts/xyz` и т. д. Но не `/posts/create`. -- `pages/posts/[page].astro` - Построит `/posts/1`, `/posts/2` и т. д. Но не `/posts/create`, `/posts/abc` и `/posts/xyz`. -- `pages/posts/[...slug].astro` - Будет создавать `/posts/1/2`, `/posts/a/b/c` и т. д. Но не `/posts/create`, `/posts/1`, `/posts/abc` и т. д. -- `pages/[...slug].astro` - Будет создавать `/abc`, `/xyz`, `/abc/xyz` и т. д. Но не `/posts/create`, `/posts/1`, `/posts/abc`, и т. д. - -### Зарезервированные маршруты - -Внутренние маршруты имеют приоритет над любыми маршрутами, определёнными пользователем или интеграцией, так как они необходимы для работы функций Astro. Вот зарезервированные маршруты Astro: - -- `_astro/`: Обслуживает все статические ресурсы клиенту, включая CSS-документы, упакованные клиентские скрипты, оптимизированные изображения и любые ресурсы Vite. -- `_server_islands/`: Обслуживает динамические компоненты, отложенные в [серверный остров](/ru/guides/server-islands/). -- `_actions/`: Обслуживает любые определённые [действия](/ru/guides/actions/). - -## Пагинация - -Astro поддерживает встроенную пагинацию для больших коллекций данных, которые необходимо разбить на несколько страниц. Astro генерирует общие свойства пагинации, включая URL предыдущей/следующей страницы, общее количество страниц и т. д. - -Имена пагинационных маршрутов должны использовать тот же синтаксис `[скобка]`, что и стандартные динамические маршруты. Например, имя файла `/astronauts/[page].astro` будет генерировать маршруты для `/astronauts/1`, `/astronauts/2` и т. д., где `[page]` - это номер генерируемой страницы. - -Вы можете использовать функцию `paginate()` для генерации этих страниц для массива значений следующим образом: - -```astro /{ (paginate) }/ /paginate\\(.*\\);/ /(?<=const.*)(page)/ /page\\.[a-zA-Z]+/ ---- -// src/pages/astronauts/[page].astro -export function getStaticPaths({ paginate }) { - const astronautPages = [ - { astronaut: "Нил Армстронг" }, - { astronaut: "Базз Олдрин" }, - { astronaut: "Салли Райд" }, - { astronaut: "Джон Гленн" }, - ]; - - // Генерируем страницы из нашего массива астронавтов, по 2 на страницу - return paginate(astronautPages, { pageSize: 2 }); -} -// Все пагинированные данные передаются по пропсу «page» -const { page } = Astro.props; ---- - -

Страница {page.currentPage}

-
    - - {page.data.map(({ astronaut }) =>
  • {astronaut}
    • )} -
-``` - -Это генерирует следующие страницы, по 2 элемента на странице: -- `/astronauts/1` - Страница 1: Отображает "Neil Armstrong" и "Buzz Aldrin". -- `/astronauts/2` - Страница 2: отображает "Sally Ride" и "John Glenn". - - -### Свойство `page` - -Когда вы используете функцию `paginate()`, каждой странице будут переданы данные через пропс `page`. Пропс `page` имеет множество полезных свойств, но вот основные из них: - -```ts -interface Page { - /** массив, содержащий часть данных страницы, которую вы передали функции paginate() */ - data: T[]; - /** метаданные */ - /** счетчик первого элемента на странице, начиная с 0 */ - start: number; - /** счетчик последнего элемента на странице, начиная с 0 */ - end: number; - /** общее количество результатов */ - total: number; - /** номер текущей страницы, начиная с 1 */ - currentPage: number; - /** количество элементов на странице (по умолчанию: 25) */ - size: number; - /** номер последней страницы */ - lastPage: number; - url: { - /** url текущей страницы */ - current: string; - /** url предыдущей страницы (если она есть) */ - prev: string | undefined; - /** url следующей страницы (если она есть) */ - next: string | undefined; - /** url первой страницы (если текущая страница не является первой) */ - first: string | undefined; - /** url последней страницы (если текущая страница не является последней) */ - last: string | undefined; - }; -} -``` - -Следующий пример отображает текущую информацию для страницы вместе со ссылками для навигации между страницами: - -```astro /(?<=const.*)(page)/ /page\\.[a-zA-Z]+(?:\\.(?:prev|next|first|last))?/ ---- -// src/pages/astronauts/[page].astro -// Выводим на страницу тот же список объектов { astronaut }, что и в предыдущем примере -export function getStaticPaths({ paginate }) { /* ... */ } -const { page } = Astro.props; ---- -

Страница {page.currentPage}

-
    - {page.data.map(({ astronaut }) =>
  • {astronaut}
    • )} -
-{page.url.first ? Первая : null} -{page.url.prev ? Предыдущая : null} -{page.url.next ? Следующая : null} -{page.url.last ? Последняя : null} -``` - -Узнайте больше о [свойстве `page` для пагинации](/ru/reference/routing-reference/#the-pagination-page-prop). - -### Вложенная пагинация - -Более продвинутым вариантом использования пагинации является **вложенная пагинация.** Это когда пагинация сочетается с другими динамическими параметрами маршрута. Вы можете использовать вложенную пагинацию для группировки коллекции пагинаций по какому-либо свойству или тегу. - -Например, если вы хотите сгруппировать посты в Markdown по какому-то тегу, вы можете использовать вложенную пагинацию, создав страницу `/src/pages/[tag]/[page].astro`, которая будет соответствовать следующим URLS: - -- `/red/1` (tag=red) -- `/red/2` (tag=red) -- `/blue/1` (tag=blue) -- `/green/1` (tag=green) - -Вложенная пагинация работает путем возврата массива результатов `paginate()` из `getStaticPaths()`, по одному для каждой группировки. - -В следующем примере мы реализуем вложенную пагинацию для построения URL-адресов, перечисленных выше: - -```astro /(?:[(]|=== )(tag)/ "params: { tag }," /const [{ ]*(page|params)/ ---- -// src/pages/[tag]/[page].astro -export function getStaticPaths({ paginate }) { - const allTags = ["red", "blue", "green"]; - const allPosts = Object.values(import.meta.glob("../pages/post/*.md", { eager: true })); - // Для каждого тега возвращаем результат paginate(). - // Убедитесь, что вы передали `{params: {tag}}` в `paginate()`. - // чтобы Astro знал, для какой группы тегов получен результат. - return allTags.flatMap((tag) => { - const filteredPosts = allPosts.filter((post) => post.frontmatter.tag === tag); - return paginate(filteredPosts, { - params: { tag }, - pageSize: 10 - }); - }); -} - -const { page } = Astro.props; -const params = Astro.params; -``` - -## Исключение страниц - -Вы можете исключить страницы или каталоги из сборки, добавив к их именам символ подчеркивания (`_`). Файлы с префиксом `_` не будут распознаны маршрутизатором и не будут помещены в каталог `dist/`. - -Это можно использовать для временного отключения страниц, а также для размещения тестов, утилит и компонентов в той же папке, что и связанные с ними страницы. - -В этом примере только `src/pages/index.astro` и `src/pages/posts/post1.md` будут построены как маршруты страниц и HTML-файлы. - - -- src/pages/ - - _hidden-directory/ - - page1.md - - page2.md - - _hidden-page.astro - - **index.astro** - - posts/ - - _SomeComponent.astro - - _utils.js - - **post1.md** - diff --git a/src/content/docs/ru/guides/typescript.mdx b/src/content/docs/ru/guides/typescript.mdx deleted file mode 100644 index fbab44e61a3fd..0000000000000 --- a/src/content/docs/ru/guides/typescript.mdx +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: TypeScript -description: Как использовать встроенную поддержку Typescript в Astro. -i18nReady: true ---- -import Since from '~/components/Since.astro'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; - -Astro по умолчанию поддерживает [TypeScript](https://www.typescriptlang.org/). Вы можете импортировать `.ts` и `.tsx` файлы в свой проект, писать Typescript код прямо внутри своего [компонента Astro](/ru/basics/astro-components/#скрипт-компонента), и даже использовать файл [`astro.config.ts`](/ru/guides/configuring-astro/#файл-конфигурации-astro), если это необходимо. - -Используя Typescript, вы можете предотвратить ошибки во время выполнения, описывая типы объектов и компонентов в коде. К примеру, если вы используете Typescript для [типизации параметров компонента](#параметры-компонентов), то редактор выведет ошибку, если вы попытаетесь передать параметр, который компонент не принимает. - -Чтобы пользоваться преимуществами Typescript, не обязательно писать код на нем в Astro проектах. Astro всегда воспринимает код компонентов как Typescript, и [расширение Astro для VSCode](/ru/editor-setup/) будет стараться определяться типы насколько это возможно, чтобы обеспечить автодополнение, показывать подсказки и ошибки в вашем редакторе. - -Astro dev-сервер не выполняет никакой проверки типов, но вы можете использовать [отдельный скрипт](#проверка-типов) для проверки ошибок типизации прямо из командной строки. - -## Настройка - -Стартовые проекты Astro добавляют `tsconfig.json` файл в ваш проект по умолчанию. Даже если вы не планируете использовать Typescript, не удаляйте его, потому что такие инструменты как Astro и VS Code с помощью него получают информацию о проекте. Некоторые функции (например, импорт пакетов npm) не полностью поддерживаются в редакторе без файла `tsconfig.json`. Если вы устанавливаете Astro вручную, не забудьте создать этот файл самостоятельно. - -### Шаблоны TSConfig - -Astro поддерживает три расширяемых шаблона `tsconfig.json`: `base`, `strict` и `strictest`. Шаблон `base` обеспечивает поддержку современных возможностей JavaScript, а также используется в качестве основы для других шаблонов. Мы рекомендуем использовать `strict` или `strictest` шаблоны, если вы планируете писать Typescript код в своем проекте. Вы можете посмотреть и сравнить эти шаблоны в директории [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/). - -Для наследования от одного из шаблонов используйте синтаксис [`extends`](https://www.typescriptlang.org/tsconfig#extends): - -```json title="tsconfig.json" -{ - "extends": "astro/tsconfigs/base" -} -``` - -Кроме того, мы рекомендуем настроить `include` и `exclude` следующим образом, чтобы воспользоваться преимуществами типов Astro и избежать проверки собранных файлов: - -```json title="tsconfig.json" ins={3-4} -{ - "extends": "astro/tsconfigs/base", - "include": [".astro/types.d.ts", "**/*"], - "exclude": ["dist"] -} -``` - -Вы можете создать файл `src/env.d.ts` как стандартный способ добавления пользовательских объявлений типов или для использования типов Astro, если у вас нет `tsconfig.json`: - -```ts title="src/env.d.ts" -// Пользовательские объявления типов -declare var myString: string; - -// Типы Astro, не требуются, если у вас уже есть `tsconfig.json` -/// -``` - -### Плагин TypeScript для редактора - -[Плагин TypeScript для Astro](https://www.npmjs.com/package/@astrojs/ts-plugin) может быть установлен отдельно, если вы не используете [официальное расширение Astro для VS Code](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). Этот плагин автоматически устанавливается и настраивается расширением VS Code, и вам не нужно устанавливать оба. - -Этот плагин работает только в редакторе. При запуске `tsc` в терминале файлы `.astro` полностью игнорируются. Вместо этого вы можете использовать [команду CLI `astro check`](/ru/reference/cli-reference/#astro-check) для проверки как `.astro`, так и `.ts` файлов. - -Этот плагин также поддерживает импорт `.astro` файлов из `.ts` файлов (что может быть полезно для реэкспорта). - - - - ```shell - npm install @astrojs/ts-plugin - ``` - - - ```shell - pnpm add @astrojs/ts-plugin - ``` - - - ```shell - yarn add @astrojs/ts-plugin - ``` - - - -Затем, добавьте код ниже в `tsconfig.json`: - -```json title="tsconfig.json" -{ - "compilerOptions": { - "plugins": [ - { - "name": "@astrojs/ts-plugin" - }, - ], - } -} -``` -Чтобы проверить, что плагин работает, создайте `.ts` файл и импортируйте Astro компонент в него. Если вы не увидите ошибок, то плагин работает корректно. - -### UI-фреймворки - -Если ваш проект использует [UI-фреймворк](/ru/guides/framework-components/), то вам может потребоваться дополнительная настройка в зависимости от фреймворка. Пожалуйста, проверьте документацию о работе Typescript вместе с вашим фреймворком для дополнительной информации. ([Vue](https://vuejs.org/guide/typescript/overview.html#using-vue-with-typescript), [React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript)) - -## Импорт типов - -По возможности используйте явный импорт и экспорт типов. - -```js del={1} ins={2} ins="type" -import { SomeType } from "./script"; -import type { SomeType } from "./script"; -``` - -Таким образом, вы избежите крайних случаев, когда сборщик Astro попытается некорректно собирать импортированные типы, как если бы они были JavaScript файлом. - -Вы можете настроить TypeScript на принудительный импорт типов в файле `.tsconfig`. Установите параметр [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) в значение `true`. TypeScript проверит ваши импорты и сообщит вам, когда следует использовать `import type`. Эта настройка включена по умолчанию во всех наших пресетах. - -```json title="tsconfig.json" ins={3} -{ - "compilerOptions": { - "verbatimModuleSyntax": true - } -} -``` - -## Импорт алиасов - -Astro поддерживает [импорт алиасов](/ru/guides/imports/#aliases), которые вы определили в секции `paths` в файлах `tsconfig.json` и `jsconfig.json`. [Прочитайте наш гайд](/ru/guides/imports/#aliases), чтобы узнать больше. - -```astro title="src/pages/about/nate.astro" "@components" "@layouts" ---- -import HelloWorld from "@components/HelloWorld.astro"; -import Layout from "@layouts/Layout.astro"; ---- -``` - -```json title="tsconfig.json" {5-6} -{ - "compilerOptions": { - "baseUrl": ".", - "paths": { - "@components/*": ["src/components/*"], - "@layouts/*": ["src/layouts/*"] - } - } -} -``` - -## Расширение `window` и `globalThis` - -Если вы захотите добавить свойство к глобальному объекту, то это можно сделать, добавив ключевое слово `declare` в файл `env.d.ts`: - -```ts title="env.d.ts" -declare const myString: string; -declare function myFunction(): boolean; -``` - -Это обеспечит типизацию `globalThis.myString` и `globalThis.myFunction`, а также `window.myString` и `window.myFunction`. - -Обратите внимание, что `window` доступно только в коде на стороне клиента. Функция `globalThis` доступна как на стороне сервера, так и на стороне клиента, но ее значение на стороне сервера не будет передано клиенту. - -Если вы хотите добавить свойство только для объекта `window`, создайте вместо `global` интерфейс `Window`: - -```ts title="env.d.ts" -interface Window { - myFunction(): boolean; -} -``` - -## Параметры компонентов - -Astro поддерживает типизацию параметров (пропсов) компонентов с помощью TypeScript. Для типизации добавьте TypeScript интерфейс `Props` в метаданных вашего компонента. Вы можете использовать выражение `export`, но это не обязательно. [Расширение Astro для VSCode](/ru/editor-setup/) будет автоматически искать интерфейс `Props` и обеспечивать соответствующую поддержку TS при использовании этого компонента внутри другого шаблона. - -```astro title="src/components/HelloProps.astro" ins={2-5} ---- -interface Props { - name: string; - greeting?: string; -} - -const { greeting = "Привет", name } = Astro.props; ---- -

{greeting}, {name}!

-``` - -### Распространённые паттерны типизации пропсов - -- Если ваш компонент не принимает пропсов или слотов, вы можете использовать `type Props = Record`. -- Если ваш компонент должен передавать дочерние элементы в свой слот, вы можете явно указать это через `type Props = { children: any; };`. - -## Утилиты типизации - -

- -Astro предоставляет встроенные типы для распространённых паттернов типизации пропсов. Они доступны в `astro/types`. - -### Встроенные HTML атрибуты - -Astro предоставляет тип `HTMLAttributes` для проверки того, что в вашей разметке используются валидные HTML-атрибуты. Эти типы можно использовать для создания пропсов компонентов. - -К примеру, если вы создаете компонент ``, вы можете добавить стандартные HTML атрибуты для тега `` в тип пропсов вашего компонента. - -```astro title="src/components/Link.astro" ins="HTMLAttributes" ins="HTMLAttributes<'a'>" ---- -import type { HTMLAttributes } from "astro/types"; - -// используйте `type` -type Props = HTMLAttributes<"a">; - -// или extends с `interface` -interface Props extends HTMLAttributes<"a"> { - myProp?: boolean; -} - -const { href, ...attrs } = Astro.props; ---- - - - -``` - -Также можно расширить стандартные JSX выражения для того, чтобы добавить нестандартные атрибуты с помощью переопределения пространства имен `astroHTML.JSX` в файле `.d.ts`. - -```ts title="src/custom-attributes.d.ts" -declare namespace astroHTML.JSX { - interface HTMLAttributes { - "data-count"?: number; - "data-label"?: string; - } - - // Добавляем пользовательское CSS-свойство в объект `style` - interface CSSProperties { - "--theme-color"?: "black" | "white"; - } -} -``` - -:::note -`astroHTML` глобально доступен внутри компонентов `.astro`. Чтобы использовать его в файлах TypeScript, используйте [тройную слэш-директиву](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html): - -```ts -/// - -type MyAttributes = astroHTML.JSX.ImgHTMLAttributes; -``` -::: - -### Тип `ComponentProps` - -

- -Этот тип экспорта позволяет вам ссылаться на `Props`, принятый другим компонентом, даже если этот компонент не экспортирует этот тип `Props` напрямую. - -В следующем примере показано использование утилиты `ComponentProps` из `astro/types` для ссылки на типы `Props` компонента `