Роутинг
Astro использует маршрутизацию на основе файлов для генерации URL ваших сборок на основе структуры файлов в вашем проекте в директории src/pages/
.
Навигация между страницами
Astro использует стандартные HTML <a>
элементы для навигации между маршрутами. Нет специфического для фреймворка компонента <Link>
.
Статические маршруты
.astro
компоненты страниц а также Markdown и MDX файлы (.md
, .mdx
) внутри директории src/pages/
автоматически становятся страницами вашего веб-сайта. Маршрут каждой страницы соответствует ее пути и имени файла в директории src/pages/
.
В проекте Astro нет отдельного «конфигурационного файла маршрутизации»! Когда вы добавляете файл в директорию src/pages/
, для вас автоматически создается новый маршрут. В статических сборках вы можете настроить формат вывода файла с помощью опции конфигурации build.format
(EN).
Динамические маршруты
Файл страницы Astro может указывать динамические параметры маршрута в его имени файла, чтобы генерировать несколько соответствующих страниц. Например, src/pages/authors/[author].astro
генерирует страницу биографии для каждого автора на вашем блоге. author
становится параметром, который вы можете получить изнутри страницы.
В режиме статического вывода по умолчанию эти страницы генерируются во время сборки, поэтому вы должны предварительно определить список author
-ов, которые получат соответствующий файл. В режиме SSR страница будет генерироваться по запросу для любого маршрута, который соответствует.
Статический (SSG) режим
Поскольку все маршруты должны быть определены во время сборки, динамический маршрут должен экспортировать getStaticPaths()
, который возвращает массив объектов со свойством params
. Каждый из этих объектов будет генерировать соответствующий маршрут.
[dog].astro
определяет динамический параметр dog
в его имени файла, поэтому объекты, возвращенные getStaticPaths()
, должны включать dog
в их params
. Затем страница может получить доступ к этому параметру с помощью Astro.params
.
Это сгенерирует три страницы: /dogs/clifford
, /dogs/rover
и /dogs/spot
, каждая из которых отображает соответствующее имя собаки.
Имя файла может включать несколько параметров, которые все должны быть включены в объекты params
в getStaticPaths()
:
Это сгенерирует /en-v1/info
и /fr-v2/info
.
Параметры могут быть включены в отдельные части пути. Например, файл src/pages/[lang]/[version]/info.astro
с тем же getStaticPaths()
выше сгенерирует маршруты /en/v1/info
и /fr/v2/info
.
📚 Узнайте больше о getStaticPaths()
(EN).
Rest параметры
Если вам нужна большая гибкость в маршрутизации URL, вы можете использовать rest параметр ([...path]
) в имени вашего .astro
файла для сопоставления путей файлов любой глубины:
Это сгенерирует /sequences/one/two/three
, /sequences/four
, и /sequences
. (Установка rest параметра в undefined
позволяет ему сопоставиться с страницей верхнего уровня.)
Rest параметры могут быть использованы с другими именованными параметрами. Например, просмотрщик файлов GitHub может быть представлен следующим динамическим маршрутом:
В этом примере запрос на /withastro/astro/tree/main/docs/public/favicon.svg
будет разбит на следующие именованные параметры:
Пример: Динамические страницы на нескольких уровнях
В следующем примере rest параметр ([...slug]
) и функция props
(EN) getStaticPaths()
генерирует страницы для путей разной глубины.
Режим сервера (SSR)
В режиме SSR (EN), динамические маршруты определяются таким же образом: включите [param]
или [...path]
скобки в именах ваших файлов, чтобы соответствовать произвольным строкам или путям. Но поскольку маршруты больше не создаются заранее, страница будет предоставлена для любого соответствующего маршрута. Поскольку это не «статические» маршруты, getStaticPaths
не следует использовать.
Эта страница будет предоставлена для любого значения resource
и id
: resources/users/1
, resources/colors/blue
, и т.д.
Изменение примера с [...slug]
для SSR
Поскольку страницы SSR не могут использовать getStaticPaths()
, они не могут получать props. Предыдущий пример можно адаптировать для режима SSR, ища значение параметра slug
в объекте. Если маршрут находится в корне (”/”), параметр slug будет undefined
. Если значение не существует в объекте, мы перенаправляем на страницу 404.
Переадресации
Иногда вам потребуется перенаправить ваших читателей на новую страницу, либо постоянно, потому что структура вашего сайта изменилась, либо в ответ на действие, такое как вход в аутентифицированный маршрут.
Вы можете определить правила для перенаправления пользователей на постоянно перемещенные страницы в вашем конфиге Astro. Или динамическое перенаправление пользователей при использовании вашего сайта.
Настроенные переадресации (экспериментально)
Добавлено в:astro@2.6.0
После включения экспериментального флага redirects: true
, вы можете указать сопоставление постоянных переадресаций в вашем конфигурационном файле Astro. Для большинства переадресаций это сопоставление старого маршрута с новым маршрутом:
Эти переадресации следуют тем же правилам, что и маршруты на основе файлов. Динамические маршруты разрешены, если и новые, и старые маршруты содержат одни и те же параметры, например:
Используя SSR или статический адаптер, вы также можете предоставить объект в качестве значения, позволяющий указать код ответа status
в дополнение к новому адресу destination
:
При запуске astro build
, Astro будет выводить HTML-файлы с тегом meta refresh по умолчанию. Поддерживаемые адаптеры вместо этого запишут конфигурационный файл хоста с переадресациями.
Код статуса по умолчанию 301
. Если сборка ведется в HTML-файлы, сервер не использует код статуса.
Динамические переадресации
На глобальном Astro
, метод Astro.redirect
позволяет вам динамически перенаправлять на другую страницу. Вы можете сделать это после проверки того, вошел ли пользователь в систему, получив их сессию из cookie.
`
Приоритет маршрутов
Возможно, несколько маршрутов будут соответствовать одному и тому же URL-пути. Например, каждый из этих маршрутов совпадет с /posts/create
:
Директорияsrc/pages/
Директорияposts/
- create.astro
- [pid].astro
- […slug].astro
Astro должен знать, какой маршрут следует использовать для создания страницы. Чтобы сделать это, оно сортирует их в соответствии со следующими правилами:
- Статические маршруты без параметров пути имеют преимущество перед всеми другими маршрутами
- Динамические маршруты с использованием именованных параметров имеют преимущество перед параметрами rest
- Предварительно отрендеренные динамические маршруты в приоритете перед динамическими маршрутами сервера
- Параметры rest имеют наименьший приоритет
- Конечные точки всегда имеют приоритет над страницами
- Ничьи разрешаются в алфавитном порядке
Приведя пример выше, вот несколько примеров того, как правила будут сопоставлять запрошенный URL с маршрутом, используемым для построения HTML:
pages/posts/create.astro
- Строит/posts/create
pages/posts/[pid].astro
- Строит/posts/1
,/posts/abc
, и т.д. Но не/posts/create
pages/posts/[...slug].astro
- Строит/posts/1/2
,/posts/a/b/c
, и т.д. Но не/posts/create
,/posts/1
,/posts/abc
Переадресации также следуют тем же правилам, но имеют приоритет в последнюю очередь; если есть маршрут на основе файла и переадресация с тем же уровнем приоритета маршрута, выбирается маршрут на основе файла.
Пагинация (разбитие на страницы)
Astro поддерживает встроенную пагинацию для больших коллекций данных, которые необходимо разделить на несколько страниц. Astro будет генерировать общие свойства пагинации, включая URL-ы предыдущей/следующей страницы, общее количество страниц и многое другое.
Имена маршрутов с пагинацией должны использовать тот же синтаксис [скобок]
, что и стандартный динамический маршрут. Например, имя файла /astronauts/[page].astro
будет генерировать маршруты для /astronauts/1
, /astronauts/2
, и так далее, где [page]
- это сгенерированный номер страницы.
Вы можете использовать функцию paginate()
для генерации этих страниц для массива значений следующим образом:
Это генерирует следующие страницы, с 2 элементами на страницу:
/astronauts/1
- Страница 1: Отображает “Нил Армстронг” и “Базз Алдрин”/astronauts/2
- Страница 2: Отображает “Салли Райд” и “Джон Гленн”
Prop page
Когда вы используете функцию paginate()
, каждой странице будут переданы ее данные через prop page
. У prop page
есть много полезных свойств, но вот самые важные:
- page.data - массив, содержащий часть данных страницы, которую вы передали функции
paginate()
- page.url.next - ссылка на следующую страницу в наборе
- page.url.prev - ссылка на предыдущую страницу в наборе
Полная справка по API
Вложенная пагинация
Более продвинутый сценарий использования пагинации - вложенная пагинация. Здесь пагинация сочетается с другими динамическими параметрами маршрута. Вы можете использовать вложенную пагинацию для группировки вашей пагинированной коллекции по некоторому свойству или тегу.
Например, если вы хотите сгруппировать ваши пагинированные посты в Markdown по некоторому тегу, вы должны использовать вложенную пагинацию, создав страницу /src/pages/[tag]/[page].astro
, которая будет соответствовать следующим URL:
/red/1
(tag=red)/red/2
(tag=red)/blue/1
(tag=blue)/green/1
(tag=green)
Вложенная пагинация работает, возвращая массив результатов paginate()
из getStaticPaths()
, по одному для каждой группы.
В следующем примере мы реализуем вложенную пагинацию для построения перечисленных выше URL:
Исключение страниц
Вы можете исключить страницы или директории из сборки, добавив перед их именами подчеркивание (_
). Файлы с префиксом _
не будут распознаваться маршрутизатором и не будут помещены в директорию 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