Checkbox и CheckboxGroup

Компонент Checkbox в библиотеке Naive UI представляет собой стандартный флажок для выбора одного значения из двух состояний: включено или выключено. Его ключевые свойства позволяют контролировать как визуальное отображение, так и поведение:

  • v-model:checked — двусторонняя привязка состояния чекбокса. При изменении пользователем автоматически обновляет значение в переменной.
  • value — уникальное значение для чекбокса, особенно важно при использовании в составе CheckboxGroup.
  • disabled — отключает чекбокс, делая его недоступным для взаимодействия.
  • indeterminate — промежуточное состояние, обычно используется для отображения частично выбранных групп элементов.
  • size — определяет размер чекбокса: small, medium, large.

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

<template>
  <n-checkbox v-model:checked="isChecked">Выбрать опцию</n-checkbox>
</template>

<script setup>
import { ref } from 'vue'
const isChecked = ref(false)
</script>

Работа с состоянием

Состояние Checkbox можно контролировать через реактивные переменные. Это позволяет программно менять флажки или синхронизировать их с данными:

<template>
  <n-checkbox
    v-model:checked="isChecked"
    :indeterminate="isIndeterminate"
  >
    Частично выбран
  </n-checkbox>
  <button @click="toggleState">Переключить</button>
</template>

<script setup>
import { ref } from 'vue'
const isChecked = ref(false)
const isIndeterminate = ref(true)

function toggleState() {
  isChecked.value = !isChecked.value
  isIndeterminate.value = false
}
</script>

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

CheckboxGroup: организация множества чекбоксов

CheckboxGroup позволяет объединять несколько чекбоксов в логическую группу, обеспечивая управление массивом выбранных значений. Основные свойства:

  • v-model:value — массив выбранных значений.
  • options — список доступных опций, каждая из которых может быть объектом { label, value, disabled } или строкой.
  • disabled — глобальное отключение всех чекбоксов в группе.
  • size — размер всех элементов группы.

Пример создания группы:

<template>
  <n-checkbox-group v-model:value="selectedOptions" :options="options" />
</template>

<script setup>
import { ref } from 'vue'

const selectedOptions = ref(['apple'])
const options = [
  { label: 'Яблоко', value: 'apple' },
  { label: 'Банан', value: 'banana' },
  { label: 'Вишня', value: 'cherry', disabled: true }
]
</script>

Здесь selectedOptions будет содержать массив выбранных значений, автоматически обновляющийся при изменении состояния любого чекбокса.

Свойства и события CheckboxGroup

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

  • @update:value — событие изменения выбранных значений, аналог двусторонней привязки.
  • disabled — блокирует взаимодействие со всеми чекбоксами в группе.
  • max и min — ограничивают количество выбираемых элементов. Например, можно позволить выбрать не более двух опций одновременно.
  • size — глобальный размер для всех дочерних чекбоксов.

Пример использования ограничения выбора:

<template>
  <n-checkbox-group
    v-model:value="selectedOptions"
    :options="options"
    :max="2"
  />
</template>

<script setup>
import { ref } from 'vue'

const selectedOptions = ref([])
const options = ['Опция 1', 'Опция 2', 'Опция 3', 'Опция 4']
</script>

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

Стилизация и размер

Оба компонента поддерживают настройку размера и кастомизации через CSS переменные. Основные переменные:

  • --n-checkbox-size — размер чекбокса.
  • --n-checkbox-border-radius — радиус скругления.
  • --n-checkbox-border-color — цвет рамки в нормальном состоянии.
  • --n-checkbox-checked-color — цвет активного состояния.

Пример глобальной настройки:

.n-checkbox {
  --n-checkbox-size: 24px;
  --n-checkbox-border-radius: 4px;
  --n-checkbox-checked-color: #4caf50;
}

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

Взаимодействие Checkbox и CheckboxGroup

Чекбоксы в группе управляются единым массивом значений, что упрощает логику управления множественными выборами. Важно учитывать, что отдельные чекбоксы могут иметь свои свойства disabled или indeterminate, которые будут корректно отображаться даже в составе группы.

Практические рекомендации

  • Для простых флажков использовать отдельный Checkbox.
  • Для множества связанных опций использовать CheckboxGroup с массивом значений.
  • Использовать indeterminate для промежуточных состояний, особенно в иерархических списках.
  • Применять max и min в группах, чтобы ограничивать количество выбираемых элементов.
  • Настраивать внешний вид через CSS-переменные для соответствия общему стилю приложения.

Гибкость Naive UI позволяет создавать как минималистичные интерфейсы с отдельными флажками, так и сложные формы с множественными выборками и ограничениями, обеспечивая удобную интеграцию с реактивной моделью Vue.

Оглавление