列表

列表是组织工具，可以增强内容的可读性和组织性。

简介

列表通过文本或图像的连续垂直索引，以简洁易懂的格式呈现信息。

Joy UI 列表使用相关组件的集合实现

• List - 列表项的包装器。默认渲染为 <ul>。
• List Item - 通用列表项。默认渲染为 <li>。
• List Item Button - 在列表项内部使用的操作元素。
• List Item Decorator - 列表项的装饰器，通常用于显示图标。
• List Item Content - 列表项内部的容器，用于显示文本内容。
• List Divider - 列表项之间的分隔符。
• List Subheader - 嵌套列表的标签。

基础

import List from '@mui/joy/List';
import ListItem from '@mui/joy/ListItem';

自定义

变体

List 组件支持 Joy UI 的四种全局变体：solid、soft、outlined 和 plain。

尺寸

List 组件提供三种尺寸：sm、md 和 lg。List 的尺寸决定了其字体大小和密度。

颜色

主题中包含的每个调色板都可以通过 color 属性使用。

装饰器

import ListItemDecorator from '@mui/joy/ListItemDecorator';

使用 List Item Decorator 组件向列表项添加支持图标或元素。

水平列表

在 List 组件上使用 orientation="horizontal" 属性水平显示列表。

语义元素

使用 component 属性来控制渲染的 HTML 标签。

<List component="ol">

下面的示例将 List 组件渲染为 HTML <nav> 元素。

标记

将 marker 属性与任何有效的 list-style-type 值一起使用，以向列表项添加标记。

省略内容

import ListItemContent from '@mui/joy/ListItemContent';

当在 List 中处理较长内容时，您可以将 List Item Content 组件与 <Typography noWrap /> 结合使用，以便在内容超出可用空间时显示省略号。这有助于保持 List Item 的视觉一致性，并防止文本溢出到 List Item 的容器之外。

分隔符

import ListDivider from '@mui/joy/ListDivider';

List Divider 组件带有四种 inset 模式

• 默认（未提供 inset 属性）：从 List 的一边延伸到另一边。
• inset="gutter"：从 List Item Decorator 的开头到内容的结尾。
• inset="startDecorator"：从 List Item Decorator 的开头到容器边缘的结尾。
• inset="startContent"：从内容的开头到容器的边缘。

如果您使用的是水平列表，则只有 inset="gutter" 可以用作列表分隔符。

粘性项目

将 List 组件用作 Sheet 组件的子组件来创建“粘性”项目。在您希望粘住的项目上，您可以添加 sticky 属性。

Sheet 组件自动调整粘性列表项以具有相同的背景，以便在滚动时内容不会溢出。

嵌套列表

import ListSubheader from '@mui/joy/ListSubheader';

您可以使用 List Item 上的 nested 属性创建嵌套列表。这使您可以添加 List Subheader 以及新的 List 组件作为 List Item 的子组件。嵌套 List 将从根 List 组件继承其 size 以及其他 CSS 变量（如 --List-radius 和 --ListItem-radius），以保持设计的一致性。嵌套 List 的布局和间距将保持独立。

交互式列表项

import ListItemButton from '@mui/joy/ListItemButton';

要使 List Item 具有交互性，您可以在 List Item 内使用 List Item Button。

要向 List Item Button 添加辅助操作，请将其包裹在 List Item 组件中，然后向其添加所需的开始或结束操作元素。

已选中

在 List Item Button 组件上使用 selected 属性来指示项目当前是否被选中。当项目被选中时，它会应用 color="primary" 和一些额外的样式（如字体粗细）来直观地传达选中状态。

CSS 变量演示场

试用 List 组件可用的 CSS 变量，看看设计如何变化。您可以使用这些变量通过 sx 属性和主题自定义组件。

常见示例

iOS 设置

此示例使用嵌套列表将设置分为几组。

Gmail 导航

灵感来自 Gmail 的桌面导航栏。

可折叠列表

灵感来自 Gatsby 文档 导航栏。此示例使用 startAction 属性创建可折叠按钮。

导航菜单

灵感来自 APG 导航菜单栏 设计模式。此示例使用水平和垂直列表的组合来构成导航菜单栏。

它还支持键盘导航，灵感来自 Roving UX 技术。

无障碍性

为确保您的 List 具有无障碍性，您应考虑以下因素

• 为列表使用适当的 HTML 语义元素（例如 ol 或 ul），以确保辅助技术可以正确解释列表结构。
• 确保在 aria-labelledby 属性中使用描述列表内容的有意义的名称。
• 使用 role 属性提供有关列表及其项目用途的更多信息。例如，对于列表使用 role="list"，对于每个列表项使用 role="listitem"。

结构

List 组件由根 <ul> 元素和一个或多个由 List Item 组件渲染的子 <li> 元素组成。List Item 内的所有组件都是可选的。List Divider（如果存在）渲染一个带有 role="separator" 的 <li>，而 List Subheader 渲染一个 <div>。

<ul class="MuiList-root">
  <li class="MuiListItem-root">
    <div class="MuiListItemButton-root" role="button">
      <span class="MuiListItemDecorator-root">
        <!-- Icon for List Item Decorator -->
      </span>
      <div class="MuiListItemContent-root">
        <!-- List Item content -->
      </div>
    </div>
  </li>
</ul>

API

请参阅下面的文档，以获取此处提及的组件的所有可用属性和类的完整参考。

• <List />
• <ListDivider />
• <ListItem />
• <ListItemButton />
• <ListItemContent />
• <ListItemDecorator />
• <ListSubheader />