Обзор
ListItem предоставляет визуальную структуру, общую для строк списков и меню. По умолчанию он отображает div для пассивного содержимого. Используйте ListItemButton для обычных строк действий. При необходимости используйте ListItem с якорем для навигации или с пользовательским семантическим владельцем. Используйте Dropdown или Select, когда вам нужен полноценный владелец всплывающего окна или выбора.
Использование
Анатомия
ListItem предоставляет слоты содержимого через props. Эти слоты размещают содержимое в одной строке; они не являются отдельно экспортируемыми компонентами.
Строка предоставляет компоновку.
render принимает элемент или обратный вызов, получающий нативные props и визуальное состояние. При использовании обратного вызова распределите эти props по фактическому корневому элементу. Нативные атрибуты, обработчики событий, className, style и ref передаются этому корневому элементу. Для строки с независимыми кнопками действий оставьте саму строку неинтерактивной, чтобы эти кнопки оставались отдельными элементами управления.
Многострочные строки
УстановитеdescriptionPlacement="below", чтобы разместить дополнительное содержимое под меткой. Заголовок сохраняет существующее поведение усечения, а дополнительное содержимое переносится в пределах доступной ширины. Стандартное размещение inline и размещение end сохраняют существующий внешний вид.
truncate или lineClamp в качестве description. Пользовательское содержимое самостоятельно управляет своей компоновкой и доступными метками.
Независимые визуальные состояния
Все визуальные состояния принадлежат вызывающему коду.active определяет открытую или текущую строку, не выбирая её. selected обозначает выбор, а focused — подсветку навигации с клавиатуры без перемещения фокуса DOM. active применяет фон текущей строки. Установите selectionAppearance="accent", чтобы добавить акцентную заливку выбранным строкам независимо от размещения описания. Внешний вид по умолчанию сохраняет существующее оформление выбора на основе индикатора. focused применяет общий подсвеченный фон, в том числе когда владелец использует его для подсветки указателем. Контур фокуса следует за фактическим фокусом с клавиатуры на корневом элементе или его элементах управления.
Эти свойства не добавляют доступных состояний. Укажите aria-current, aria-selected или состояние checked элемента управления на соответствующем семантическом владельце. Фактический фокус с клавиатуры также сохраняет нативный контур фокуса.
Независимые элементы управления
Сохраняйте корневойdiv по умолчанию, если строка содержит настоящий флажок или независимые кнопки действий. Используйте startIcon для флажка, а actions — для кнопок. Декоративный indicator не нужен, если настоящий флажок уже отображает выбор.
ListItem.disabled изменяет только внешний вид; передайте disabled каждому настоящему элементу управления, чтобы предотвратить его активацию.
Существующее поведение видимости действий применяется к многострочным строкам: actionsVisibility="hover" показывает действия при наведении или фокусе внутри строки и сохраняет их видимыми на сенсорных устройствах. Установите значение always для постоянно отображаемых действий, в том числе когда открыто всплывающее окно, принадлежащее вызывающему коду. При ширине строки 480px или менее многострочные действия перемещаются на отдельную строку и переносятся по мере необходимости.
Строка действия
Используйте ListItemButton, чтобы сочетать стилизацию строки с нативным взаимодействием кнопки. Передайтеdisabled один раз, чтобы управлять и внешним видом, и активацией.
ListItem через render. Этот владелец предоставляет нативный фокус, активацию клавишами Enter и Space, а также поведение disabled. ListItem.disabled предоставляет только соответствующий визуальный стиль. shortcut отображает подсказки; сочетания клавиш регистрирует ваше приложение.
Навигация и явные ссылки
Передайте якорь черезrender, если навигация выполняется по всей строке. Разместите атрибуты якоря, включая href, target и rel, на этом элементе.
div, чтобы избежать вложенных ссылок или кнопок. Строковые метки сохраняют усечение и всплывающую подсказку при переполнении; для пользовательского содержимого можно использовать OverflowingTextWithTooltip с явно отрисованным якорем.
У ссылок нет нативного атрибута disabled. Если назначение недоступно, владелец ссылки должен обеспечить соответствующую семантику, порядок перехода по Tab и политику навигации. Одна лишь стилизация с помощью ListItem.disabled не предотвращает навигацию.
Владелец элемента всплывающего меню
ИспользуйтеDropdown.ActionItem или Dropdown.OptionItem внутри их владельца всплывающего окна. Эти части уже компонуют макет ListItem и предоставляют его визуальные слоты. Владелец всплывающего меню предоставляет роли, фокус, навигацию с клавиатуры, активацию и поведение disabled.
Политика нативных событий
ListItem перенаправляет нативные объекты событий и обработчики. Щелчки всплывают обычным образом, включая щелчки по элементам управления завершающих действий. Установите любое намеренное ограничение на интерактивном владельце или в обработчике вызывающей стороны.preventDefault(), например предотвращение навигации по ссылке. Передача onClick не добавляет роль, не делает div доступным для управления с клавиатуры и не изменяет распространение событий.
Перетаскивание и навигация редактора, управляемые приложением
Создавайте строки с возможностью изменения порядка с помощьюListItem внутри хоста перетаскивания вашего приложения. Разместите атрибуты и слушатели перетаскивания хоста на его рукоятке и передайте рукоятку или захват через startIcon. Сохраняйте отдельные элементы управления видимостью, редактированием и удалением в actions. Хост перетаскивания управляет изменением порядка с помощью указателя и клавиатуры, отключением перетаскивания и доступными метками рукоятки.
Для предложений редактора сохраните существующий listbox редактора и владельца активного варианта. Отрисовывайте каждый ListItem с role="option" и aria-selected, а для внешнего вида активной строки используйте focused. Редактор управляет навигацией стрелками и активацией клавишей Enter, пока фокус остается в области редактирования. Предотвращайте изменения фокуса при нажатии указателем, когда этого требует редактор, и обрабатывайте выбор указателем в обработчике строки приложения.
Для предложений на странице Dropdown используйте Dropdown.OptionItem или Dropdown.ActionItem, чтобы эта страница управляла навигацией и активацией. Не добавляйте второй обработчик Enter или Space владельцу, который уже активируется с клавиатуры.
Строка настроек
Используйте SettingsRow для строки переключателя с меткой. Он объединяетListItem и Switch, управляет их доступной связью и использует отключенное состояние переключателя для внешнего вида строки.
Индикатор выбора
active, selected, focused и disabled независимо управляют оформлением строки. Они не регистрируют действия, не перемещают DOM-фокус, не добавляют доступные роли или состояния и не подавляют события. Индикаторы check и checkbox являются декоративными; для элемента управления формы используйте настоящий Checkbox. Установите aria-pressed, aria-selected или семантику другого состояния на владельце, которому они нужны.
Строки выбора
Выбор принадлежит родительскому элементу. УListItem нет неконтролируемого состояния выбора: передайте selected и обновляйте его из onClick. Используйте indicator="check" для одного варианта и indicator="checkbox" для нескольких вариантов. Оба индикатора декоративные; интерактивный владелец обрабатывает активацию.
В существующем listbox передайте role="option" и aria-selected, а управление фокусом и клавишами со стрелками оставьте в listbox. Для полноценного виджета выбора используйте Select. Автономные кнопки выбора могут использовать aria-pressed, как в этих примерах.
Одиночный выбор
Поместите Avatar вstartIcon, чтобы обозначить запись. Используйте description для вспомогательного текста и descriptionPlacement="end" для значения в конце.
Множественный выбор
Используйте Tag в качестве содержимого строки для значений с тегами или поместите ColorSample вstartIcon для выбора цвета. Строка также может содержать обычный текст или аватар.
disabled на отрисованной кнопке, чтобы предотвратить активацию и удалить её из порядка перехода по Tab. Также передайте ListItem.disabled для её визуального оформления.
Слоты
ИспользуйтеstartIcon и endIcon для значков или содержимого, принадлежащего вызывающему коду, description — для вспомогательного текста, actions — для конечного содержимого, а hasSubmenu — для индикатора подменю. descriptionPlacement принимает значения inline, end или below. color="danger" задаёт стиль для деструктивного действия. Не вкладывайте интерактивные элементы управления в строку, отрисованную как кнопка.
Метки
ИспользуйтеshortcutJoinLabel, чтобы настроить текст между последовательными шагами сочетания клавиш. По умолчанию используется then; пустая строка удаляет текст-соединитель. То же свойство доступно в частях элемента Dropdown.
Свойства
Справочник создаётся на основе публичных типов компонента. Поддерживаются нативные атрибуты и обработчикиdiv, включая доступные имена и нативные события. Разместите специфичные для кнопки или якоря атрибуты на элементе, предоставленном через render. И ref, и ref отрисованного элемента указывают на фактический корневой элемент DOM.
ReactNode
Trailing content, such as buttons, rendered after the content.
"auto" | "end"
по умолчанию:"auto"
Keeps actions beside the content at every width when set to
end. The default auto preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch."always" | "hover"
по умолчанию:"hover"
When trailing actions are visible: on hover and focus, or always.
boolean
по умолчанию:"false"
Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.
"danger" | "neutral"
по умолчанию:"neutral"
Color of the text and icons.
danger marks a destructive action.ReactNode
Supporting text, placed according to
descriptionPlacement."below" | "end" | "inline"
по умолчанию:"inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
boolean
по умолчанию:"false"
Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner.
ReactNode
Icon rendered after the content.
boolean
по умолчанию:"false"
Applies highlighted styling without moving DOM focus or handling keyboard navigation.
Shows a chevron indicating that the item opens a submenu.
"check" | "checkbox" | "none"
по умолчанию:"none"
Selection indicator: a check icon after the content or a checkbox before
it.
Ref<HTMLElement>
Ref to the actual DOM root, including a composed native button or link.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>
Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior.
boolean
по умолчанию:"false"
Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.
"accent" | "default"
по умолчанию:"default"
Selection styling independent of description placement.
default preserves indicator-based styling; accent fills selected rows with the accent background.ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to
then; pass an empty string to omit it.ReactNode
Icon rendered before the content.
shortcut={['Mod', 'Enter']} для одновременного нажатия клавиш или shortcut={[['G'], ['P']]} для последовательных нажатий. См. Shortcut для вложенных комбинаций и общего форматировщика строк.