Cascader

Базовый выбор

Значение: —. Поле с name="geo" отдаёт в нативную форму скрытый input: у каскада в форму попадает выбранный уровень, а не весь путь.

Пресет значения

При открытии панели ветка выбранного значения уже раскрыта: видны все уровни до листа.

Поиск и множественный выбор

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

Состояния

Узел «Стоп-лист» отключён: по нему нельзя перейти и выбрать город внутри.

События

Выберите значение в первом блоке — здесь появится событие select.

Входные параметры

ИмяТипПо умолчаниюОписание
optionsCascaderOption[][]Корневые узлы каскада. Вложенность задаётся полем children.
modelValueCascaderPath | CascaderPath[] | nullnull Выбранный путь — массив значений от корня к листу, например ['ru', 'ru-szfo', 'ru-spb']. В режиме multiple — массив таких путей. Путь, которого нет в options, считается пустым выбором.
placeholderstring'Выберите значение'Подсказка триггера, когда ничего не выбрано.
searchPlaceholderstring'Поиск...'Подсказка в поле поиска.
size'sm' | 'md' | 'lg'размер из C3FormField, иначе 'md'Высота поля. Приоритет у собственного пропа, затем у контекста формы.
multiplebooleanfalseМножественный выбор: панель не закрывается, повторный выбор пути убирает его.
searchablebooleanfalseПоказывать поиск по всем уровням сразу.
clearablebooleanfalseПоказывать кнопку очистки выбора. Видна только когда есть выбор.
disabledbooleanfalseПоле недоступно: панель не открывается, кнопка очистки скрыта.
errorbooleanfalseФлаг ошибки: добавляет стиль и aria-invalid. Учитывается и ошибка C3FormField.
namestringundefined Имя поля. Компонент рендерит скрытый input с этим именем, поэтому значение попадает в нативную форму: у пути в форму идёт выбранный уровень, в режиме multiple — по полю на каждый путь.
columnWidthstring'12rem'Ширина одной колонки.
maxHeightstring'18rem'Максимальная высота панели: при большом дереве появляется прокрутка.

События

ИмяАргументыОписание
update:modelValueCascaderPath | CascaderPath[]Новое значение. Доступно как v-model.
select(path, option)Выбран путь: массив значений и сам узел CascaderOption.
clear—Выбор очищен кнопкой очистки.

Тип CascaderOption

ПолеТипПо умолчаниюОписание
labelstring—Подпись узла.
valuestring | numberlabelЗначение узла. Если не задано, значением считается подпись.
disabledbooleanfalseУзел недоступен: по нему нельзя перейти к потомкам и нельзя его выбрать.
childrenCascaderOption[]undefinedПотомки. Если поле есть, узел считается не листом: клик раскрывает ветку.

Описание

Каскадный выбор нужен для данных с глубокой иерархией: страна → регион → город, отдел → команда, категория → подкатегория → товар. Пользователь видит сразу несколько уровней рядом, поэтому не нужно возвращаться назад: ширина панели растёт вместе с числом открытых колонок.

Значение компонента — путь, а не идентификатор выбранного узла. Это делает состояние самодостаточным: по нему можно восстановить раскрытые уровни, показать полный путь в триггере и однозначно сопоставить выбор с серверными данными.

Выбирается только лист: узел с потомками раскрывает ветку, а не создаёт путь длиной в один уровень. Это исключает неоднозначность, когда выбранный уровень неизвестен.

Поиск (searchable) заменяет колонки одним списком совпадений по всем уровням сразу и показывает полный путь найденного узла — так, например, по запросу «Санкт» виден путь «Россия / Северо-Западный ФО / Санкт-Петербург», а не просто его последний уровень.

Дополнительная информация

  • Хлебные крошки над колонками показывают, какая ветка раскрыта; клик по крошке возвращает фокус на этот уровень. В режиме поиска крошки скрыты.
  • Клавиатура: Enter, Space, ↑ и ↓ открывают панель; внутри неё ↑/↓ перемещают активный узел, ←/→ переходят между колонками, Home/End — к краю колонки, Enter раскрывает узел или выбирает лист, Escape закрывает панель.
  • Навигация пропускает отключённые узлы и зацикливается по колонке; выбранная ветка подсвечена акцентом.
  • В режиме поиска ←/→ и Home/End не перехватываются: список один, колонок нет.
  • Доступность: aria-haspopup="tree" и aria-expanded у триггера, role="treeitem" и aria-level у узлов, aria-selected отмечает ветку выбранного значения.
  • Панель позиционируется через computePopoverPosition и закрывается по клику вне; при открытии фокус уходит в панель, при закрытии возвращается на триггер.
  • Телепорт рендерится только на клиенте, поэтому SSR-разметка не расходится при нескольких каскадах на странице.
  • При смене options на открытой панели колонки пересобираются: оставлять прежние данные было бы расхождением с новым набором.
  • Смена modelValue снаружи обновляет раскрытую ветку, поэтому значение можно задавать при инициализации или сбросить из кода.

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

const path = ref<CascaderPath | null>(null)

<C3Cascader v-model="path" :options="geoOptions" searchable clearable />

После выбора в обработчике @select путь готов к отправке целиком: ['ru', 'ru-szfo', 'ru-spb'].

×