# @3mo/list 中文文档

规范地址：https://npmcn.com/package/%403mo/list/

版本：0\.12\.6
npm 元数据更新时间：2026-10-21T19:53:58.132Z
中文译文更新时间：2026-11-06T17:07:10.963Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%403mo/list
原文对照：https://npmcn.com/package/%403mo/list/?lang=original
项目主页：https://3mo-esolutions.github.io/web-components/?path=/docs/data-list--overview
源码仓库：https://github.com/3mo-esolutions/web-components

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：129 kB，58 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@3mo/flex x，@3mo/icon x，@a11d/lit x，@3mo/radio x，@3mo/theme \>=0\.5\.4，@3mo/switch x，@3mo/checkbox x，@material/web 1\.x，@3mo/focus-ring x，@3mo/indexability \>=0\.3\.0，@3mo/navigability x，@3mo/selectability \>=0\.3\.0，@3mo/focus-controller x，@3mo/disabled-property x，@3mo/mutation-observer x，@3mo/expand-collapse-icon-button x
- 首次发布：2023-02-03T15:07:00.660Z
- 最新版本发布：2026-10-21T19:53:57.675Z
- 近 30 天下载量：2635（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 14 个）

## 中文简介

列表的Web组件有可选择的,复选框,收音机和切换项目,加上ARIA列表框和组合框控制器.

## 安装

```sh
npm install @3mo/list
```

也可以使用：`pnpm add @3mo/list`、`yarn add @3mo/list`、`bun add @3mo/list`

## README

# 列表

列表的Web组件有可选择的,复选框,收音机和切换项目,加上ARIA列表框和组合框控制器.

[![npm](https://img.shields.io/npm/v/@3mo/list?style=flat-square&color=0077c8)](https://www.npmjs.com/package/@3mo/list) [![Documentation](https://img.shields.io/badge/docs-storybook-ff4785?style=flat-square&logo=storybook&logoColor=white)](https://3mo-esolutions.github.io/web-components/?path=/docs/data-list--overview)

项目清单,例如: `mo-list-item`和有收发机、开关或无线电按钮的人.

## 安装

```sh
npm install @3mo/list
```

```ts
import '@3mo/list'
```

## 使用量

```html
<mo-list>
    <mo-list-item icon='inbox'>Inbox</mo-list-item>
    <mo-list-item icon='drafts'>Drafts</mo-list-item>
    <mo-list-item icon='send'>Sent</mo-list-item>
    <mo-list-item icon='delete'>Trash</mo-list-item>
</mo-list>
```

## 实例

-   [内容](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--content) - 某个项目在它之后保留任何内容 `icon`,例如其末尾的快捷键,以及带有 `role='separator'` 将各组分隔开.
-   [已禁用](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--disabled) A级 `disabled` 项淡出并忽略了按;其中的一个元素仍然可以带它们 `pointer-events: auto`。 。 。 .
-   [子网格布局](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--subgrid-layout) - 作为网格列出的清单,其物品经过其栏杆 `subgrid` 上行所有项目的图标、标签和快捷键.
-   [复选框项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--checkbox-items) —— 说 `mo-checkbox-list-item` 使整个项目成为其复选框的标签.
-   [切换项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--switch-items) —— 说 `mo-switch-list-item` 对开关也一样.
-   [无线电项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--radio-items) —— 说 `mo-radio-list-item` 对收音机按钮也一样.
-   [选择控制对齐](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--selection-control-alignment) —— 说 `selectionControlAlignment='start'` 将控件放在内容之前而不是其结尾.
-   [可选择的项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--selectable-items) A级 `toggleable` 可选项目由新闻界选择和取消,并按其背景显示其状态.
-   [可折叠的项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--collapsible-items) —— 说 `mo-collapsible-list-item` 打开它 `details` 在它所持有的项目之下,任何深度.
-   [可选择列表](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--selectable-list) —— 说 `mo-selectable-list` 在其所有可选项目上保留一个选择,无论其控制如何,作为指数 `value`;箭头键在它们之间移动.
-   [可选择的可折叠项目](https://3mo-esolutions.github.io/web-components/?path=/story/data-list--selectable-collapsible-items) —— 相撞物中的可选项目也加入列表的选择; 这里 `:has()` 概述持有该证书的团体.

### 组合框

-   [默认](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-combobox--default) ——QQ或QQ在所选国家上打开列表并 Esc 关闭;每个新过滤器使其第一次匹配激活,所以 Enter 把它拿走.
-   [弹出搜索](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-combobox--search-in-popup) ——一个按钮打开了带有自己搜索框的弹出,即组合框.

### 列表框

-   [默认](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--default) —— 标签,然后是箭头、家、端并输入名称移动; 空格或输入选择.
-   [选择焦点](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--selection-follows-focus) —— 说 `selectionFollowsFocus` 选择箭头到达的选项,作为几个选项的单选列表框.
-   [水平](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--horizontal) —— 说 `orientation: 'horizontal'` 与 qq 和 qq 一起移动,它们遵循写入方向.
-   [多个选择](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--multiple-selection) — 空格或点击切换一个选项, Shift+row和Shift+ 空间扩展范围, Ctrl+Shift+ Home 或 End 选择为任意一端, Ctrl+A 选择全部或无.
-   [按键过滤](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--filter-as-you-type) - 已经 `combobox`中,焦点保留在输入中,并且通过元素引用来宣布活动选项; Home, End, QQ and → stay the 输入.
-   [分组](https://3mo-esolutions.github.io/web-components/?path=/story/behaviors-listbox--grouped) ——标签组中的选项:箭头从一个组直跑到下一个组,而屏幕读取器在每个组内计数.

## 无障碍

### `mo-list`

A 类 `list` 联 合 国 `listitem`s:每件物品都是个制表站,和 `Enter` 财务报告和审定财务报表 `Space` 点击它。 用于选择所用物品 `mo-selectable-list`页:1 [列表框](https://3mo-esolutions.github.io/web-components/?path=/docs/behaviors-listbox--overview)。 。 。 . `ArrowRight` 打开一个 `mo-collapsible-list-item` 财务报告和审定财务报表 `ArrowLeft` 关闭它。 它没有宣布它是否尚未打开,而两个密钥不会以从右到左的语言互换.

### `ListboxController`

名单是 `listbox`,与 `aria-multiselectable` 复数和 `aria-orientation='horizontal'` 当水平. 每个选项都是 `option` 与 `aria-selected`,以及 `aria-disabled` 被禁用时. Focus roves: Tab在第一个选择的选项上着陆,其他在第一个选项上着陆. 箭头不选择就移动, 除非 `selectionFollowsFocus` 在单项选择中移动时选择.

| 密钥 | 对 |
| --- | --- |
| `ArrowDown` `ArrowUp` | 下一个或以前的选项; `ArrowRight` 财务报告和审定财务报表 `ArrowLeft` 当水平. |
| `Home` `End`, (中文(简体) ), `PageUp` `PageDown` | 第一种或最后一种选择,或再加一页. |
| 一封信 | 类型头. |
| `Space` `Enter` | 选择选项, 如单击一样; 在多次时切换. |
| `Shift` +一箭头 | 多重:从开始的地方移动并扩展选择. |
| `Ctrl` `Shift` `Home` 编号 : `End` | 多重:从选项选择第一个或最后一个选项. |
| `Ctrl` `A` | 多: 选择全部, 或者全部选择时不选择 . |

列表名称 `aria-label` 或者说 `aria-labelledby`。 。 。 .

### `ComboboxController`

输入是一个 `combobox` 与 `aria-expanded` 财务报告和审定财务报表 `aria-controls` 指向列表框,其选项遵循 [列表框](https://3mo-esolutions.github.io/web-components/?path=/docs/behaviors-listbox--overview) 模式. 焦点留在输入中: 活动选项由 `aria-activedescendant`,设置为元素参考,从而在另一个阴影根中达到选项,并获得 `data-keyboard-focus` 这样它就可以显示一个焦点环.

| 密钥 | 对 |
| --- | --- |
| `ArrowDown` `PageDown` | 关闭:打开选定的选项, 否则打开第一个选项 . |
| `ArrowUp` `PageUp` | 关闭: 在选中的选项上打开, 否则在最后一个选项上打开 . |
| `Home` `End`, (中文(简体) ), `Enter` `Space` | 关闭, 如果输入不需要打字: 在第一个或最后一个选项上打开 `Home` 财务报告和审定财务报表 `End`,在选中的 `Enter` 财务报告和审定财务报表 `Space`。 。 。 . |
| `ArrowDown` `ArrowUp` | 打开:下一个或上一个选项. |
| `Home` `End` | 打开:第一个或最后一个选项;在一个需要打字的输入中,它们会移动护身符取而代之. |
| 一封信 | 类型头,或过滤选项的打字. |
| `Enter` | 选择活动选项并关闭; `Space` 输入时也不打字. |
| `Escape` `Tab` | 关闭; `Tab` 动作也集中注意力. |

指定输入和列表框,例如在可见标签后.

另一弹出 占据列表框的位置通过 `popup`: 树上作为输入的控件 `combobox`,用于 选项嵌入到其他选项下。 它的钥匙和作用是树自己的.

## API 密码

### `mo-list`

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `itemsChange` | `HTMLElement[]` | 清单项目更改时发出 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 列表项目. |

### `mo-checkbox-list-item`

带有复选框的列表项, 可以在项目切换的任何地方按 .

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `selectionControlAlignment` | `selectionControlAlignment` | `"start" | "end"` | `"end"` | 复选框相对于列表项内容的对齐 |
| `selected` | `selected` | `CheckboxSelection` | `false` | 复选框的值 |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |
|  | `indeterminate` |  |  | 复选框是否不确定 |

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `change` |  | 当复选框值改变时发出 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

### `mo-collapsible-list-item`

打开下方嵌入项的列表项 .

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `open` | `open` | `boolean` | `false` | 列表项目是否打开 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 父列表项目 |
| `details` | 嵌入式列表项目 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `summary` | 母列表项目的主机摘要元素 |
| `details` | 隐藏列表项的详细内容 |
| `expand-collapse-icon-button` | 扩展/缩放图标按钮 |

### `mo-list-item`

列表中的一个项目,其内容前有可选图标.

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

### `mo-list-item-ripple`

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `disabled` | `disabled` | `boolean` | `false` | 是否禁用波纹 |

### `mo-navigation-list-item`

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

### `mo-radio-list-item`

带有收音机按钮的列表项目, 由任何地点的媒体选择 .

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `name` | `name` | `string | undefined` |  | 电台名称 |
| `selectionControlAlignment` | `selectionControlAlignment` | `"start" | "end"` | `"end"` | 电台相对于列表项目内容的调整 |
| `selected` | `selected` | `boolean` | `false` | 是否选中收音机 |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `change` |  | 无线电值变化时发出 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

### `mo-selectable-list`

列表,按其指数对可选项目保留一个选择,以他们控制为准.

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `selectability` | `selectability` | `Selectability` | `"single"` | 清单的可选性 |
| `value` | `value` | `number[]` | `"new Array<number>()"` | 选定的列表项目索引 |

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `change` | `number[]` | 选定列表项目更改时发送 |
| `itemsChange` | `HTMLElement[]` | 清单项目更改时发出 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 列表项的默认位置 |

### `mo-selectable-list-item`

以背景显示的媒体选择的列表项目 .

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `toggleable` | `toggleable` | `boolean` | `false` | 是否可以切换列表项选择 |
| `selected` | `selected` | `boolean` | `false` | 是否选中列表项 |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `change` |  | 选定或取消列表项时发送 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

### `mo-switch-list-item`

带有切换器的列表项目, 可以在任意位置按下此项目切换 .

#### 属性

| 名称 | 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `selectionControlAlignment` | `selectionControlAlignment` | `"start" | "end"` | `"end"` | 切换器相对于列表项内容的对齐 |
| `selected` | `selected` | `boolean` | `false` | 是否选中开关 |
| `disabled` | `disabled` | `boolean` | `false` | 列表项是否禁用 |
| `icon` | `icon` | `MaterialIcon | undefined` |  | 在列表项中显示的图标 |
| `preventClickOnSpace` | `preventClickOnSpace` | `boolean` | `false` | 列表项目是否应防止点击空间 |

#### 活动

| 名称 | 细节 | 说明 |
| --- | --- | --- |
| `change` |  | 切换值变化时发出 |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| (默认) | 内容默认槽 |

#### 中央支助部分

| 名称 | 说明 |
| --- | --- |
| `icon` | 内容前的图标. |

## 链接

-   [文档](https://3mo-esolutions.github.io/web-components/?path=/docs/data-list--overview)
-   [更改日志](https://3mo-esolutions.github.io/web-components/?path=/docs/data-list--overview)
-   [来源](https://github.com/3mo-esolutions/web-components/tree/main/packages/List)

## 许可证

麻省理工学院 3MO GmbH

## 常见问题

### @3mo/list 是什么？

列表的Web组件有可选择的,复选框,收音机和切换项目,加上ARIA列表框和组合框控制器\.

### 如何安装 @3mo/list？

在项目目录运行 npm install @3mo/list，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@3mo/flex（x）、@3mo/icon（x）、@a11d/lit（x）、@3mo/radio（x）、@3mo/theme（\>=0\.5\.4）、@3mo/switch（x）、@3mo/checkbox（x）、@material/web（1\.x）、@3mo/focus-ring（x）、@3mo/indexability（\>=0\.3\.0）、@3mo/navigability（x）、@3mo/selectability（\>=0\.3\.0）、@3mo/focus-controller（x）、@3mo/disabled-property（x）、@3mo/mutation-observer（x）、@3mo/expand-collapse-icon-button（x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @3mo/list 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @3mo/list 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @3mo/list 可以商用吗？

@3mo/list 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @3mo/list 的下载量有多少？

根据 npm 官方下载统计，@3mo/list 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,635 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @3mo/list 还在维护吗？

最新版本 0\.12\.6 发布于 2026/10/22（17 天前）；至今共发布 79 个版本，其中过去 12 个月发布了 14 个；首次发布于 2023/02/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。