FormItem и Layout

В библиотеке Naive UI компоненты FormItem и Form обеспечивают мощный и гибкий механизм построения форм с продуманной валидацией, управлением состоянием и удобным взаимодействием с пользователем. Они позволяют создавать формы с адаптивным расположением полей, поддержкой различных типов ввода и полной интеграцией с layout-системой библиотеки.

FormItem: структура и свойства

Компонент FormItem представляет отдельное поле формы. Он отвечает за отображение метки, управления состоянием ошибки и связанного ввода.

Основные свойства:

  • label – текстовая метка поля. Может быть строкой или функцией для рендеринга кастомного содержимого.
  • path – путь к полю в объекте модели формы. Позволяет связывать поле с данными через v-model.
  • rule / rules – объект или массив правил валидации. Поддерживаются стандартные типы проверки: required, minLength, maxLength, pattern, а также кастомные функции валидации.
  • showFeedback – управление отображением сообщений об ошибках.
  • labelWidth – ширина метки. Позволяет создавать аккуратные формы с выравниванием полей по колонкам.
  • pathSeparator – символ, используемый для разделения вложенных свойств объекта модели (по умолчанию .).

Пример привязки данных к полю:

<n-form :model="formData">
  <n-form-item label="Имя" path="name" :rules="[{ required: true, message: 'Введите имя' }]">
    <n-input v-model:value="formData.name" placeholder="Введите имя" />
  </n-form-item>
</n-form>

<script>
export default {
  data() {
    return {
      formData: {
        name: ''
      }
    }
  }
}
</script>

Здесь FormItem автоматически отслеживает изменения значения в formData.name и управляет отображением ошибок в соответствии с заданным правилом.

Работа с правилами валидации

Naive UI поддерживает как синхронные, так и асинхронные правила. Каждое правило может содержать:

  • required – обязательность поля.
  • type – тип значения (string, number, email, url и др.).
  • min / max – ограничения по длине или числовым значениям.
  • pattern – регулярное выражение для проверки.
  • validator – функция для кастомной проверки.

Пример кастомной функции валидации:

<n-form-item label="Пароль" path="password" :rules="[
  { required: true, message: 'Введите пароль' },
  { validator: validatePassword }
]">
  <n-input type="password" v-model:value="formData.password" />
</n-form-item>

<script>
function validatePassword(rule, value) {
  if (!/[A-Z]/.test(value)) {
    return new Error('Пароль должен содержать хотя бы одну заглавную букву')
  }
  return true
}
</script>

Функция может возвращать true при успешной проверке или объект ошибки, который FormItem автоматически отображает.

Layout для форм

Naive UI предоставляет гибкие возможности для организации расположения FormItem через свойства формы и контейнеров.

Горизонтальные и вертикальные формы

  • labelPlacement – определяет, где будет располагаться метка: top или left.
  • labelWidth – задает фиксированную ширину метки, полезно для горизонтальных форм.
  • inline – делает форму однострочной, позволяя размещать несколько полей в одной строке.
<n-form :model="formData" label-placement="left" label-width="120">
  <n-form-item label="Email" path="email">
    <n-input v-model:value="formData.email" />
  </n-form-item>
  <n-form-item label="Телефон" path="phone">
    <n-input v-model:value="formData.phone" />
  </n-form-item>
</n-form>

В этом примере метки выровнены слева, а поля занимают оставшееся пространство.

Сетка (Grid Layout)

Для сложных форм удобно использовать n-grid и n-grid-item, чтобы управлять расположением полей в несколько колонок.

<n-grid cols="2" x-gap="20px" y-gap="20px">
  <n-grid-item>
    <n-form-item label="Имя" path="name">
      <n-input v-model:value="formData.name" />
    </n-form-item>
  </n-grid-item>
  <n-grid-item>
    <n-form-item label="Фамилия" path="surname">
      <n-input v-model:value="formData.surname" />
    </n-form-item>
  </n-grid-item>
</n-grid>
  • cols – количество колонок.
  • x-gap и y-gap – расстояние между колонками и строками.
  • n-grid-item автоматически распределяет поля по сетке, сохраняя выравнивание и адаптивность.

Комбинирование FormItem с Layout

Использование FormItem в сочетании с n-grid или кастомными контейнерами позволяет создавать динамические и отзывчивые формы. Например, комбинируя поля разных типов:

  • Текстовые поля (n-input)
  • Выбор из списка (n-select)
  • Чекбоксы и радиокнопки (n-checkbox, n-radio-group)
  • Поля с датой и временем (n-date-picker)

Каждое поле внутри FormItem автоматически наследует правила валидации, отображение ошибок и управление состоянием формы.

Работа с вложенными объектами

FormItem поддерживает привязку к глубоко вложенным объектам через path:

<n-form-item label="Город" path="address.city">
  <n-input v-model:value="formData.address.city" />
</n-form-item>

Это позволяет легко управлять сложными структурами данных без дополнительного кода для синхронизации значений.

Управление формой через API

Форма предоставляет методы для программного контроля:

  • validate() – проверка всех полей.
  • reset() – сброс значений к исходным.
  • clearValidate() – очистка сообщений об ошибках.
  • validateField(path) – проверка конкретного поля.

Пример:

const formRef = ref(null)

function submitForm() {
  formRef.value.validate().then(() => {
    console.log('Форма валидна', formData)
  }).catch(() => {
    console.log('Есть ошибки в форме')
  })
}

Ссылка на форму (ref) позволяет вызывать эти методы из родительских компонентов.

Адаптивные формы

Комбинация FormItem с n-grid и labelPlacement позволяет создавать формы, которые автоматически подстраиваются под ширину экрана. Это особенно полезно для мобильных интерфейсов и панелей администрирования, где важно сохранить читабельность и компактность элементов.

Использование Naive UI обеспечивает полное управление внешним видом и поведением формы при минимальном количестве кода, сохраняя при этом мощные возможности валидации и удобного расположения элементов.

Оглавление