Навигация с Turbo Drive - geroi/turbo-rails GitHub Wiki

Turbo Drive - это часть Turbo, которая улучшает навигацию на уровне страницы. Она следит за кликами по ссылкам и отправкой форм, выполняет их в фоновом режиме и обновляет страницу без полной перезагрузки. Это эволюция библиотеки, ранее известной как Turbolinks.

• Основы навигации по страницам
• Application визит
• Restoration визиты
• Отмена визитов до их начала
• Пауза рендеринга
• Пауза запросов
• Отключение Turbo Drive на определенных ссылках или формах
• Отображение прогресса
• Перезагрузка при изменении ассетов
• Обеспечение того, чтобы определенные страницы вызывали полную перезагрузку
• Установка корневого расположения
• Перенаправление после отправки формы
• Стриминг после отправки формы

Turbo Drive моделирует навигацию по странице как посещение (URL) с экшном.

Посещения представляют собой весь жизненный цикл навигации от щелчка до рендеринга. Сюда входит изменение истории браузера, отправка сетевого запроса, восстановление копии страницы из кэша, рендеринг окончательного ответа и обновление позиции прокрутки. Существует два типа визита: application визит, действие которого заключается в advance или replace, и визит restoration, действие которого заключается в restore.

Application визит инициируется нажатием на ссылку с поддержкой Turbo Drive или программным вызовом Turbo.visit(location). При application визите всегда отправляется сетевой запрос. Когда приходит ответ, Turbo Drive отображает его HTML и завершает визит.

Если это возможно, Turbo Drive выводит предварительный просмотр страницы из кэша сразу после начала посещения. Это улучшает воспринимаемую скорость при частой навигации между одними и теми же страницами.

Если местоположение визита включает анкор, Turbo Drive попытается прокрутить страницу до элемента с анкором. В противном случае он будет прокручивать страницу до самого верха.

Application visit приводит к изменению истории браузера; экшн визита определяет, каким образом.

Действие посещения по умолчанию - advance. Во время advance посещения Turbo Drive помещает новую запись в стек истории браузера с помощью history.pushState.

Приложения, использующие адаптер Turbo Drive iOS, обычно обрабатывают advance визиты путем размещения нового контроллера представления в стеке навигации. Аналогично, приложения, использующие адаптер Android, обычно размещают новую activity в стеке back.

Вы можете захотеть посетить местоположение без занесения новой записи истории в стек. Действие replace visit использует history.replaceState для отбрасывания самой верхней записи истории и замены ее новым местоположением.

Чтобы указать, что переход по ссылке должен вызвать посещение с заменой, аннотируйте ссылку с data-turbo-action="replace":

< a href="/edit" data-turbo-action="replace"> Редактировать</a>

Чтобы программно посетить местоположение с помощью действия replace, передайте action: "replace" в Turbo.visit:

Turbo. visit("/edit", { action: "replace" })

Приложения, использующие адаптер Turbo Drive iOS, обычно обрабатывают замену посещений путем dismiss самого верхнего контроллера представления и перемещения нового контроллера представления в стек навигации без анимации.

Turbo Drive автоматически инициирует посещение restoration при навигации с помощью кнопок "Назад" или "Вперед" браузера. Приложения, использующие адаптеры для iOS или Android, инициируют посещение восстановления при перемещении назад в навигационном стеке.

Если это возможно, Turbo Drive отрендерит копию страницы из кэша без запроса. В противном случае он получит свежую копию страницы по сети. Дополнительные сведения см. в разделе Понимание кэширования.

Turbo Drive сохраняет положение прокрутки каждой страницы перед переходом на другую страницу и автоматически возвращается к этому сохраненному положению при повторных посещениях.

Визиты restoration имеют экшн restoration, и Turbo Drive резервирует их для внутреннего использования. Вы не должны пытаться аннотировать ссылки или вызывать Turbo.visit с действием restore.

Посещения приложения могут быть отменены до их начала, независимо от того, были ли они инициированы щелчком по ссылке или вызовом Turbo.visit.

Ожидайте событие turbo:before-visit, чтобы получить уведомление о начале визита, и используйте event.detail.url (или $event.originalEvent.detail.url, если используется jQuery) для проверки местоположения визита. Затем отмените посещение, вызвав event.preventDefault().

Restoration визиты не могут быть отменены и не отменяют turbo:before-visit. Turbo Drive выполняет restoration визиты в ответ на уже состоявшуюся навигацию по истории, обычно с помощью кнопок "Назад" или "Вперед" браузера.

Приложение может приостановить рендеринг и провести дополнительную подготовку перед его выполнением. Слушайте событие turbo:before-render, чтобы получить уведомление, когда рендеринг вот-вот начнется, и приостановите его с помощью event.preventDefault(). После завершения подготовки продолжите рендеринг, вызвав event.detail.resume(). В качестве примера можно привести добавление анимации при выходе с сайта:

document. addEventListener('turbo:before-render', async (event) => {
    event.preventDefault()
    await animateOut()
    event.detail.resume()
})

Приложение может приостановить запрос и провести дополнительную подготовку перед его исполнением.

Слушайте событие turbo:before-fetch-request, чтобы получить уведомление, когда запрос вот-вот начнется, и приостановите его с помощью event.preventDefault(). После завершения подготовки запрос будет продолжен вызовом event.detail.resume().

Примером использования является установка заголовка Authorization для запроса:

document.addEventListener('turbo:before-fetch-request', async (event) => {
  event.preventDefault()

  const token = await getSessionToken(window.app)
  event.detail.fetchOptions.headers['Authorization'] = `Bearer ${token}`

  event.detail.resume()
})

Turbo Drive можно отключить для каждого элемента, указав в аннотации элемента или любого из его предков data-turbo="false".

    <a href="/" data-turbo="false">Disabled</a>
    
    <form action="/messages" method="post" data-turbo="false">
      ...
    </form>
    
    <div data-turbo="false">
      <a href="/">Disabled</a>
      <form action="/messages" method="post">
        ...
      </form>
    </div>

Для повторного включения, если предок отказался, используйте data-turbo="true":

<div data-turbo="false">
  <a href="/" data-turbo="true">Enabled</a>
</div>

Ссылки или формы с отключенным Turbo Drive будут обрабатываться браузером в обычном режиме. Если вы хотите, чтобы Drive был опциональным, а не опциональным, вы можете установить Turbo.session.drive = false; тогда data-turbo="true" будет использоваться для включения Drive на основе каждого элемента. Если вы импортируете Turbo в пакете JavaScript, вы можете сделать это глобально:

import { Turbo } from "@hotwired/turbo-rails"
Turbo.session.drive = false

Отображение прогресса

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

Индикатор выполнения включен по умолчанию. Он появляется автоматически на любой странице, загрузка которой занимает более 500 мс. (Вы можете изменить эту задержку с помощью метода Turbo.setProgressBarDelay).

Прогресс бар - это элемент

.turbo-progress-bar {
  height: 5px;
  background-color: green;
}

.turbo-progress-bar {
  visibility: hidden;
}

<head>
  ...
  <link rel="stylesheet" href="/application-258e88d.css" data-turbo-track="reload">
  <script src="/application-cbd3cd4.js" data-turbo-track="reload"></script>
</head>

<head>
  ...
  <meta name="turbo-visit-control" content="reload">
</head>

<head>
  ...
  <meta name="turbo-root" content="/app">
</head>