GitHubopen_in_new

ListItem ​

ListItem 提供丰富的列表项布局。默认情况下它可交互，并渲染为按钮；设置 href 时则渲染为锚点。对于纯信息行或由内部控件负责交互的行，可设置 interactive="false"。此时列表项会渲染为 div，不具备按钮、链接、焦点、状态层或按压行为。列表项处于被动状态时，任何 href 都会被忽略。

ListItem 会自动参与 List Grouping CSS 工具类的分组；该工具类也可用于分组其他元素和组件。

尺寸 ​

size 独立于 appearance，用于选择行几何尺寸。它继承自 listItemDefaults.size 或 provideListItemDefaults({ size })，库默认值为 medium（56px）。Helper 会响应式地合并字段；设为 undefined 可恢复继承。Button 尺寸默认值不会控制列表行。

尺寸最小高度块方向内边距行内方向内边距图标间距图标尺寸
extra-small36px6px12px8px20px
small48px6px16px12px24px
medium56px6px16px20px24px
large64px8px22px20px24px
extra-large80px10px24px24px28px

公开 Token 会覆盖预设值：--md-item-min-height、--md-item-padding-block、--md-item-padding-inline、--md-item-gap、--md-item-content-gap 和 --md-item-icon-size。可在祖先元素或组件根元素上设置；根元素上的值优先于继承值。组件本身不会设置这些公开几何 Token。

表格显示密度 0 的尺寸。继承的 --md-density token 会降低最小高度和垂直内边距，不改变文字、图标或水平间距。公开尺寸 token 优先级更高。预设定义的是最小高度，因此描述和多行标题可使行增高。详见密度。

示例 ​

默认 ​

组合用法 ​

M3 Library Overview Open the Button docs page.→

Vue Router ​

当 ListItem 用作导航时，请使用 RouterLink custom，并将其 href 和 navigate 传给该组件。

外观 ​

appearance="standard" 是默认值：活动指示器固定为整行宽度、转角紧凑，并且不会展开高亮或执行按压形状变换。appearance="expressive" 保留展开式指示器和按压形状变换。外观不会改变按钮/链接/展示语义、插槽或布局 Token。应用级外观可通过 listItemDefaults.appearance 设置，子树可在 setup 中调用 provideListItemDefaults()；实例的 appearance 属性优先级更高。

standard

expressive

现有条目如需保留之前的外观，可设置 appearance="expressive"。shape 属性控制 expressive 外观的形状；standard 使用 --md-shape-compact。--md-item-indicator-shape 可定制两种外观中的指示器。

菜单命令请使用 MenuItem。ListItem 仍用于一般列表项。外观与密度建议请参阅样式指南。

列表项中的选择控件 ​

CheckBox、Radio 和 Switch 可以出现在列表项中，作为状态指示器。在这种布局中，整行通常是更大、更易点击的目标，而选择控件只负责传达当前状态。

此时请使用控件的 presentation 属性。展示模式保留 Material 3 视觉状态，但会移除嵌套的原生输入框、对辅助技术隐藏视觉控件，并禁用控件自身的 state layer 效果。父级行必须提供可访问名称、角色、选中状态、禁用状态和交互反馈。

模式 ​

无障碍规则 ​

  • 每行只保留一个交互目标。整行是控件；视觉上的 CheckBox、Radio 或 Switch 不应成为另一个可聚焦元素。
  • 将可访问名称放在行上，通常使用可见的 title 文本。
  • 在行上设置 aria-checked，并使其与视觉控件的 checked 状态保持同步。
  • 使用匹配的角色：独立选择使用 checkbox，一组单选项使用 radio，即时开关设置使用 switch。
  • 将相关单选行放入带有可访问名称的 radiogroup 中。
  • 对需要原生单选键盘行为的单选组，请保留原生 radio 输入框，或在父级组中添加方向键导航。
  • 禁用某行时，同时禁用该行并向展示控件传入 disabled，使视觉状态与交互状态一致。

不应使用展示模式的情况 ​

独立控件不要使用 presentation。独立的 CheckBox、Radio 或 Switch 应保留其原生输入框，以便表单、键盘交互、焦点指示和辅助技术无需额外代码即可正常工作。

也应避免在可用行内显示禁用状态的视觉控件。这样会让人误以为可见控件不可用，但整行仍会改变状态，造成困惑。

参考 ​

结构

元素部件选择器
<component>
root
[data-scope="item"][data-part="root"]
left_click鼠标左键单击复制
<Icon>
leading条件显示
[data-scope="item"][data-part="leading"]
left_click鼠标左键单击复制
<span>
main
[data-scope="item"][data-part="main"]
left_click鼠标左键单击复制
<span>
header条件显示
[data-scope="item"][data-part="header"]
left_click鼠标左键单击复制
<span>
title条件显示
[data-scope="item"][data-part="title"]
left_click鼠标左键单击复制
<span>
description条件显示
[data-scope="item"][data-part="description"]
left_click鼠标左键单击复制
<span>
footer条件显示
[data-scope="item"][data-part="footer"]
<Icon>
trailing条件显示
[data-scope="item"][data-part="trailing"]
left_click鼠标左键单击复制

属性

名称说明默认值控件
shape可选

The shape of the button.

M3Shape | undefined
undefined
-
href可选

The href attribute. If provided, the button will be rendered as an anchor element.

string | undefined
undefined
leadingIcon可选

Name of the leading icon.

string | undefined
undefined
trailingIcon可选

Name of the trailing icon.

string | undefined
undefined
disabled可选

Whether the button is disabled.

boolean | undefined
undefined
size可选

Row geometry preset. Public item tokens override individual dimensions.

ListItemSize | undefined
undefined
-
appearance可选

Standard fixed highlight or expressive expanding indicator and press morph.

standardexpressive
undefined
interactive可选

Whether the whole item is an interactive action or link.

boolean | undefined
true
active可选

Highlight the item as active/selected.

boolean | undefined
false
title可选

Fallback title when default slot is not provided.

string | undefined
undefined
description可选

Fallback description when description slot is not provided.

string | undefined
undefined

插槽6

名称参数说明
header-Optional content above the main row.
leading-Optional leading content.
default-Main title content.
description-Optional description below the title.
trailing-Optional trailing content.
footer-Optional content below the main row.

样式20

Token说明
--md-item-active-icon-colorColor
回退值var(--md-sys-color-on-secondary-container)

Controls active icon color.

--md-item-active-indicator-colorColor
回退值var(--md-sys-color-secondary-container)

Controls active indicator color.

--md-item-active-label-colorColor
回退值var(--md-sys-color-on-secondary-container)

Controls active label color.

--md-item-active-state-layer-colorState
回退值var(--md-sys-color-on-secondary-container)

Controls active state layer color.

--md-item-content-gapLayout
回退值--dp(2)

Controls content gap.

--md-item-footer-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls footer color.

--md-item-gapLayout
回退值--dp(12)

Controls gap.

--md-item-header-colorColor
回退值var(--md-sys-color-on-surface-variant)

Controls header color.

--md-item-icon-sizeLayout
回退值Size, typography, density and icon scale (default medium reference: 24dp)

Controls icon size.

--md-item-inactive-icon-colorColor
回退值var(--md-color-on-container)

Controls inactive icon color.

--md-item-inactive-label-colorColor
回退值var(--md-color-on-container)

Controls inactive label color.

--md-item-inactive-state-layer-colorState
回退值var(--md-color-on-container)

Controls inactive state layer color.

--md-item-indicator-collapsed-visual-widthLayout
回退值--dp(12)

Controls indicator collapsed visual width.

--md-item-indicator-shapeShape
回退值var(--md-shape-indicator)

Controls indicator shape.

--md-item-main-padding-blockLayout
回退值--dp(8)

Controls main padding block.

--md-item-main-padding-inlineLayout
回退值--dp(12)

Controls main padding inline.

--md-item-min-heightLayout
回退值--dp(56)

Controls min height.

--md-item-motionMotion
回退值var(--md-easing-spatial)

Controls motion.

--md-item-padding-blockLayout
回退值--dp(8)

Controls padding block.

--md-item-padding-inlineLayout
回退值--dp(8)

Controls padding inline.