TreeSelect

TreeSelect — компонент библиотеки Naive UI, предназначенный для выбора элементов из иерархической структуры данных. Он объединяет функциональность выпадающего списка и древовидного представления. Такой интерфейс используется в ситуациях, когда элементы имеют родительско-дочерние связи и требуется наглядное отображение вложенности.

Типичные сценарии применения:

  • выбор категории товара из иерархии каталога;
  • выбор подразделения в структуре компании;
  • настройка прав доступа;
  • выбор географических регионов;
  • работа с древовидными файловыми структурами.

Компонент интегрирован в экосистему Vue.js и полностью поддерживает реактивную модель данных.

Базовое использование

Компонент n-tree-select используется аналогично обычному Select, но принимает древовидную структуру данных.

Пример

<template>
  <n-tree-select
    v-model:value="value"
    :options="options"
    placeholder="Выберите элемент"
  />
</template>

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

const value = ref(null)

const options = [
  {
    label: 'Frontend',
    key: 'frontend',
    children: [
      { label: 'Vue', key: 'vue' },
      { label: 'React', key: 'react' }
    ]
  },
  {
    label: 'Backend',
    key: 'backend',
    children: [
      { label: 'Node.js', key: 'node' },
      { label: 'Python', key: 'python' }
    ]
  }
]
</script>

Основные элементы структуры

Каждый узел дерева содержит:

Поле Назначение
label отображаемое название
key уникальный идентификатор
children массив дочерних элементов

Структура данных TreeOption

Тип данных, используемый компонентом, называется TreeOption.

interface TreeOption {
  label?: string
  key: string | number
  children?: TreeOption[]
  disabled?: boolean
}

Дополнительные свойства:

Свойство Описание
disabled запрещает выбор элемента
isLeaf указывает, что элемент является листом
prefix пользовательский контент перед текстом
suffix пользовательский контент после текста

Поддержка множественного выбора

Компонент поддерживает множественный выбор элементов через свойство multiple.

<n-tree-select
  v-model:value="values"
  :options="options"
  multiple
/>
const values = ref([])

В этом режиме:

  • возвращается массив ключей
  • появляется возможность выбирать несколько узлов дерева
  • визуально отображаются выбранные элементы в поле ввода

Отображение выбранных значений

Поведение выбранных элементов можно настраивать.

Свойство show-path

Показывает полный путь к элементу:

<n-tree-select
  v-model:value="value"
  :options="options"
  show-path
/>

Пример отображения:

Frontend / Vue

Это полезно, когда одинаковые названия встречаются в разных ветках дерева.

Каскадный выбор

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

Свойство:

cascade

Пример

<n-tree-select
  v-model:value="values"
  :options="options"
  multiple
  cascade
/>

Особенности:

  • выбор родителя выбирает все дочерние элементы
  • снятие выбора удаляет выбор из всей ветки
  • состояние может быть частично выбранным

Управление состоянием раскрытия

TreeSelect позволяет управлять раскрытием узлов дерева.

expanded-keys

<n-tree-select
  v-model:value="value"
  :options="options"
  :expanded-keys="expandedKeys"
/>
const expandedKeys = ref(['frontend'])

Это свойство задаёт список раскрытых элементов.

Поиск внутри дерева

Компонент поддерживает встроенную функцию поиска по узлам дерева.

Активация поиска

<n-tree-select
  v-model:value="value"
  :options="options"
  filterable
/>

Появляется поле ввода, позволяющее:

  • фильтровать элементы
  • автоматически раскрывать подходящие ветки

Пользовательская логика фильтрации

Можно определить собственную функцию поиска.

<n-tree-select
  v-model:value="value"
  :options="options"
  filterable
  :filter="filter"
/>
const filter = (pattern, option) => {
  return option.label.toLowerCase().includes(pattern.toLowerCase())
}

Параметры функции:

Параметр Значение
pattern текст поиска
option текущий узел

Ленивая загрузка узлов

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

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

Пример

<n-tree-select
  v-model:value="value"
  :options="options"
  :on-load="load"
/>
const load = async (node) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      node.children = [
        { label: 'Dynamic child 1', key: 'child1' },
        { label: 'Dynamic child 2', key: 'child2' }
      ]
      resolve()
    }, 1000)
  })
}

Такой подход уменьшает:

  • время первоначальной загрузки
  • объём данных в памяти
  • нагрузку на сервер

Отображение чекбоксов

TreeSelect поддерживает выбор с чекбоксами, что особенно полезно при множественном выборе.

<n-tree-select
  v-model:value="values"
  :options="options"
  multiple
  checkable
/>

Особенности:

  • рядом с элементами появляются чекбоксы
  • поддерживается частичное состояние выбора
  • работает совместно с cascade

Управление стратегией выбора

Стратегия выбора настраивается через checked-strategy.

Возможные варианты:

Значение Поведение
all возвращаются все выбранные узлы
parent возвращаются только родительские узлы
child возвращаются только листовые элементы

Пример

<n-tree-select
  v-model:value="values"
  :options="options"
  multiple
  checkable
  checked-strategy="child"
/>

Это часто используется в системах управления правами доступа.

Отключение узлов

Некоторые элементы дерева можно сделать недоступными.

{
  label: 'Backend',
  key: 'backend',
  disabled: true
}

Такой элемент:

  • отображается в списке
  • не может быть выбран

Пользовательский рендер узлов

TreeSelect поддерживает кастомизацию отображения узлов.

Свойство:

render-label

Пример

<n-tree-select
  v-model:value="value"
  :options="options"
  :render-label="renderLabel"
/>
const renderLabel = ({ option }) => {
  return h(
    'span',
    { style: 'color: blue' },
    option.label
  )
}

Возможности кастомизации:

  • добавление иконок
  • изменение цвета
  • отображение дополнительной информации
  • интеграция пользовательских компонентов

Управление размером компонента

TreeSelect поддерживает несколько размеров.

size="small"
size="medium"
size="large"

Пример:

<n-tree-select
  size="large"
  :options="options"
/>

Плейсхолдер

Текст, отображаемый при отсутствии выбранного значения.

placeholder="Выберите категорию"

Очистка выбранного значения

Для удобства пользователя можно добавить кнопку очистки.

clearable

Пример:

<n-tree-select
  v-model:value="value"
  :options="options"
  clearable
/>

Управление шириной выпадающего меню

По умолчанию ширина меню совпадает с шириной поля ввода.

Изменение поведения:

:consistent-menu-width="false"

Теперь ширина меню определяется содержимым.

События компонента

TreeSelect генерирует события, позволяющие отслеживать изменения.

update:value

Вызывается при изменении выбранного значения.

<n-tree-select
  :options="options"
  @update:value="handleChange"
/>
const handleChange = (value) => {
  console.log(value)
}

update:expanded-keys

Срабатывает при раскрытии или закрытии узлов.

@n-tree-select
@update:expanded-keys="handleExpand"

load

Используется для ленивой загрузки узлов.

Производительность

При работе с большими деревьями важно учитывать оптимизацию:

Рекомендации

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

Типизация TypeScript

TreeSelect полностью типизирован.

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

import type { TreeOption } from 'naive-ui'

const options: TreeOption[] = [
  {
    label: 'Node',
    key: 'node'
  }
]

Преимущества:

  • автодополнение
  • предотвращение ошибок
  • строгая типизация структуры данных

Интеграция с формами

TreeSelect легко интегрируется с компонентом формы.

Пример:

<n-form>
  <n-form-item label="Категория">
    <n-tree-select
      v-model:value="value"
      :options="options"
    />
  </n-form-item>
</n-form>

Это позволяет:

  • выполнять валидацию
  • управлять состоянием формы
  • объединять несколько компонентов ввода

Расширенные сценарии использования

TreeSelect часто применяется в более сложных интерфейсах.

Системы прав доступа

Используется для выбора:

  • ролей
  • разрешений
  • модулей системы

Структура дерева может повторять архитектуру приложения.

Каталоги товаров

Позволяет выбирать категории из иерархии:

Электроника
  ├─ Компьютеры
  ├─ Смартфоны
  └─ Телевизоры

Организационные структуры

Применяется для отображения:

  • департаментов
  • отделов
  • сотрудников

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

Свойство Назначение
options структура дерева
value выбранное значение
multiple множественный выбор
filterable включение поиска
checkable чекбоксы
cascade каскадный выбор
show-path отображение пути
expanded-keys раскрытые узлы
clearable очистка значения

Типичные ошибки при использовании

Отсутствие уникальных ключей

Каждый узел дерева обязан иметь уникальное значение key.

Ошибка:

Duplicate key

Неправильная структура children

children должен быть массивом объектов TreeOption.

Неверно:

children: {}

Верно:

children: []

Несоответствие типов value

При множественном выборе value должен быть массивом.

const value = ref([])

Архитектурные преимущества TreeSelect

Компонент предоставляет:

  • высокую гибкость конфигурации
  • масштабируемость для больших иерархий
  • глубокую интеграцию с реактивной системой Vue
  • поддержку кастомного рендеринга

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

Оглавление