Установка контекста

Unpoly — это библиотека для создания динамических веб-приложений с минимальным использованием JavaScript. Она позволяет обновлять отдельные части страницы без полной перезагрузки, обеспечивая плавный пользовательский опыт и сокращение объёма сетевых запросов. В основе работы лежит концепция progressive enhancement: страницы работают без JavaScript, а Unpoly добавляет динамику поверх уже существующей структуры.

Инициализация и подключение

Для использования Unpoly необходимо подключить её JavaScript и CSS-файлы. Обычно это делается через CDN или локальные файлы:

<link rel="stylesheet" href="https://unpkg.com/unpoly/dist/unpoly.min.css">
<script src="https://unpkg.com/unpoly/dist/unpoly.min.js"></script>

После подключения библиотека автоматически начинает отслеживать ссылки и формы на странице, обеспечивая их ajax-подгрузку. Для полной работы важно, чтобы сервер возвращал корректный HTML: Unpoly заменяет только определённые фрагменты страницы, не трогая остальной DOM.

Селекторы и таргетинг

Ключевой концепцией является targeting. Любой элемент на странице можно обновлять с помощью CSS-селектора:

<div id="content">
  <p>Первичный контент</p>
</div>
<a href="/new_content" up-target="#content">Загрузить новый контент</a>

Атрибут up-target указывает, какой элемент на странице должен быть обновлён при клике на ссылку. Если атрибут отсутствует, Unpoly заменяет весь <body>.

Дополнительные важные атрибуты:

  • up-method — HTTP-метод (GET, POST) для запроса.
  • up-transition — анимация при обновлении (fade, slide, cross-fade и др.).
  • up-swap — способ замены содержимого (replace, prepend, append, before, after).

Работа с формами

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

<form action="/submit" method="post" up-target="#content">
  <input type="text" name="name">
  <button type="submit">Отправить</button>
</form>

При успешной отправке сервер должен вернуть HTML-фрагмент, который заменит содержимое указанного up-target. Важный момент: серверу не нужно возвращать весь <body>, достаточно только обновляемой части.

Настройка поведения форм

  • up-validate — включение клиентской валидации перед отправкой.
  • up-disable — блокировка кнопки при отправке.
  • up-confirm — вывод диалогового окна подтверждения перед отправкой.

События и хуки

Unpoly предоставляет гибкую систему событий для управления динамикой:

  • up:click — перед выполнением запроса по ссылке.
  • up:request — перед отправкой любого запроса.
  • up:success — после успешного обновления фрагмента.
  • up:error — при ошибке запроса.

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

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

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

Управление историей

Unpoly интегрируется с историей браузера через pushState. Каждое обновление страницы фиксируется в истории, что позволяет использовать кнопки «назад» и «вперед». Основные методы:

  • up.navigate(url, options) — программная навигация с возможностью указать target, method и transition.
  • up.reload() — обновление текущего фрагмента.
  • up.replace(url) — замена контента без добавления в историю.

Работа с фрагментами

Важной практикой является разделение страницы на фрагменты с уникальными идентификаторами:

<div id="header"></div>
<div id="content"></div>
<div id="footer"></div>

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

Настройки глобального поведения

Глобальные параметры можно настраивать через объект up.options:

up.options.animation = 'cross-fade';
up.options.cache = true;
up.options.method = 'get';
  • animation — анимация по умолчанию.
  • cache — включение кеширования запросов.
  • method — HTTP-метод для всех ссылок и форм по умолчанию.

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

Unpoly автоматически обрабатывает сетевые ошибки и ошибки сервера. В случае ошибки up:error можно определить кастомное поведение:

up.on('up:error', function(event) {
  alert('Ошибка загрузки: ' + event.status);
});

Дополнительно поддерживаются «фрагментные ошибки» — когда сервер возвращает некорректный HTML только для определённого up-target.

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

Серверная часть должна возвращать валидный HTML-фрагмент, соответствующий up-target. Рекомендуется использовать шаблоны, которые могут рендерить как полный HTML, так и только фрагменты. Unpoly автоматически определяет, является ли ответ фрагментом или полной страницей, и корректно его подставляет.

Формат ответа может включать дополнительные заголовки:

  • X-Up-Location — перенаправление после запроса.
  • X-Up-Target — указание целевого фрагмента для обновления.

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

Анимации делают обновление контента более естественным. Основные типы переходов:

  • fade — плавное исчезновение и появление.
  • slide — сдвиг элемента сверху или снизу.
  • cross-fade — одновременное исчезновение старого и появление нового содержимого.
  • none — отключение анимации.

Переходы можно задавать как глобально, так и на конкретных ссылках или формах через up-transition.

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

Оглавление