WS Form


WS Form предоставляет единый интерфейс для чтения и изменения полей HTML-формы, проверки значений и обработки отправки.

Поддерживает

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

Подключение

js
import { wsForm } from '/core/modules/ws-form/assets/js/initial.js';

Быстрый старт

html
<form id="contact-form">
    <label>
        Имя
        <input type="text" name="name">
    </label>
    <button type="submit">Отправить</button>
</form>
js
const form = wsForm(document.querySelector('#contact-form'));

form.required('name', 'Укажите имя');

form.onSubmit(({ values, valid }) => {
    if (!valid) {
        return;
    }

    console.log(values.name);
}, {
    validate: true,
    prevent: true
});

wsForm() принимает элемент <form> и возвращает объект для работы с формой. Параметр validate: true включает проверку при отправке; без него обработчик получает valid: true без запуска проверки. Параметр prevent: true отменяет стандартную отправку браузером. По умолчанию она не отменяется.

Шаблоны ввода

Готовые шаблоны доступны через form.templates. Каждый метод принимает имя существующего поля и возвращает объект формы. Настройки передаются вторым аргументом; для mask() объект настроек с параметром mask обязателен. Шаблон не создаёт HTML-поле: сначала добавьте его в <form> с нужным атрибутом name.

Шаблон Что делает
mask(name, options) Задаёт формат ввода с цифровыми, буквенными и смешанными позициями.
email(name, options) Проверяет формат адреса электронной почты.
login(name, options) Допускает логин или адрес электронной почты.
password(name, options) Проверяет пароль; по умолчанию длина от 8 до 36 символов.
number(name, options) Оставляет только цифры при вводе и проверяет их при валидации.
phone(name, options) Форматирует международный номер телефона и проверяет его длину.
slug(name, options) Нормализует адресную часть и при необходимости синхронизирует её с другим полем.
date(name, options) Добавляет к полю календарь выбора даты.
color(name, options) Добавляет панель выбора цвета и проверку его значения.

Универсальная маска

Для существующего текстового поля с name="document-code":

js
form.templates.mask('document-code', {
    mask: 'AA-9999',
    'letter-case': 'upper',
    required: true,
    requiredMessage: 'Укажите код',
    patternMessage: 'Заполните код полностью'
});

В маске 9 обозначает цифру 0-9, A обозначает букву Unicode, а * допускает букву или цифру. Остальные символы являются фиксированными.

Чтобы использовать специальный символ как фиксированный, экранируйте его. Например, mask: '\\A999' задаёт фиксированную букву A и три цифровые позиции.

Параметр Описание
mask Непустая строка маски или непустой массив строк масок. Обязателен.
placeholder Один символ-заполнитель, по умолчанию _. Буквы и цифры 0-9 не допускаются.
letter-case Регистр букв: none, upper или lower. По умолчанию none.
alphabet Строка разрешённых букв для позиций A и *. По умолчанию разрешены любые буквы Unicode.
inputMode Подсказка экранной клавиатуре. По умолчанию numeric, если все вводимые позиции цифровые, иначе text.
required Обязательность поля. По умолчанию сохраняется состояние HTML-поля.
requiredMessage Сообщение для пустого обязательного поля.
patternMessage Сообщение для значения, не соответствующего полностью заполненной маске.

В примере ввод ab1234 преобразуется в AB-1234. Через form.value('document-code') возвращается форматированное значение, включая дефис.

Частично заполненная маска не проходит проверку. Пустое поле допустимо, если оно не обязательное.

Универсальная маска поддерживает текстовые input и textarea с доступным управлением положением курсора. Для обычного поля используйте input type="text", а не input type="number".

При подключении маски HTML-атрибуты pattern, minlength и maxlength снимаются. Формат ввода задавайте параметрами маски.

Несколько вариантов маски

Если поле допускает несколько форматов, передайте массив строк в параметре mask. Например, для поля с name="reference-code":

js
form.templates.mask('reference-code', {
    mask: ['99-99', '99-99-99'],
    required: true,
    requiredMessage: 'Укажите код',
    patternMessage: 'Введите четыре или шесть цифр'
});

Ввод 1234 даёт значение 12-34, а 123456 даёт 12-34-56. Пять цифр оставляют длинную маску незаполненной, поэтому такое значение не проходит проверку.

Модуль автоматически выбирает формат при вводе и удалении символов. Если значение помещается в несколько вариантов, предпочтение отдаётся маске с меньшим количеством вводимых позиций.

Массив должен быть непустым. Каждый элемент должен быть непустой строкой маски с вводимыми позициями.

Общие параметры placeholder, letter-case, alphabet и сообщения проверки применяются ко всем вариантам.

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

Массив вариантов поддерживается у mask(). У телефонного шаблона phone() параметр mask принимает только одну строку.

Email, логин и пароль

js
form.templates.email('email', {
    required: true,
    requiredMessage: 'Укажите почту',
    patternMessage: 'Некорректный адрес'
});

form.templates.login('login', {
    required: true,
    min: 3,
    max: 50
});

form.templates.password('password', {
    required: true,
    min: 8,
    max: 36
});

Для этих шаблонов required по умолчанию выключен. Для email и login длина не ограничивается, пока не заданы min или max. Тексты ошибок можно переопределять параметрами requiredMessage, minMessage, maxMessage и patternMessage.

У password значения min и max по умолчанию равны 8 и 36. Максимальную длину можно уменьшить, но нельзя увеличить выше 36. Пробелы учитываются в длине пароля и не удаляются. По умолчанию допускаются ASCII-символы от пробела до ~ и символы Unicode диапазона U+0080–U+07FF, включая кириллицу.

Число и телефон

js
form.templates.number('code', {
    required: true,
    max: 6
});

form.templates.phone('phone', {
    required: true,
    mask: '+375 (__) ___-__-__',
    min: 12,
    max: 12
});

number работает со строкой цифр, а не преобразует значение поля в тип number. Его max ограничивает количество цифр.

У phone символ _ обозначает позицию для вводимой цифры; параметром digit его можно заменить. Маска должна начинаться с +. Параметры min и max задают длину полного номера **в цифрах**, включая фиксированные цифры маски. form.value('phone') возвращает номер без пробелов и скобок, например +375291234567. Без маски поддерживается международный номер длиной от 3 до 15 цифр.

Параметры min и max должны быть целыми числами: 1 <= min <= max <= 15. По умолчанию min равен 3, а max равен вместимости маски в цифрах или 15, если маска не задана.

При заданной маске max не может превышать её вместимость и должен оставлять хотя бы одну вводимую цифру после фиксированного префикса.

В отличие от универсальной маски, телефонный шаблон допускает номер короче маски, если достигнута длина min. Чтобы требовать заполнения всех позиций, задайте min и max равными полной длине номера в цифрах.

Обязательность телефонного поля по умолчанию определяется его HTML-атрибутом required. Параметр autocomplete по умолчанию равен tel.

Адресная часть

js
form.templates.slug('slug', {
    origin: 'title',
    slash: false
});

При изменении title шаблон обновляет slug: приводит текст к нижнему регистру, заменяет пробелы дефисами и по умолчанию транслитерирует кириллицу. slash: false запрещает / в результате; cyrillic: true сохраняет кириллицу. Если задан toggle, синхронизация зависит от состояния соответствующего флажка.

Дата

js
form.templates.date('published-at', {
    time: true
});

Шаблон добавляет календарь к существующему полю. Без time значение имеет формат YYYY-MM-DD, с time: true — YYYY-MM-DD HH:MM:SS. Язык календаря можно передать при создании формы: wsForm(formNode, { lang: 'ru' }). Для оформления календаря передайте { style: true } при создании формы: модуль подключит свой CSS.

Выбор цвета

Шаблон color() добавляет к текстовому полю панель выбора цвета с режимами HEX и RGB, настройкой непрозрачности и историей последних цветов.

html
<form id="appearance-form">
    <label for="accent-color">Основной цвет</label>
    <input id="accent-color" type="text" name="accent-color" value="27,27,27,1">
</form>

В JavaScript-модуле после импорта wsForm:

js
const appearance = wsForm(document.querySelector('#appearance-form'), {style: true, lang: 'ru'});
appearance.templates.color('accent-color', {required: true, size: 32});

console.log(appearance.value('accent-color')); // '27,27,27,1'

Параметр style: true подключает стили модуля.

Параметр Описание
required Обязательность поля. По умолчанию сохраняется состояние HTML-поля.
size Размер элемента управления: 24, 32 или 40. По умолчанию 32.
lang Язык подписей: ru для русского, иначе английский. По умолчанию используется язык формы.
texts Объект переводов подписей и сообщений, например title, choose, clear, required, invalid.
required-message Сообщение для пустого обязательного поля.
pattern-message Сообщение для некорректного значения цвета.
on-update Функция, получающая строку значения при его установке, в том числе через setValue().

Значение поля имеет формат R,G,B,A: три целых числа от 0 до 255 и непрозрачность от 0 до 1. Для использования в CSS значение нужно обернуть в rgba(...).

Режим HEX относится к интерфейсу панели. Строки #1B1B1B и rgba(27,27,27,1) в самом поле не проходят проверку.

Пустое значение допустимо, если поле не обязательное. Очистить его можно кнопкой панели или через appearance.clear('accent-color').

Поддерживаются input типов text, search и tel. Нативное поле input type="color" и textarea не подходят.

Выбор цвета с экрана доступен только при поддержке этой возможности браузером.

Значения полей

Имя поля соответствует его HTML-атрибуту name.

Метод Назначение
has(name) Проверить наличие поля с указанным именем.
value(name) Получить значение одного поля.
setValue(name, value) Установить значение одного поля.
values() Получить объект значений всех полей формы.
setValues(values) Установить значения существующих полей из объекта.
clear(name) Очистить одно поле.
clearAll() Очистить все поля.
js
form.setValue('name', 'Анна');

console.log(form.value('name'));
console.log(form.values());

Для текстового поля значение является строкой. Одиночный флажок возвращает true или false, группа флажков — массив значений выбранных элементов, группа радиокнопок — значение выбранного элемента либо пустую строку. Поле выбора файла возвращает массив объектов File; назначить ему файлы через setValue() нельзя.

removeField(name)

Отключает связанные с полем обработчики и виджеты модуля. Используйте перед удалением или заменой HTML-поля в динамической форме:

js
form.removeField('name');

Возвращает объект формы. Если поле ещё не подключено к модулю, ничего не меняется.

Сам HTML-элемент остаётся в форме. Метод не исключает его из отправки и не делает has(name) равным false.

При следующем обращении через value(), setValue() или values() модуль снова подключит существующее поле. Нужные обработчики и шаблоны следует назначить заново.

Группы полей

Несколько радиокнопок или флажков с одинаковым name обрабатываются как одно поле. Для группы флажков в setValue() передавайте массив строк:

html
<form id="preferences-form">
    <label><input type="checkbox" name="topics[]" value="news"> Новости</label>
    <label><input type="checkbox" name="topics[]" value="updates"> Обновления</label>
</form>
js
const preferences = wsForm(document.querySelector('#preferences-form'));

preferences.setValue('topics[]', ['news', 'updates']);
console.log(preferences.value('topics[]')); // ['news', 'updates']

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

Проверка значений

Метод Назначение
required(name, message) Сделать поле обязательным и задать сообщение об ошибке.
minLength(name, min, message) Проверять минимальную длину текста.
maxLength(name, max, message) Проверять максимальную длину текста.
pattern(name, expression, message) Проверять текст регулярным выражением.
validate(name) Проверить указанное поле; без name — зарегистрированные поля формы.
errors(name) Получить массив ошибок поля после проверки.
resetValidation(name) Сбросить ошибки указанного поля; без name — зарегистрированных полей.
js
form.required('name', 'Укажите имя');
form.minLength('name', 2, 'Имя слишком короткое');

if (!form.validate('name')) {
    console.log(form.errors('name'));
}

Правила проверки добавляются при вызове соответствующих методов. Отключённые поля проверку не проходят.

Отображение ошибок

WS Form хранит ошибки полей, но не создаёт для них HTML-разметку. Вывод сообщений остаётся за кодом вашей формы.

Добавьте место для сообщения рядом с полем name:

html
<p id="name-error" role="alert"></p>

Если сервер вернул ошибку для этого поля, передайте её как массив строк:

js
const nameError = document.querySelector('#name-error');

form.setErrors({
    name: ['Имя уже используется']
});

nameError.textContent = form.firstError('name');
form.focusFirstError();

setErrors() принимает объект, где ключи — имена существующих полей, а значения — массивы сообщений. firstError(name) возвращает первое сообщение или пустую строку. hasErrors() позволяет проверить, есть ли ошибки у доступных полей.

Для сброса сообщения очистите и состояние формы, и выведенный текст:

js
form.clearErrors('name');
nameError.textContent = '';

clearErrors(name) не меняет HTML самостоятельно. Повторный вызов validate() также сбрасывает ранее установленные ошибки и запускает правила проверки заново, поэтому не вызывайте его сразу после setErrors(), если хотите показать ответ сервера.

Несохранённые изменения

После настройки формы и заполнения начальных значений включите предупреждение перед уходом:

js
form.protectChanges();

Метод запоминает текущее состояние. Если данные изменятся, при уходе со страницы, перезагрузке или закрытии вкладки модуль запрашивает стандартное предупреждение браузера. Возможность его показа и текст определяет браузер.

Обычная отправка формы, не отменённая обработчиком, не вызывает это предупреждение. Закрытие внутренних окон и переходы без перезагрузки нужно обрабатывать отдельно через hasChanges().

Метод Назначение
getState() Возвращает снимок текущего состояния полей.
markSaved() Принимает текущее состояние за сохранённое.
hasChanges() Возвращает true, если состояние отличается от сохранённого.
protectChanges() Запоминает текущее состояние и включает предупреждение браузера перед уходом.
unprotectChanges() Отключает предупреждение, сохраняя возможность проверки изменений.
allowLeaveOnce() Разрешает следующий уход без предупреждения этой формы.

markSaved() не отправляет данные на сервер. При сохранении через JavaScript вызывайте его только после подтверждённого успешного ответа сервера.

До первого вызова markSaved() или protectChanges() метод hasChanges() возвращает false. Если вернуть исходные значения полей, форма снова считается неизменённой.

getState() возвращает массив записей вида [name, type, ...values], упорядоченных по имени поля. Это снимок для сравнения, а не объект значений из values().

Методы markSaved(), protectChanges(), unprotectChanges() и allowLeaveOnce() возвращают объект формы.

Настройка отслеживания

Параметры передаются вторым аргументом wsForm(formNode, options):

Параметр Назначение
changes-filter Функция, получающая HTML-элемент поля. Возврат false исключает поле из снимка.
changes-state Функция, возвращающая массив дополнительных значений, которые также нужно сравнивать.

Для дополнительных значений удобно использовать строки, числа и логические значения. Объекты сравниваются по ссылке, а не по содержимому.

Получение существующего объекта формы

Чтобы обратиться к уже созданному объекту, импортируйте FormController:

js
import { FormController } from '/core/modules/ws-form/assets/js/initial.js';

const existingForm = FormController.getInstance(document.querySelector('#contact-form'));

Метод возвращает зарегистрированный объект формы или null, если его нет. Повторно вызывать wsForm() для получения существующего объекта не нужно.

Отправка и завершение работы

onSubmit(handler, options) регистрирует обработчик события submit. Он получает объект с event, экземпляром form, объектом values и результатом valid. Опция validate: true запускает проверку. При ошибке по умолчанию отменяется стандартная отправка и фокус переходит к первому ошибочному полю; это поведение можно изменить параметрами preventInvalid: false и focusError: false.

Если форма больше не используется, вызовите destroy() для освобождения обработчиков и наблюдателя за полями.