Функция up.reload

up.reload — это ключевой инструмент библиотеки Unpoly, предназначенный для обновления частей страницы или всей страницы без полной перезагрузки. Она позволяет динамически подгружать новый HTML и интегрировать его в текущий DOM, сохраняя состояние интерфейса и ускоряя работу веб-приложения.

Основной синтаксис

up.reload([target], [options])

Параметры:

  • target (необязательный) — CSS-селектор или DOM-элемент, который будет обновлён. Если не указан, обновляется вся страница.
  • options (необязательный) — объект с настройками поведения обновления.

Пример обновления всего документа:

up.reload();

Пример обновления конкретного блока:

up.reload('#comments');

Объект options и его свойства

Объект options предоставляет гибкий контроль над поведением функции:

  • url — URL, с которого будет загружен новый HTML. Если не указан, используется текущий адрес страницы.

  • target — переопределяет CSS-селектор блока для обновления.

  • cache — логическое значение. Если true, результат может быть взят из кэша, если false — всегда запрашивается свежий контент.

  • scroll — управляет прокруткой после обновления. Может принимать:

    • false — не скроллить,
    • true — скролл к началу документа,
    • селектор — скролл к указанному элементу.

  • focus — фокус на элемент после обновления. Может быть селектором или false.

  • method — HTTP-метод запроса (GET, POST и т.д.).

  • params — объект с параметрами запроса.

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

up.reload('#notifications', {
  url: '/notifications',
  cache: false,
  scroll: '#notifications'
});

Обновление определённых частей страницы

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

  • обновления списков сообщений,
  • динамических таблиц,
  • блоков с уведомлениями или статусами.

Пример обновления нескольких блоков:

up.reload(['#sidebar', '#main-content']);

При передаче массива селекторов Unpoly обновляет каждый блок отдельно, используя один и тот же запрос, если указана общая url.

Применение с событием up:content:loaded

После обновления контента часто требуется выполнить дополнительный JavaScript. Для этого Unpoly предоставляет событие up:content:loaded:

document.addEventListener('up:content:loaded', (event) => {
  if (event.target.matches('#comments')) {
    console.log('Комментарии обновлены');
  }
});

event.target указывает на обновлённый элемент, что позволяет безопасно выполнять скрипты только для изменённых частей DOM.

Поведение с кэшем

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

Пример отключения кэша:

up.reload('#profile', { cache: false });

Для динамического контента, который изменяется часто (например, лента новостей или уведомления), кэширование рекомендуется отключать.

Использование с AJAX-параметрами

up.reload поддерживает передачу дополнительных параметров через объект params:

up.reload('#search-results', {
  url: '/search',
  params: { query: 'Unpoly', page: 2 }
});

Эти параметры автоматически сериализуются в query string при GET-запросе или в тело запроса при POST.

Настройка плавных переходов

Unpoly предоставляет возможность использовать анимации при обновлении элементов. Для этого в options можно указать:

  • animation — название предопределённой анимации (fade, slide, replace, и др.).
  • duration — длительность анимации в миллисекундах.

Пример:

up.reload('#main-content', {
  animation: 'fade',
  duration: 300
});

Библиотека автоматически добавляет плавное исчезновение старого контента и появление нового.

Обработка ошибок

up.reload возвращает промис, что позволяет обрабатывать успешное обновление или ошибки:

up.reload('#notifications')
  .then(() => console.log('Обновление выполнено'))
  .catch(() => console.log('Ошибка при обновлении'));

Ошибки могут возникать из-за сетевых проблем, некорректного HTML или недоступного URL.

Практические рекомендации

  • Минимизировать область обновления — чем меньше DOM-элемент, тем быстрее обновление и меньше побочных эффектов.
  • Использовать селекторы вместо ID, если блоков несколько однотипных, чтобы обновлять их динамически.
  • Комбинировать с up:fragment:loaded для тонкой настройки поведения отдельных фрагментов.
  • Контролировать кэш для данных, которые часто меняются, чтобы пользователи всегда видели актуальный контент.
  • Использовать анимации осторожно, чтобы не перегружать браузер на больших страницах.

up.reload является универсальным инструментом для динамического обновления страниц в Unpoly, обеспечивая скорость, плавность и контроль над частями DOM без полной перезагрузки.

Оглавление