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

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

Асинхронная отправка форм

Формы в Unpoly можно отправлять асинхронно без изменения стандартного HTML-кода. Для этого достаточно добавить атрибут up-target к форме или к кнопке отправки:

<form action="/users" method="post" up-target="#user-list">
  <input type="text" name="name">
  <button type="submit">Создать пользователя</button>
</form>

Ключевые моменты:

  • up-target указывает на элемент, который будет обновлён после успешной отправки формы.
  • По умолчанию Unpoly отправляет форму через AJAX и подставляет полученный HTML в указанный контейнер.
  • Если up-target не указан, библиотека использует body или ближайший родительский контейнер с up-target.

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

Unpoly предоставляет события, позволяющие контролировать процесс отправки формы и обновления страницы:

  • up:form:submit — вызывается перед отправкой формы. Можно отменить отправку через event.preventDefault().
  • up:form:success — срабатывает после успешной отправки, когда сервер вернул корректный HTML.
  • up:form:error — вызывается при ошибке сервера или при неудачной валидации.
  • up:form:complete — срабатывает в любом случае, после успеха или ошибки.

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

up.on('up:form:success', 'form', (event) => {
  console.log('Форма успешно отправлена!');
});

Динамическая валидация

Unpoly поддерживает как серверную, так и клиентскую валидацию. Для клиентской валидации можно использовать стандартные HTML-атрибуты (required, pattern) вместе с Unpoly:

<form action="/register" method="post" up-target="#messages">
  <input type="email" name="email" required>
  <input type="password" name="password" required minlength="6">
  <button type="submit">Регистрация</button>
</form>

Если сервер возвращает ошибки валидации, Unpoly автоматически обновляет целевой контейнер и отображает ошибки без перезагрузки страницы. Для удобства можно использовать стандартные CSS-классы up-error для подсветки полей с ошибками.

Индикация загрузки

Для улучшения UX рекомендуется показывать индикатор загрузки при отправке формы. В Unpoly это делается через атрибут up-indicator:

<form action="/users" method="post" up-target="#user-list" up-indicator="#spinner">
  <input type="text" name="name">
  <button type="submit">Создать пользователя</button>
</form>
<div id="spinner" style="display:none;">Загрузка...</div>

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

  • Элемент с up-indicator автоматически отображается при начале запроса и скрывается после завершения.
  • Можно использовать несколько индикаторов для разных форм на одной странице.

Обработка ответов сервера

Unpoly позволяет легко обрабатывать различные типы ответа:

  • HTML — обновляет указанный контейнер новым содержимым.
  • JSON — можно обрабатывать через событие up:ajax:success и выполнять кастомные действия:
up.on('up:ajax:success', 'form', (event) => {
  const data = event.responseJSON;
  if (data.status === 'ok') {
    console.log('Данные успешно сохранены:', data);
  }
});
  • Статусные коды — ошибки 4xx и 5xx вызывают событие up:form:error, что позволяет централизованно обрабатывать ошибки на клиенте.

Частичное обновление формы

В Unpoly поддерживается обновление отдельных частей формы без перезагрузки всей страницы. Для этого можно использовать up-target на любом дочернем элементе:

<form action="/profile" method="post">
  <div id="profile-info" up-target>
    <input type="text" name="username" value="user123">
  </div>
  <button type="submit" up-target="#profile-info">Сохранить</button>
</form>

Это позволяет обновлять только изменённые поля и уменьшает нагрузку на страницу.

Отправка форм через ссылки

Unpoly поддерживает отправку форм через <a>-теги с атрибутами up-method и up-target:

<a href="/logout" up-method="post" up-target="body">Выйти</a>
  • up-method задаёт HTTP-метод для запроса (post, put, delete).
  • up-target указывает контейнер для обновления после ответа сервера.

Управление кэшированием

Unpoly автоматически кеширует фрагменты HTML для ускорения повторного отображения. Для форм это особенно полезно, когда необходимо сохранить введённые данные при навигации назад. Атрибуты up-cache и up-nocache позволяют тонко контролировать этот процесс:

<form action="/search" method="get" up-target="#results" up-cache="true">
  <input type="text" name="query">
  <button type="submit">Поиск</button>
</form>

Сочетание с другими библиотеками

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

  • jQuery — для манипуляций с DOM перед отправкой формы.
  • Stimulus или Alpine.js — для реактивного обновления состояния формы.
  • Rails или Django — для серверной генерации HTML с поддержкой Unpoly.

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

  1. Использовать up-target для точечного обновления элементов, избегая перезагрузки всей страницы.
  2. Всегда обрабатывать события up:form:success и up:form:error для централизованной логики.
  3. Применять up-indicator для информирования пользователя о загрузке.
  4. Настраивать валидацию как на клиенте, так и на сервере.
  5. Использовать кэширование фрагментов форм для улучшения UX при навигации.

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

Оглавление