Функция up.navigate

Функция up.navigate является центральным инструментом библиотеки Unpoly для управления навигацией по страницам без полной перезагрузки браузера. Она обеспечивает возможность загрузки нового контента, обновления части страницы или изменения URL с минимальными визуальными перебоями. Основное назначение up.navigate — выполнение AJAX-перехода с сохранением истории браузера и поддержкой эффектов анимации.

up.navigate(url, options)
  • url — строка, указывающая путь или полный адрес страницы, к которой необходимо перейти.
  • options — объект с дополнительными параметрами, влияющими на поведение навигации.

Основные опции up.navigate

1. target Определяет CSS-селектор элемента, который будет заменён новым контентом.

up.navigate('/users/1', { target: '#main-content' });

Если опция не указана, Unpoly заменяет <body> или основной контейнер, определённый по умолчанию.

2. method HTTP-метод запроса. Поддерживаются 'get' и 'post'.

up.navigate('/users', { method: 'post', params: { name: 'Alice' } });

3. params Передача данных на сервер при навигации. Может быть объектом, массивом пар ключ-значение или FormData.

4. cache Управление кэшированием загруженного контента. Возможные значения:

  • 'reload' — всегда загружать заново;
  • 'prefer-cache' — использовать кэш при наличии;
  • 'only-cache' — не делать запрос, использовать только кэш.
up.navigate('/dashboard', { cache: 'prefer-cache' });

5. history Контролирует, будет ли навигация сохраняться в истории браузера. По умолчанию true.

up.navigate('/settings', { history: false });

6. transition Позволяет задавать анимацию перехода между текущим и новым контентом. Поддерживаются встроенные эффекты 'fade', 'slide', 'cross-fade' или пользовательские функции.

up.navigate('/profile', { transition: 'fade' });

Работа с событиями при навигации

up.navigate генерирует несколько ключевых событий, которые позволяют контролировать процесс:

  • up:request — перед отправкой запроса. Можно изменить параметры запроса.
  • up:success — успешное завершение запроса и вставка контента.
  • up:fail — ошибка запроса (например, сервер вернул 500).
  • up:after-update — событие после обновления DOM.

Пример использования событий:

document.addEventListener('up:success', (event) => {
  console.log('Контент обновлён', event.target);
});

Навигация с сохранением состояния

up.navigate поддерживает передачу состояния через объект options.state. Это позволяет хранить дополнительную информацию о текущем состоянии страницы при навигации, которая будет доступна при возвращении через кнопку «Назад».

up.navigate('/search', {
  state: { filter: 'active', page: 2 }
});

Данные из state можно получить при событии up:location-changed:

document.addEventListener('up:location-changed', (event) => {
  console.log(event.state.filter); // 'active'
});

Частичная замена контента

Функция позволяет обновлять только часть страницы без перезагрузки всего документа. Селектор target указывает область для обновления. В сочетании с серверными шаблонами это позволяет создавать интерфейсы с мгновенным откликом, минимизируя нагрузку и мерцания.

up.navigate('/notifications', { target: '#notifications-panel' });

Если сервер возвращает контент с заголовком X-Up-Replace: #notifications-panel, Unpoly автоматически заменит указанный элемент, даже если target не был явно указан.

Прерывание и отмена навигации

Перед отправкой запроса событие up:request можно использовать для условного прерывания:

document.addEventListener('up:request', (event) => {
  if (!confirm('Продолжить переход?')) {
    event.preventDefault();
  }
});

Такой подход обеспечивает контроль над навигацией, предотвращая нежелательные переходы.

Интеграция с формами и ссылками

up.navigate тесно интегрирована с элементами <a> и <form> при использовании атрибутов up-target и up-method. Можно программно инициировать переход по ссылке или отправку формы:

const link = document.querySelector('a[data-up]');
up.navigate(link.href, { target: link.getAttribute('up-target') });

Особенности работы с URL

up.navigate автоматически обновляет адресную строку браузера и управляет историей. При переходе к тому же URL без изменений содержимого Unpoly может использовать кэш. При необходимости можно принудительно перезагрузить контент:

up.navigate('/home', { cache: 'reload' });

Библиотека корректно обрабатывает относительные и абсолютные URL, добавляет хеши и query-параметры без перезагрузки страницы.

Поддержка анимаций и плавных переходов

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

up.navigate('/messages', {
  target: '#inbox',
  transition: (fromEl, toEl, done) => {
    fromEl.style.opacity = 0;
    setTimeout(() => {
      toEl.style.opacity = 1;
      done();
    }, 300);
  }
});

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

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

Оглавление