WS Form

Подключение

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

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

<form id="contact-form">
    <label>
        Имя
        <input type="text" name="name">
    </label>
    <button type="submit">Отправить</button>
</form>

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. Каждый метод принимает name существующего поля и необязательный объект настроек, а возвращает объект формы. Шаблон не создаёт HTML-поле: сначала добавьте его в <form> с нужным атрибутом name.

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

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: 64
});

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

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

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 цифр.

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

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

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

Дата

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.

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

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

form.setValue('name', 'Анна');

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

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

Группы полей

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

<form id="preferences-form">
    <label><input type="checkbox" name="topics[]" value="news"> Новости</label>
    <label><input type="checkbox" name="topics[]" value="updates"> Обновления</label>
</form>

const preferences = wsForm(document.querySelector('#preferences-form'));

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

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

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

form.required('name', 'Укажите имя');
form.minLength('name', 2, 'Имя слишком короткое');

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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