Валидатор:

Справочник для бэкэндера

$3

Интерфейс предоставляет методы для работы с валидацией форм. Все методы доступны через глобальный объект window.frontApi.form.

Ниже input может быть HTMLInputElement или селектором поля, form может быть HTMLFormElement или селектором формы, а errorBlock может быть HTMLElement или селектором элемента.

Проще говоря вы можете передавать в аргументы либо селектор (id, класс, и т.д), либо сам элемент.

| Метод | Параметры | Возвращает | Описание |
| ----------------------- | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resetFormFieldsErrors | form | void | Сбрасывает все ошибки валидации для всех полей указанной формы. |
| validateForm | form | boolean | Валидирует все поля формы. Возвращает true, если все поля валидны, и false, если есть ошибки. Автоматически показывает ошибки для невалидных полей. |
| validateField | input | boolean | Валидирует одно поле формы. Возвращает валидность поля. |
| resetFormFieldErrors | input | void | Сбрасывает ошибки валидации для указанного поля формы. |
| setFormFieldError | input, message? | void | Вручную добавляет сообщение об ошибке к указанному полю формы. Полезно для кастомных проверок. |
| resetFormError | form, errorBlock? | void | Удаляет общее сообщение об ошибке для всей формы (не привязанное к конкретному полю). |
| setFormError | form, message, errorBlock? | void | Добавляет общее сообщение об ошибке для всей формы (не привязанное к конкретному полю). |
| initAll | --- | void | Инициализация / Переинициализация |
| isValidForm | form | boolean | Проверка валидации формы (возвращает true - если все поля валидны, иначе false) |

Как Бэкенду слушать валидацию формы пример:

``javascript
const form = document.querySelector('.contacts-form__form')
form.addEventListener('submit', e => {
const isValid = window.frontApi.form.isValid(e.target)
console.log('Form send e', isValid)
})
`

Пример вызова каждого метода с комментариями

`javascript
// Инициализация
window.frontApi.form.initAll()

// Валидация всей формы
const isValid = window.frontApi.form.validateForm('#myForm') // возвращает true - если все поля валидны, иначе false

// Проверка валидации всей формы
const myForm = document.querySelector('#myForm')
const isValid_2 = window.frontApi.form.isValidForm(myForm) // возвращает true - если все поля валидны, иначе false

// Валидация отдельного поля
const isFieldValid = window.frontApi.form.validateField('#myForm #email') // возвращает true - если все поля валидны, иначе false

// Ручное добавление ошибки на поле
window.frontApi.form.setFormFieldError('#myForm #password', 'Пароль должен содержать минимум 8 символов')

// Сброс всех ошибок у поля
window.frontApi.form.resetFormFieldErrors('#myForm #email')

// Ручное добавление ошибки на всю форму
window.frontApi.form.setFormError('#myForm', 'Ошибка отправки формы')

// Сброс ошибки формы
window.frontApi.form.resetFormError('#myForm')

// Сброс всех ошибок
window.frontApi.form.resetFormFieldsErrors('#myForm')
`

Справочник для фронтов

$3

Пример верстки для инпута под валидатор (на примере кастомный инпут с плавающим плейсхолдером)

`astro
---
import './input.scss';

interface Props extends astroHTML.JSX.InputHTMLAttributes {
class?: string
'data-validate'?: string
}

const { class: className, ...props } = Astro.props as Props
---

class:list={['input', className]}
data-input-parent
>
class="input__field"
data-input
{...props}
/>
class="input__error"
data-error-container
>

`

Пример верстки для формы под валидатор

`astro
---
import './form.scss'

interface Props extends astroHTML.JSX.FormHTMLAttributes {
class?: string
}

const { class: className, ...props } = Astro.props as Props
---

{...props}
class:list={['form', className]}
>

class="form__error"
data-form-error=""
>

`

Пример использования находится на странице ui

$3

- Валидатор собирает все формы по тегу form, затем проставляет каждой форме novalidate и data-form-init
- Обязательный атрибут у инпута - data-validate='' (значение атрибута определяет тип валидации, все типы представлены в таблице ниже)
- Если не указывать тип в data-validate, то он будет браться из ванильного поля type у input-а
- Если нужно изменить текст ошибки у поля, то следует указать атрибут data-error-message='новый текст ошибки'
- Если для поля телефона требуется маска, то дополнительно добавить атрибут data-mask-phone
- minlength='число' - устанавливает минимальное кол-во символов
- maxlength='число' - устанавливает максимальное кол-во символов

_ВАЖНО! Валидация на самих инпутах на ввод символов начнет работать только после первой попытки отправки формы, до первого submit-а ошибки не будут подсвечиваться, чтобы не мешать пользователю._

Все базовые типы для data-validate

| Тип | Описание |
| ----------------- | --------------------------------------------------------------------- |
| email | Проверяет, является ли значение корректным email-адресом |
| text-only | Проверяет, что значение состоит только из букв (кириллица + латиница) |
| text-cyrillic | Проверяет, что значение состоит только из букв кириллицы |
| text-english | Проверяет, что значение состоит только из букв латиницы |
| tel | Проверяет, что значение является корректным номером телефона |
| number | Проверяет, что значение является числом |
| positive-number | Проверяет, что значение является положительным числом |

Примечания:

В случае с типом tel, дополнительно проверяется длина номера телефона: если длина меньше 11 символов, то валидация считается неуспешной без выполнения метода валидации.

Для типов text-only, text-cyrillic, text-english проверяется, что текст состоит только из букв, соответствующих указанному языку.

$3

Интерфейс предоставляет методы для работы с валидацией форм. Все методы доступны через глобальный объект window.frontApi.form.

Ниже input может быть HTMLInputElement или селектором поля, form может быть HTMLFormElement или селектором формы, а errorBlock может быть HTMLElement или селектором элемента.

| Метод | Параметры | Возвращает | Описание |
| ----------------------- | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resetFormFieldsErrors | form | void | Сбрасывает все ошибки валидации для всех полей указанной формы. |
| validateForm | form | boolean | Валидирует все поля формы. Возвращает true, если все поля валидны, и false, если есть ошибки. Автоматически показывает ошибки для невалидных полей. |
| validateField | input | boolean | Валидирует одно поле формы. Возвращает валидность поля. |
| resetFormFieldErrors | input | void | Сбрасывает ошибки валидации для указанного поля формы. |
| setFormFieldError | input, message? | void | Вручную добавляет сообщение об ошибке к указанному полю формы. Полезно для кастомных проверок. |
| setFormError | form, message, errorBlock? | void | Добавляет общее сообщение об ошибке для всей формы (не привязанное к конкретному полю). |
| resetFormError | form, errorBlock? | void | Удаляет общее сообщение об ошибке для всей формы (не привязанное к конкретному полю). |
| initAll | --- | void | Инициализация / Переинициализация |
| isValidForm | form | boolean | Проверка валидации формы (возвращает true - если все поля валидны, иначе false) |

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

`javascript
// Валидация всей формы
const isValid = window.customValidator.validateForm('#myForm')

// Валидация отдельного поля
const isFieldValid = window.customValidator.validateField('#myForm #email')

// Ручное добавление ошибки
window.customValidator.setFormFieldError('#myForm #password', 'Пароль должен содержать минимум 8 символов')

window.customValidator.setFormError('#myForm', 'Ошибка отправки формы')

// Сброс ошибок
window.customValidator.resetFormFieldsErrors('#myForm')
`

Более подробно пример работы можно посмотреть на странице UI в нашем сборщике.

$3

По умолчанию есть предопределённые сообщения об ошибках для различных типов валидации (email, телефон, текст и т.д.) на 2 языках (русский, английский).

Вы можете полностью или частично заменить стандартные сообщения, передав объект конфигурации при инициализации валидации.
Ключ для валидации можете брать из таблицы выше. Значение - строка

Также вы можете переопределить базовый класс невалидных полей и контейнера ошибки:

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

`javascript
import { validatorInit } from '@front-cmdt/validator'

validatorInit({
invalidClass: 'bg-red-500',
errorMessages: {
ru: {
tel: 'Мой кастомный текст для ошибок'
}
}
})
`

Полный пример конфигурации:

`javascript
import { validatorInit } from '@front-cmdt/validator'

const validatorConfig = {
// Класс для контейнера ошибок (по умолчанию 'input__error')
errorContainerClass: 'test__error-class',
// Класс для невалидных полей (применяется к элементу с data-input-parent)
invalidClass: 'test-invalidClass',

// Переопределение сообщений об ошибках
errorMessages: {
// Язык определяется из атрибута
ru: {
required: 'Это поле не может быть пустым',
minlength: 'Минимум {{minlength}} символов',
email: 'Введите корректный email',
tel: 'Введите корректный номер телефона',
number: 'Введите корректное число',
'text-only': 'Введите корректное имя',
'text-cyrillic': 'Только кириллица',
'text-english': 'Только латиница',
'positive-number': 'Введите положительное число',
checkbox: 'Это обязательное поле',
radio: 'Выберите один из вариантов',
select: 'Выберите значение из списка'
},
en: {
required: 'This field cannot be empty',
minlength: 'Minimum {{minlength}} characters',
email: 'Enter a valid email address',
tel: 'Enter a valid phone number',
number: 'Enter a valid number',
'text-only': 'Enter a valid name',
'text-cyrillic': 'Only Cyrillic characters are allowed',
'text-english': 'Only English characters are allowed',
'positive-number': 'Enter a positive number',
checkbox: 'Please check the box',
radio: 'Please select an option',
select: 'Please select a value'
}
}
}

validatorInit(validatorConfig)
`

$3

1. Контейнер ошибок существует внутри миксина

Если миксин включает в себя контейнер для отображения ошибок, этот контейнер просто должен иметь атрибут data-error-container.

2. Отсутствие контейнера ошибки в миксине

В случае, если контейнера ошибки не существует в миксине ИЛИ нам надо вывести ошибку в другом месте, то ТРЕБУЕТСЯ:

а) На элемент input навесить атрибут data-error-container="пример-id"
б) На странице расположить элемент с таким же data-error-container (чтобы JS мог находить его для вывода ошибок).

Для принудительного появления ошибки использовать:

`javascript
window.frontApi.form.setFormFieldError(inputSelector || inputElement, message)
`

Для принудительного удаления/скрытия ошибки использовать:

`javascript
window.frontApi.form.resetFormFieldErrors(inputSelector || inputElement)
`

Для принудительного удаления/скрытия ВСЕХ ошибок формы использовать:

`javascript
window.frontApi.form.resetFormFieldsErrors(formSelector || formElement)
`

Общая ошибка формы

В случаях, когда необходимо отобразить общую ошибку формы (например, при валидации на стороне сервера или комплексной проверке данных), требуется добавить в верстку формы специальный контейнер с атрибутом data-form-error=''

Для появления общей ошибки использовать:

`javascript
window.frontApi.form.setFormError(formSelector || formElement, message)
``