List 列表

列表是一种垂直排列的索引，用于展示文本或图片，便于用户快速浏览和访问相关信息。

使用方法

按需导入组件：

import 'mdui/components/list.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';

按需导入组件的 TypeScript 类型：

import type { List } from 'mdui/components/list.js';
import type { ListItem } from 'mdui/components/list-item.js';
import type { ListSubheader } from 'mdui/components/list-subheader.js';

使用示例：

Subheader

Item 1

Item 2

<mdui-list>
  <mdui-list-subheader>Subheader</mdui-list-subheader>
  <mdui-list-item>Item 1</mdui-list-item>
  <mdui-list-item>Item 2</mdui-list-item>
</mdui-list>

示例

文本内容

在 <mdui-list-item> 组件上设置 headline 属性，可以设定列表项的主文本，设置 description 属性，可以设定副文本。

<mdui-list>
  <mdui-list-item headline="Headline"></mdui-list-item>
  <mdui-list-item headline="Headline" description="Supporting text"></mdui-list-item>
</mdui-list>

源码

也可以通过 default slot 设定主文本，通过 description slot 设定副文本。

Headline

Headline Supporting text

<mdui-list>
  <mdui-list-item>Headline</mdui-list-item>
  <mdui-list-item>
    Headline
    <span slot="description">Supporting text</span>
  </mdui-list-item>
</mdui-list>

源码

默认情况下，主文本和副文本无论长度如何，都会完全显示。你可以通过设置 headline-line 和 description-line 属性为主文本和副文本添加行数限制，最多可以限制为 3 行。

Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text

<mdui-list>
  <mdui-list-item headline-line="1" description-line="2">
    Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline
    <span slot="description">Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text</span>
  </mdui-list-item>
</mdui-list>

源码

两侧内容

在 <mdui-list-item> 组件上设置 icon 和 end-icon 属性，可以在列表项的左侧和右侧添加 Material Icons 图标。

Headline

<mdui-list>
  <mdui-list-item icon="people" end-icon="arrow_right">Headline</mdui-list-item>
</mdui-list>

源码

也可以通过 icon 和 end-icon slot 在列表项的左侧和右侧添加元素。

Headline

<mdui-list>
  <mdui-list-item>
    Headline
    <mdui-avatar slot="icon" src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>
    <mdui-checkbox slot="end-icon"></mdui-checkbox>
  </mdui-list-item>
</mdui-list>

源码

链接

通过设置 href 属性，可以将列表项转换为链接。此时，你还可以使用与链接相关的属性，如：download、target 和 rel。

Headline

<mdui-list>
  <mdui-list-item href="https://www.mdui.org" target="_blank">Headline</mdui-list-item>
</mdui-list>

源码

禁用状态

在 <mdui-list-item> 组件上添加 disabled 属性，可以禁用该列表项。此时，列表项中的 checkbox、radio、switch 等组件也会被禁用。

Headline

<mdui-list>
  <mdui-list-item disabled>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

源码

激活状态

在 <mdui-list-item> 组件上添加 active 属性，可以激活该列表项。

Headline

<mdui-list>
  <mdui-list-item active>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

源码

不可点击状态

在 <mdui-list-item> 组件上添加 nonclickable 属性，可以移除列表项上的鼠标悬浮和点击涟漪效果。

Headline

<mdui-list>
  <mdui-list-item nonclickable>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

源码

圆角形状

在 <mdui-list-item> 组件上添加 rounded 属性，可以使该列表项呈现圆角形状。

Headline

<mdui-list>
  <mdui-list-item rounded>Headline</mdui-list-item>
  <mdui-list-item rounded>Headline</mdui-list-item>
</mdui-list>

源码

垂直对齐方式

在 <mdui-list-item> 组件上设置 alignment 属性，可以调整列表项左右两侧元素与列表项的对齐方式。其值可以为：

start：顶部对齐
center：居中对齐
end：底部对齐

Headline

<mdui-list>
  <mdui-list-item alignment="start" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
  <mdui-list-item alignment="center" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
  <mdui-list-item alignment="end" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
</mdui-list>

源码

自定义内容

在 <mdui-list-item> 组件中使用 custom slot，可以完全自定义列表项的内容。

test

<mdui-list>
  <mdui-list-item>
    <div slot="custom" style="display: flex;">
      <mdui-icon name="people"></mdui-icon>
      <div>test</div>
    </div>
  </mdui-list-item>
</mdui-list>

源码

`mdui-list-item` API

属性

HTML 属性	JavaScript 属性	类型	默认值
`headline`	`headline`	`string`	-
主文本。也可以通过 default slot 设置
`headline-line`	`headlineLine`	`1 \| 2 \| 3`	-
主文本行数，超过限制后将截断显示。默认无行数限制。可选值包括： `1`：显示单行，超出后截断 `2`：显示两行，超出后截断 `3`：显示三行，超出后截断
`description`	`description`	`string`	-
副文本。也可以通过 `slot="description"` 设置
`description-line`	`descriptionLine`	`1 \| 2 \| 3`	-
副文本行数，超过限制后将截断显示。默认无行数限制。可选值包括： `1`：显示单行，超出后截断 `2`：显示两行，超出后截断 `3`：显示三行，超出后截断
`icon`	`icon`	`string`	-
左侧的 Material Icons 图标名。也可以通过 `slot="icon"` 设置
`end-icon`	`endIcon`	`string`	-
右侧的 Material Icons 图标名。也可以通过 `slot="end-icon"` 设置
`disabled`	`disabled`	`boolean`	`false`
是否禁用该列表项，禁用后，列表项将变为灰色，且其中的 `<mdui-checkbox>`、`<mdui-radio>`、`<mdui-switch>` 等也将禁用
`active`	`active`	`boolean`	`false`
是否激活该列表项
`nonclickable`	`nonclickable`	`boolean`	`false`
是否使列表项不可点击。设置后，列表项中的 `<mdui-checkbox>`、`<mdui-radio>`、`<mdui-switch>` 等仍可交互
`rounded`	`rounded`	`boolean`	`false`
是否使用圆角形状的列表项
`alignment`	`alignment`	`'start' \| 'center' \| 'end'`	`'center'`
列表项的垂直对齐方式。可选值包括： `start`：顶部对齐 `center`：居中对齐 `end`：底部对齐
`href`	`href`	`string`	-
链接的目标 URL。如果设置了此属性，组件内部将渲染为 `<a>` 元素，并可以使用链接相关的属性。
`download`	`download`	`string`	-
下载链接的目标。 Note：仅在设置了 `href` 属性时，此属性才有效。
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
链接的打开方式。可选值包括： `_blank`：在新窗口中打开链接 `_parent`：在父框架中打开链接 `_self`：默认。在当前框架中打开链接 `_top`：在整个窗口中打开链接 Note：仅在设置了 `href` 属性时，此属性才有效。
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
当前文档与被链接文档之间的关系。可选值包括： `alternate`：当前文档的替代版本 `author`：当前文档或文章的作者 `bookmark`：永久链接到最近的祖先章节 `external`：引用的文档与当前文档不在同一站点 `help`：链接到相关的帮助文档 `license`：当前文档的主要内容由被引用文件的版权许可覆盖 `me`：当前文档代表链接内容的所有者 `next`：当前文档是系列中的一部分，被引用的文档是系列的下一个文档 `nofollow`：当前文档的作者或发布者不认可被引用的文件 `noreferrer`：不包含 `Referer` 头。类似于 `noopener` 的效果 `opener`：如果超链接会创建一个顶级浏览上下文（即 `target` 属性值为 `_blank`），则创建一个辅助浏览上下文 `prev`：当前文档是系列的一部分，被引用的文档是系列的上一个文档 `search`：提供一个资源链接，可用于搜索当前文件及其相关页面 `tag`：提供一个适用于当前文档的标签（由给定地址识别） Note：仅在指定了 `href` 属性时可用。
`autofocus`	`autofocus`	`boolean`	`false`
是否在页面加载完成后自动获取焦点
`tabindex`	`tabIndex`	`number`	-
元素在使用 Tab 键切换焦点时的顺序

方法

名称	参数	返回值
`click`		`void`
模拟鼠标点击元素
`focus`	`options: FocusOptions` (可选)	`void`
将焦点设置到当前元素。可以传入一个对象作为参数，该对象的属性包括： `preventScroll`：默认情况下，元素获取焦点后，页面会滚动以将该元素滚动到视图中。如果不希望页面滚动，可以将此属性设置为 `true`。
`blur`		`void`
移除当前元素的焦点

事件

名称
`focus`
获得焦点时触发
`blur`
失去焦点时触发

Slots

名称
默认
主文本
`description`
副文本
`icon`
列表项左侧的元素
`end-icon`
列表项右侧的元素
`custom`
任意自定义内容

CSS Parts

名称
`container`
列表项容器
`icon`
左侧图标
`end-icon`
右侧图标
`body`
中间部分
`headline`
主标题
`description`
副标题

CSS 自定义属性

名称
`--shape-corner`
列表项的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
`--shape-corner-rounded`
指定了 `rounded` 属性时，列表项的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌

`mdui-list-subheader` API

Slots

名称
默认
列表标题文本

`mdui-list` API

Slots

名称
默认
`<mdui-list-item>` 元素

LinearProgress 线性进度指示器

Menu 菜单