Перейти к основному содержанию

Обзор

OverflowingList измеряет доступную ширину, размещает помещающиеся элементы в компактном ряду и предоставляет кнопку +N, открывающую полный список во всплывающем окне. Количество обновляется при изменении контейнера, содержимого элементов или упорядоченного списка. У пустых списков и списков, которые помещаются, нет кнопки переполнения или доступного всплывающего окна. Передайте полный упорядоченный список как элементы с ключами. Ваше приложение управляет содержимым, действиями и данными каждого элемента. Компактная строка остаётся видимой при открытии всплывающего окна. Во всплывающем окне повторяется полный список, включая элементы, помещающиеся в строке.

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

Видимость счётчика

В режиме по умолчанию при фокусе на встроенном элементе сохраняется текущая видимость количества, поэтому отображение количества не вытесняет этот элемент из строки. При фокусировке кнопки количества количество становится видимым. Используйте false, если окружающий интерфейс предоставляет другой способ доступа к скрытым элементам. При изменении на false количество скрывается без закрытия уже открытого всплывающего окна. open и defaultOpen по-прежнему могут отображать полный список при переполнении элементов. Удаление переполняющих элементов или расширение списка до тех пор, пока не поместятся все элементы, закрывает всплывающее окно и удаляет кнопку количества. Количество всегда описывает элементы за пределами компактной строки. maxInlineCount ограничивает число видимых элементов строки. Доступная ширина может ещё больше уменьшить это число. Всплывающее окно всё равно содержит полный список. Оно не загружает отсутствующие элементы и не виртуализирует всплывающее окно.

Состояние всплывающего окна

Список управляет состоянием своего всплывающего окна, когда open не указан. Используйте defaultOpen для его начального состояния. По умолчанию используется false; для изначально открытого всплывающего окна всё равно требуются переполняющие элементы. Передайте open и обновляйте его в onOpenChange, чтобы управлять состоянием всплывающего окна. Колбэк получает запрошенное логическое значение и сведения о событии установленного Popover, включая reason, event, trigger, cancel() и preventUnmountOnClose(). Вызов cancel() предотвращает запрошенное изменение состояния. При управляемом использовании обновляйте своё состояние только для изменений, которые вы принимаете. Передайте actionsRef, чтобы получить методы Popover close() и unmount(). close() запрашивает закрытие через onOpenChange и учитывает отмену. Если ваш колбэк вызывает preventUnmountOnClose() для выполнения управляемого вызывающей стороной выхода, вызовите actionsRef.current?.unmount() после завершения этого выхода. Это освобождает удерживаемое всплывающее окно, не удаляя список, и позволяет открыть его снова.

Нативные цели и композиция

Нативные атрибуты div, обработчики, стили, имена классов и ссылки на OverflowingList применяются к корневому элементу компактной строки. Используйте triggerProps для кнопки количества и popupProps для div содержимого всплывающего окна. Оба сохраняют нативные свойства, обработчики, ссылку и композицию render элемента/функции соответствующей части Popover. Настройте триггер с помощью triggerProps.render, как в управляемом примере, или передайте triggerProps.children, чтобы заменить +N. Пользовательские компоненты должны перенаправлять предоставленные свойства и ссылку. Пользовательские компоненты всплывающих окон также должны отображать предоставленные дочерние элементы; OverflowingList управляет содержимым элементов. Значение overflowLabel по умолчанию — “Показать все элементы”. Доступное имя кнопки по умолчанию объединяет количество и эту метку, например “+3 Показать все команды”. Переопределите triggerProps['aria-label'] или popupProps['aria-label'], если их содержимому требуется другое имя. По умолчанию OverflowingList останавливает распространение click, mousedown, pointerdown, keydown и keyup для триггера и всплывающего окна. Это предотвращает активацию окружающего поля или средства выбора при открытии всплывающего окна и взаимодействии с его элементами. Обработчик, заданный через triggerProps или popupProps, заменяет обработчик по умолчанию для этого события. Вызовите event.stopPropagation() в своём обработчике, чтобы сохранить блокировку, либо не вызывайте его, чтобы разрешить всплытие этого события. Для других событий сохраняются значения по умолчанию. Обработчики пользовательского элемента render компонуются с предоставленными свойствами обычным образом. Когда переопределение клика во всплывающем окне разрешает всплытие, установленный портал Base UI может дважды отправить этот клик окружающему предку React с одним и тем же нативным событием. Это также происходит с обычным Popover. OverflowingList сохраняет это поведение вышестоящего компонента; он не гарантирует один вызов колбэка предка для каждого нативного события всплывающего окна при включённом всплытии.

Клавиатура и фокус

Enter, Space и активация указателем открывают немодальное всплывающее окно. Escape и взаимодействие вне окна закрывают его. Обычное закрытие возвращает фокус на кнопку количества. Фокус, уже находящийся на видимом встроенном элементе или внешнем элементе управления, сохраняется. Всплывающее окно поддерживает содержимое, ссылки и кнопки с их нативным поведением клавиатуры; оно не превращает их в элементы меню и не добавляет навигацию по меню стрелками. Используйте popupProps.initialFocus и popupProps.finalFocus, чтобы настроить фокус при открытии и закрытии через контракт установленного Popover. Каждый список независимо управляет своими адаптивными измерениями. Размонтирование одного списка освобождает его наблюдателей и не влияет на работу других списков.

Серверный рендеринг и гидратация

Серверная разметка включает первые maxInlineCount элементов либо все элементы, если ограничение не указано. Измерение ширины и содержимое всплывающего окна становятся доступными после монтирования на клиенте. Гидратация повторно использует предварительную строку и применяет адаптивное измерение после монтирования на клиенте. Дочерние элементы строки и всплывающего окна являются отдельными отрисованными экземплярами. Поддерживайте общее состояние между этими местоположениями на стороне вызывающего кода.

Миграция

Всплывающее окно по-прежнему показывает полный список и по умолчанию использует “Показать все элементы”. showOverflowCount={false} сохраняет обрезанную строку и скрывает количество. Это не закрывает уже открытое всплывающее окно. Триггер и всплывающее окно сохраняют блокировку по умолчанию для click, mousedown, pointerdown, keydown и keyup. Переопределите отдельный обработчик через triggerProps или popupProps, если окружающий интерфейс должен получать это событие.

Свойства

RefObject<PopoverRootActions | null>
Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes.
ReactElement<unknown, string | JSXElementConstructor<any>>[]
обязательно
Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row.
boolean
по умолчанию:"false"
Initial popup visibility when uncontrolled. Defaults to false.
number
Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list.
((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)
Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose().
boolean
Controlled popup visibility. A popup can appear only when items overflow.
string
по умолчанию:"Show all items"
Accessible label for the popup. The default overflow button is named by its visible count followed by this label. Defaults to Show all items.
Omit<PopoverPopupProps, "children">
Popover.Popup native props, handlers, ref, render composition and focus options for the overflow content. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default.
Ref<HTMLDivElement>
Ref forwarded to the compact row root div.
boolean
Shows the count on hover, keyboard focus or while open by default. Use true to keep it visible whenever items overflow, or false to hide the count and clip the row. An already-open popup stays open until dismissed. Empty lists and lists that fit have no trigger.
Omit< ComponentPropsWithRef<typeof Popover.Trigger>, 'handle' | 'payload' | 'ref' > & { ref?: Ref<HTMLElement> }
Popover.Trigger native props, handlers, ref, children and render composition for the count button. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default. Custom components must forward supplied props and ref.