列表

列表是組織工具，可以增強內容的可讀性和組織性。

簡介

列表透過文字或圖片的連續垂直索引，以簡潔、易於理解的格式呈現資訊。

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> 元素。

標記

使用具有任何有效 list-style-type 值的 marker 屬性，將標記新增至列表項目。

省略符號內容

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

當在列表中使用較長的內容時，您可以結合 List Item Content 元件和 <Typography noWrap />，以便在內容超出可用空間時顯示省略符號。這有助於保持列表項目的視覺一致性，並防止文字溢出列表項目的容器之外。

分隔線

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

List Divider 元件提供四種 inset 模式

• 預設值（未提供 inset 屬性）：從列表的一個邊緣延伸到另一個邊緣。
• inset="gutter"：從 List Item Decorator 的開頭到內容的結尾。
• inset="startDecorator"：從 List Item Decorator 的開頭到容器邊緣的結尾。
• inset="startContent"：從內容的開頭到容器的邊緣。

如果您使用的是水平列表，則只有 inset="gutter" 會作為列表分隔線運作。

黏性項目

將 List 元件用作 Sheet 元件的子元件，以建立「黏性」項目。在您希望黏住的項目上，您可以新增 sticky 屬性。

Sheet 元件會自動調整 sticky 列表項目以具有相同的背景，以便在捲動時內容不會溢出。

巢狀列表

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

您可以在 List Item 上使用 nested 屬性來建立巢狀列表。這可讓您新增 List Subheader 以及新的 List 元件作為 List Item 的子元件。巢狀列表將從根 List 元件繼承其 size 以及其他 CSS 變數（例如 --List-radius 和 --ListItem-radius），以保持設計的一致性。巢狀列表的版面配置和間距將保持獨立。

互動式列表項目

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 變數 playground

試用 List 元件可用的 CSS 變數，以查看設計如何變更。您可以使用這些變數，透過 sx 屬性和主題來自訂元件。

常見範例

iOS 設定

此範例使用巢狀列表將設定分成群組。

Gmail 導航

靈感來自 Gmail 的桌面導航列。

可摺疊列表

靈感來自 Gatsby 文件導航列。此範例使用 startAction 屬性來建立可摺疊按鈕。

導航選單

靈感來自 APG 導航選單列設計模式。此範例結合了水平和垂直列表，以形成導航選單列。

它也支援鍵盤導航，靈感來自 Roving UX 技術。

無障礙功能

為了確保您的列表具有無障礙功能，以下是一些您應該考量的因素

• 為列表使用適當的 HTML 語意元素（例如 ol 或 ul），以確保輔助技術可以正確解譯列表結構。
• 請務必使用有意義的名稱，在 aria-labelledby 屬性中描述列表的內容。
• 使用 role 屬性來提供有關列表及其項目的用途的其他資訊。例如，對列表使用 role="list"，對每個列表項目使用 role="listitem"。

剖析

List 元件是由根 <ul> 元素和一個或多個由 List Item 元件渲染的子 <li> 元素組成。List Item 內巢狀的所有元件都是選用的。List Divider（如果存在）會渲染 <li> 和 role="separator"，而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 />