@front-cmdt/validator

v0.0.3

Published

9 days ago

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

Downloads

194

0High
0Medium
0Low

knyazew

validator form validation

Валидатор:

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

API

Интерфейс предоставляет методы для работы с валидацией форм. Все методы доступны через глобальный объект 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) |

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

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)
})

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

// Инициализация
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')

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

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

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

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

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

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

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

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

---
import './form.scss'

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

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

<form
  {...props}
  class:list={['form', className]}
>
  <slot />
  <div
    class="form__error"
    data-form-error=""
  >
  </div>
</form>

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

Основные сведения

Валидатор собирает все формы по тегу 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 проверяется, что текст состоит только из букв, соответствующих указанному языку.

API

| Метод | Параметры | Возвращает | Описание | | ----------------------- | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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) |

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

// Валидация всей формы
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 в нашем сборщике.

Конфигурация

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

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

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

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

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

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

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

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

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

  // Переопределение сообщений об ошибках
  errorMessages: {
    // Язык определяется из атрибута <html lang='ru'></html>
    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)

Обработка ошибок

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme