useForm
Создаёт состояние формы по схеме tinyval.
Сигнатура
ts
function useForm<S extends Schema, V extends object>(schema: S, options: FormOptions<V>): Form<V, Infer<S>>Опции
| Опция | Тип | По умолчанию | Описание |
|---|---|---|---|
initial | V | — | Начальные значения полей. Обязательна. Из неё берётся тип form.values |
mode | 'blur' | 'input' | 'submit' | 'blur' | Когда показывать ошибки поля — см. Ошибки |
debounce | number | 300 | Задержка перед асинхронными проверками при вводе, мс |
focusOnError | boolean | true | При неудачной отправке поставить фокус на первое поле с ошибкой (по атрибуту name) |
extractErrors | (error) => errors | ответ 422 | Как достать ошибки полей из исключения в handleSubmit. По умолчанию понимает 422 от Laravel через axios и ofetch и ValidationError из tinyval |
id | string | useId() | Основа для id полей. По умолчанию useId() во Vue 3.5+ — совпадает при SSR |
messages, labels, maxDepth | Как у validate: язык и названия полей для этой формы |
Что возвращает
Реактивный объект. Используйте его целиком (form.errors.email), не деструктурируйте — иначе пропадёт реактивность.
Форма передаётся вложенным компонентам: в них useField('email'), useFieldArray('items'), useFormContext() и компоненты TvField работают без явной передачи формы.
| Поле | Описание |
|---|---|
values | Значения полей для v-model |
errors | Ошибки, которые пора показать (с учётом mode), и ошибки сервера: { email: '...', 'items.0.title': '...' } |
allErrors | Все текущие ошибки, даже ещё не показанные |
valid | Форма валидна и нет ошибок сервера |
dirty | Значения отличаются от начальных |
changes | Только изменённые поля — например, для PATCH, см. Редактирование |
touched | Поля, с которых пользователь уходил: { email: true } |
validating | Идёт асинхронная проверка |
submitting | Идёт отправка (handleSubmit) |
submitted | Форму пытались отправить — после этого видны все ошибки |
submitCount | Сколько раз пытались отправить |
submitSucceeded | Последняя отправка прошла успешно |
data | Проверенные данные (после trim, coerce…) или undefined |
| Метод | Описание |
|---|---|
touch(path) | Отметить поле как «тронутое» — обычно на @blur. touch('items') отмечает все вложенные поля |
handleSubmit(onValid, onInvalid?) | Обработчик для @submit: отменяет отправку страницы, проверяет форму и вызывает onValid(data) с проверенными данными или onInvalid(errors) |
validate(paths?) | Проверить форму и показать все ошибки. С путями — только эти поля, см. Пошаговые формы. Возвращает Promise<boolean> |
isDirty(path) | Изменилось ли поле |
setValue(path, value), setValues(values) | Задать значение поля / нескольких полей |
setErrors(errors) | Показать ошибки сервера: { email: '...' } или формат Laravel { email: ['...'] } |
setFieldError(path, message?) | Ошибка одного поля; исчезнет при его изменении. Без текста — убрать |
clearErrors(path?) | Скрыть ошибки поля или всей формы до следующего ухода с поля / отправки |
setTouched(path, value?) | Отметить поле «тронутым» или снять отметку |
resetField(path, value?) | Вернуть поле к начальному значению; с value — задать новое начальное |
validateField(path) | Проверить одно поле и показать его ошибку |
reset(values?) | Вернуть начальные (или новые) значения и очистить ошибки, touched, submitted. Новые значения становятся точкой отсчёта для dirty |
bind(path) | modelValue, onUpdate:modelValue и onBlur — для компонентов UI-библиотек |