Validate

Очень простой плагин валидации форм для AlpineJS. Этот плагин, как и сам AlpineJS, предназначен для использования по мере необходимости. Этот плагин не навязывает вам какую-либо структуру данных или функциональности формы. Его можно использовать как с x-model, так и без нее.

Директива x-validate позволяет выполнять простую проверку и отображать ошибки. Он также записывает все данные формы в реактивную форму FormData. Магическая функция $validate предоставляет доступ к функциям валидации, формам данных и простой проверке валидности отправки.

Установка

Вы можете использовать этот плагин, включив его из тега <script> или установив с помощью менеджера пакетов.

Через CDN

Вы можете подключить CDN-сборку этого плагина с помощью тега <script>, только подключать нужно ДО основного JS-файла Alpine.

jsDelivr CDN
unpkg CDN

<!-- Validate Plugin -->
<script defer src="https://cdn.jsdelivr.net/npm/@colinaut/alpinejs-plugin-simple-validate@latest/dist/alpine.validate.min.js"></script>

<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

<!-- Validate Plugin -->
<script defer src="https://unpkg.com/@colinaut/alpinejs-plugin-simple-validate@latest/dist/alpine.validate.min.js"></script>

<!-- Alpine Core -->
<script defer src="https://unpkg.com/alpinejs@3/dist/cdn.min.js"></script>

Через менеджер пакетов

Вы можете установить Validate для использования внутри вашей сборки следующим образом:

npm i @colinaut/alpinejs-plugin-simple-validate

yarn add @colinaut/alpinejs-plugin-simple-validate

pnpm add @colinaut/alpinejs-plugin-simple-validate

Затем инициализируйте его в своей сборке:

import Alpine from 'alpinejs';
import validate from '@colinaut/alpinejs-plugin-simple-validate';

Alpine.plugin(validate);
Alpine.start();

Использование

Добавьте атрибуты x-data и x-validate в свой элемент <form> (вам не нужны переменные в x-data; его просто нужно инициировать как компонент Alpine). Это автоматически:

Собирает все данные в реактивный массив formData[form], который обновляется при потере фокуса или клике (в зависимости от типа поля).
Проверяет валидность при потере фокуса с помощью базовой проверки checkValidity() браузера, учитывая атрибуты required и типы полей ввода.
Использует встроенную улучшенную проверку регулярных выражений для обязательных полей, полей электронной почты, телефона и URL-адреса, так как возможности браузеров ограничены.
Автоматически добавляет скрытый элемент span.error-msg с сообщением об ошибке рядом с полем.
- Вам придётся стилизовать всё самостоятельно (см. пример ниже).
Когда проверка валидности не проходит, это…
- Добавляет атрибуты aria-invalid="true" и aria-errormessage к элементу поля.
- Отображает сообщение об ошибке, удаляя атрибут hidden.
- Добавляет атрибут data-error="{сообщение об ошибке}" на родительском элементе поля для дополнительной стилизации, которая может вам понадобиться (ищет ближайший родительский элемент с классом field-parent или, если это не удается, использует .parentNode).
- После потери фокуса вызывает событие invalid и добавляет слушатель события input для проверки валидности, а также событие blur.
Если событие valid срабатывает, всё вышеперечисленное отменяется.
Используйте :disabled="$validate.isComplete('formId')" для отключения кнопки отправки и/или используйте @submit="$validate.submit", чтобы автоматически проверить валидность всех полей перед отправкой.

Дополнительная валидация

Используйте директиву x-validate вместе с модификаторами (например, x-validate.wholenumber) непосредственно на полях формы, чтобы добавить дополнительную валидацию.
Для написания пользовательского сообщения об ошибке есть несколько способов:
- Добавьте атрибут data-error-msg="пользовательское сообщение об ошибке" к самому полю.
- Добавьте соседний (на том же уровне) элемент с классом error-msg и напишите свое собственное сообщение об ошибке. Плагин ищет все следующие соседние элементы и автоматически добавляет соответствующий атрибут aria-errormessage со связанными идентификаторами тегов. Это также полезно, если вы хотите добавить описательный текст или другой элемент перед сообщением об ошибке, или если вы хотите применить специальное оформление к определённому сообщению об ошибке.
- Добавьте элемент с правильным идентификатором в любом месте на странице (идентификатор — error-msg-${id соответствующего поля}), и он будет использовать его.
Используйте x-validate.group для групп флажков или радиокнопок, чтобы проверить, что хотя бы одно из полей выбрано.
Добавьте конкретное условие для поля, например, x-validate='$el.value === 'bunny' (см. Использование выражений для проверки ниже).
Используйте $validate.isComplete(el), чтобы определить, завершены ли форма, группы <fieldset> или какое-либо поле.
Если вы хотите, чтобы только несколько полей проходили валидацию, вы можете опустить x-validate для <form> и добавить его непосредственно на поля. При этом всё равно требуется наличие атрибута x-data у элемента <form>.
В папке examples в репозитории Git показаны некоторые возможности этого плагина.

Директива `x-validate`

Директивы элемента формы и модификаторы пользовательского интерфейса

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

Вот некоторые из них:

x-validate: Запускает валидацию и захватывает данные формы для всей формы.
x-validate.bluronly: Изменяет стандартное поведение, чтобы не использовать слушатель события input для заполняемых полей формы.
x-validate.input: Устанавливает поля на использование как слушателя события blur, так и input для всех проверок валидации.
x-validate.refocus: Принудительно устанавливает фокус на элементе формы, если он недопустим.
x-validate.use-browser: Использует встроенную валидацию браузера вместе с x-validate.
x-validate.validate-on-submit: Автоматически запускает валидацию при отправке формы.

Директивы элемента поля

Эти модификаторы позволяют настраивать поведение валидации в зависимости от ваших потребностей. Например, вы можете использовать x-validate.input, чтобы проверять валидность поля как при потере фокуса, так и при вводе данных.

Используются на элементах <input>, <select>, <textarea>:

Используемый синтаксис	Описание
`x-validate`	просто собирает данные. Полезно, если не установлено на элементе `<form>`. Также полезно в паре с выражением для конкретной проверки поля, например, `x-validate='$el.value === 'bunny'`. Обратите внимание, что во многих случаях обычного атрибута `pattern` может быть достаточно.
`x-validate.required`	заменяет атрибут `required`. ^*
`x-validate.tel`	работает так же, как `type='tel'`, используя улучшенное регулярное выражение. ^*
`x-validate.email`	работает так же, как `type='email'`, используя улучшенное регулярное выражение.
`x-validate.website`	считается действительным, если домен сайта указан с или без `http://` или `https://`.
`x-validate.url`	работает так же, как `type='url'`, используя улучшенное регулярное выражение. ^*
`x-validate.number`	считается действительным, если это число (положительное или отрицательное; целое или десятичное).
`x-validate.integer`	считается действительным, если это целое число (положительное или отрицательное).
`x-validate.wholenumber`	считается действительным, если это целое число (положительное).
`x-validate.date`	по умолчанию используется формат `yyyy-mm-dd`, так как это то, как поле ввода `type='date'` сохраняет дату.
`x-validate.date.mmddyyyy`	формат `mm-dd-yyyy`.
`x-validate.date.ddmmyyyy`	формат `dd-mm-yyyy`.
`x-validate.date.yyyymmdd`	формат `yyyy-mm-dd`.

* Это позволит вам использовать x-validate.required вместо атрибута required или x-validate.tel на type='text' вместо type='tel' ↩

Использование выражений для проверки

Вы можете добавить конкретное условие для поля, например, x-validate='$el.value === 'bunny'. Это можно совместить с другими проверками. Например, x-validate.website="$el.includes('bunny')" для веб-сайтов, содержащих слово bunny в названии. Обратите внимание, что во многих случаях обычного атрибута pattern может быть достаточно.

Группы флажков и радиокнопок

Флажки и радиокнопки, которые имеют одинаковый атрибут name, обновляют один и тот же объект данных formData. Радиокнопки обновляют значение с учётом выбранной кнопки. Флажки сохраняются как строка со значениями, разделёнными запятыми, а также как массив.

Можно проверить, что хотя бы один элемент выбран, добавив x-validate.group к каждому флажку или радиокнопке в именованной группе. Если вы хотите, чтобы пользователь мог выбрать несколько флажков, используйте выражение с указанием необходимого количества выбранных вариантов x-validate.group="2".

Магические функции

$formData возвращает объект formData для текущей формы
$validate представляет собой объект с набором функций (см. функции ниже)

Функции валидации

Можно добавить любую конкретную проверку, такую как email или tel. Основное отличие между магической функцией и директивой заключается в том, что required предполагается.

И $validate.email('') и $validate.email('hi') возвращают false
$validate.email('hi@hello.com') возвращает true
Если val — пустая строка или действительный адрес электронной почты, то выражение val === '' || $validate.email(val) также возвращает true.
При проверке даты можно использовать форматы, такие как $validate.date.mmddyyyy(str).

Другие функции

Директива x-validate, когда используется на элементе <form>, добавляет каждое поле в реактивный массив formData[formId]. Если она используется только на отдельных полях, x-validate добавляет только эти поля в массив formData[formId].

Используемый синтаксис	Описание
`@submit="$validate.submit"`	применяется к элементу `<form>`. Она выполняет проверку текущей формы; если проверка не проходит, отображаются ошибки, и событие отправки формы предотвращается.
`$validate.isComplete(el)`	возвращает `true` или `false` для проверки валидности формы, набора полей или отдельных полей. ^*
`$validate.data(el)`	возвращает массив полей формы или набора полей, или отдельный объект данных поля. ^*
`$validate.formData(form)`	возвращает сырой объект `formData` с ключевыми именами полей. ^*
`$validate.value(el, value)`	возвращает простой объект с ключами и значениями полей для форм и наборов полей, или просто сырое значение для отдельных полей. Аргумент `value` является необязательным и применяется только для полей; если он предоставлен, он обновит значение поля и обновит `formData` для `x-validate`. ^*

* Аргумент el может быть переменной $refs или строкой с именем/идентификатором для получения данных из формы, набора полей или отдельных полей. ↩

Дополнительные функции

Они предоставляют доступ к некоторым функциям бэкенда — используйте их на свой страх и риск.

$validate.updateData(field, data, triggerErrorMsg) позволяет вам напрямую добавлять или обновлять массив formData для определённого поля. Если вызвать этот метод только с именем поля, он получит новое значение для этого поля. Это полезно, если вы динамически обновляете поле с помощью других функций JavaScript.
$validate.toggleError(field, valid) позволяет вам переключать сообщение об ошибке для любого поля.

Пример

<form id="form" x-data x-validate @submit="$validate.submit">
    <p><em>* обязательное поле</em></p>
    <div>
        <label for="name">Ваше имя *</label>
        <input type="text" id="name" name="name" required data-error-msg="Имя обязательно" />
    </div>
    <div>
        <label for="email">Ваш имейл *</label>
        <input type="email" id="email" name="email" required data-error-msg="Имейл обязателен" />
    </div>
    <div>
        <label for="wholenumber">Целое число</label>
        <input type="wholenumber" id="wholenumber" name="wholenumber" x-validate.wholenumber data-error-msg="Укажите положительное целое число" />
    </div>
    <div id="animals">
        <h4>Любимые животные *</h4>
        <div class="flex items-baseline gap-4" data-error-msg="Вы должны выбрать хотя бы одно животное">
          <label><input type="checkbox" x-validate.group name="animals" id="cat" value="cat">Кошка</label>
          <label><input type="checkbox" x-validate.group name="animals" id="dog" value="dog">Собака</label>
          <label><input type="checkbox" x-validate.group name="animals" id="bunny" value="bunny">Кролик</label>
        </div>
    </div>
    <div>
        <input type="submit" value="Отправить">
    </div>
</form>
<style>
    .error-msg {
        color: red;
    }
</style>