Прокрутка к якорям

Unpoly предоставляет механизмы для навигации по страницам без полной перезагрузки, сохраняя привычное поведение прокрутки к якорям. При загрузке фрагмента возможна автоматическая установка позиции прокрутки, а также тонкое управление поведением при переходах.

Основные принципы

Якорем считается элемент с идентификатором (id), на который ссылается навигация. В классическом подходе браузер прокручивает документ после загрузки страницы. В Unpoly загрузка проходит асинхронно, поэтому требуется координация между обновлённым фрагментом и поведением прокрутки.

Важный момент: прокрутка выполняется только после завершения обновления соответствующего фрагмента. Если целевой элемент отсутствует в обновлённом DOM, прокрутка не происходит.

Прокрутка по умолчанию

Переход up.link или up.navigate способен автоматически обработать якорь, если URL содержит #hash. Например:

/docs#section-api

Если section-api присутствует после обновления фрагмента, Unpoly прокрутит к нему, используя метод scrollIntoView() или собственный механизм.

Управление поведением прокрутки

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

Настройки браузерной прокрутки

  • up.viewport.scroll — контролирует прокрутку внутри viewport-фрагментов.
  • up.fragment.scroll — задаёт прокрутку для конкретного фрагмента.

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

Обновление фрагментов и якоря

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

Примерный алгоритм Unpoly:

  1. Выполнить запрос и обновить фрагмент.
  2. Проверить наличие элемента с якорем.
  3. Если найден — выполнить прокрутку.
  4. Если отсутствует — ничего не делать.

Якоря и история

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

Ключевой аспект: поддерживается привычная модель взаимодействия — переход вперёд приводит к новой прокрутке, назад — к восстановлению.

Пользовательское управление прокруткой

Для более точного контроля используются события и опции переходов:

  • scroll: false — отключает автопрокрутку.
  • scroll: 'top' — фиксированная прокрутка к началу контейнера.
  • scroll: element — позиционирование относительно указанного элемента.

Пример в ссылках:

<a up-target=".content" up-scroll="false">...</a>

и в переходах:

up.navigate(url, { scroll: 'top' })

Якоря в динамическом контенте

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

Прокрутка внутри nested viewport

Unpoly поддерживает вложенные области прокрутки. Элемент с атрибутом up-viewport становится контейнером для содержимого, внутри которого возможны собственные якоря и собственная прокрутка. Это позволяет создавать интерфейсы, напоминающие одностраничные приложения, но без отказа от стандартной семантики URL.

Особенность nested viewport заключается в том, что якорь сопоставляется только с теми фрагментами, которые доступы в его пределах. Если целевой id находится за пределами viewport, Unpoly не переключает уровень вложенности автоматически.

Сложные случаи

Проблемы могут возникать при следующих условиях:

  • якорь совпадает с элементом вне обновлённого фрагмента;
  • обновление происходит со сменой структуры DOM;
  • несколько элементов имеют одинаковый id;
  • используется анимированная загрузка.

В таких ситуациях требуется либо расширить область обновления, либо выполнить ручную прокрутку с помощью up.scroll().

Прокрутка и плавные эффекты

Unpoly не навязывает собственную анимацию прокрутки, но позволяет подключить её через пользовательские скрипты. Плавные переходы становятся естественным дополнением для интерфейсов с точечными навигациями и большим количеством якорей.

Итоговое состояние документа

После выполнения перехода Unpoly обеспечивает согласованность:

  • URL содержит хэш;
  • DOM содержит целевой якорь;
  • позиция прокрутки соответствует якорю;
  • история браузера отражает текущий шаг.

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

Оглавление