Сериализация форм

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

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

Методы сериализации

up.form.serialize(form)

Метод принимает HTML-элемент <form> или объект jQuery/Element и возвращает строку URL-кодированных параметров (application/x-www-form-urlencoded), готовую для передачи через AJAX:

const form = document.querySelector('#user-form');
const serialized = up.form.serialize(form);
console.log(serialized);
// Пример вывода: "name=Иван&email=ivan%40example.com&subscribe=on"

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

  • Игнорируются неактивные (disabled) поля формы.
  • Чекбоксы и радио-группы сериализуются только если отмечены.
  • Поля с одинаковым name объединяются в массив через повторяющиеся ключи (tags[]=js&tags[]=css).

up.form.serializeArray(form)

Возвращает массив объектов вида { name, value }, что удобно для программной обработки перед отправкой:

const arrayData = up.form.serializeArray(form);
console.log(arrayData);
/*
[
  { name: "name", value: "Иван" },
  { name: "email", value: "ivan@example.com" },
  { name: "subscribe", value: "on" }
]
*/

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

Автоматическая сериализация при отправке

Unpoly автоматически сериализует форму при вызове методов up.submit() или при использовании up-link с атрибутом up-target. Пример:

<form id="user-form" up-target="#profile">
  <input type="text" name="name" value="Иван">
  <input type="email" name="email" value="ivan@example.com">
  <button type="submit">Отправить</button>
</form>
up.on('submit', '#user-form', event => {
  event.preventDefault();
  up.submit(event.target);
});

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

Настройка способа сериализации

Unpoly позволяет контролировать формат отправки данных через опцию formData:

  • formData: true — используется объект FormData для передачи файлов и бинарных данных.
  • formData: false — обычная сериализация в строку URL-кодированных параметров.

Пример отправки с FormData:

up.submit('#user-form', {
  formData: true,
  url: '/profile/update'
});

Это необходимо, когда форма содержит <input type="file">, так как стандартная сериализация в URL не поддерживает бинарные данные.

Сериализация сложных структур

Для вложенных объектов и массивов Unpoly поддерживает синтаксис name="user[address][city]":

<input type="text" name="user[address][city]" value="Москва">
<input type="text" name="user[address][zip]" value="101000">

Сериализация:

up.form.serialize(form);
// "user[address][city]=Москва&user[address][zip]=101000"

На сервере такие данные будут интерпретированы как вложенный объект user.address.

Работа с динамически добавляемыми полями

Если форма содержит элементы, добавляемые через JavaScript, Unpoly корректно их сериализует, если они находятся внутри <form>:

const newInput = document.createElement('input');
newInput.name = 'tags[]';
newInput.value = 'javascript';
form.appendChild(newInput);

up.form.serialize(form);
// "name=Иван&tags[]=javascript"

Массивы и множественные поля обрабатываются автоматически.

Валидация и фильтрация данных перед сериализацией

Unpoly позволяет фильтровать данные через up.form.filterValues:

const filtered = up.form.filterValues(form, (name, value) => {
  return value.trim() !== '';
});

Так можно исключить пустые поля или применять пользовательские правила до отправки на сервер.

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

Серверная часть должна корректно обрабатывать URL-кодированные строки или объекты FormData. Важно учитывать:

  • Для массивов использовать синтаксис name[].
  • Для вложенных объектов синтаксис name[key].
  • В случае файлов — обязательно multipart/form-data.

Особенности при асинхронной загрузке

  • Если форма находится внутри динамически загруженного фрагмента, метод up.form.serialize работает после того, как элемент добавлен в DOM.
  • Обработчики событий up.on('submit', ...) можно применять как к статическим, так и к динамическим формам благодаря делегированию.

Полезные советы по сериализации в Unpoly

  • Использовать serializeArray для работы с данными в JS до отправки.
  • Применять FormData, если требуется загрузка файлов.
  • Всегда проверять вложенные объекты и массивы через синтаксис name[key] или name[].
  • Сериализация игнорирует disabled и скрытые поля без value. Для отправки таких данных их нужно явно включить через JS.
Оглавление