列表项组件

shadow

Item（列表项）是构成列表的基本元素，可以包含文本、图标、头像、图片、输入框以及任何原生或自定义的组件。Item 应仅作为 List（列表） 中的行来使用，并与其他 item 共同组成列表。它们支持滑动、删除、排序、编辑等多种交互。

基础用法

默认情况下，item 内的文本左对齐，并在文本宽度超过 item 宽度时自动换行。我们可以通过 Ionic 框架提供的 CSS 工具类来修改此行为，例如在下方示例中使用 .ion-text-nowrap 来禁止换行。更多可用于转换 item 内文本样式的类，请参阅 CSS 工具类文档。

内容类型

虽然列表中的 item 形式多样，但它们通常支持 5 种不同的内容类型：辅助视觉元素、文本、元数据、操作和表单控件。然而，并非所有这些内容类型都应同时使用。以下指南将介绍不同的内容类型，以及如何在应用中正确使用它们。

辅助视觉元素

辅助视觉元素是用于装饰 item 的图标或其他点缀。常见的辅助视觉元素包括 Avatar（头像）、Icon（图标）和 Thumbnail（缩略图）。由于这些内容并非理解 item 意图所必需，通常使用 aria-hidden="true" 对屏幕阅读器隐藏。

如果某个视觉元素是与 item 交互所必需的（例如一个图标按钮），那么它属于 操作，而不是辅助视觉元素。

辅助视觉元素应以一致的方式呈现。这能使每个 item 的信息更容易被解析。

Do

在列表中，将视觉元素统一对齐在同一侧

Don't

不要在同一列表中混合使用不同的对齐方式

在下面的示例中，我们创建了两个带有辅助视觉元素的列表。第一个列表使用图标，第二个列表使用头像。由于这些视觉元素是装饰性的，因此都设置了 aria-hidden="true"。此外，它们都统一放置在 start 插槽中。

文本

文本内容类型包括表单控件标签或其他可见文本。这些文本用于表明 item 的用途。请尽量保持文本简短扼要。

如果你发现需要额外用几句话来解释某个 item 的用途，可以考虑将这些补充说明移到一个位于列表底部的 Note（备注） 中。将该 item 放入独立的列表中，可以清楚地表明文本与哪个项目相关联。

Do

将长文本移到列表外部

Don't

不要试图将长文本塞进一个 item 里

在下面的示例中，我们创建了一个包含不同类型文本的列表。"First Name"（名字）和 "Last Name"（姓氏）标签用于指示在文本输入框中应输入的内容。

开关（Toggle）上的 "Allow Notifications"（允许通知）标签下方有一段额外文本，提示用户可以禁用通知。由于这段文本较短，直接放在了 item 内部。

在该列表下方是另一个列表，其中包含一个文本输入框（textarea）以及一个位于其下、包含长文本的 Note（备注）。将文本输入框放入独立的列表中，是为了明确这段长文本是与该文本输入框关联的，而不是其他字段。

元数据

元数据为 item 提供额外的上下文信息，例如状态文本或计数。像 Badge（徽章） 或 Note（备注） 这类组件是展示元数据的好方式。

限制元数据的数量，只包含最关键的信息。

Do

只添加最重要的元数据

Don't

不要添加过多元数据，以免让用户感到信息过载或困惑。

开发者还应考虑元数据的重要性。根据具体用例，突出显示元数据可能对用户有帮助，也可能会分散他们对更重要信息的注意力。

Do

优先突出最重要的内容。

Caution

被优先突出的元数据可能会分散用户对其他重要内容的注意力。

在下面的示例中，我们创建了两个包含不同类型元数据的列表。第一个列表使用 Note（备注） 来显示每个待办清单中的任务数量。

第二个列表模仿了 iOS 邮件应用，展示了一个收件箱。这个列表使用了自定义元数据，包括 "start" 插槽中的“未读邮件”指示器，以及 "end" 插槽中的时间戳和自定义详情图标。“未读邮件”指示器用蓝色高亮，以吸引用户注意未读邮件，而时间戳则相对不那么显眼。

操作

操作是可交互的元素，激活时会执行某些功能。一个 item 可以在一行内显示多个操作。但开发者应确保每个操作的可点击区域足够大，方便用户操作。

开发者应避免创建嵌套的可交互元素，这会破坏屏幕阅读器的用户体验。例如，如果 ion-item 的 button 属性已设为 true，就应避免在该 item 的主要内容区域内再添加按钮。

可以通过使用 Item Sliding（滑动项） 组件来添加操作。也可以在不使用 Item Sliding 的情况下直接将操作放在 item 内部，但数量应限制在不超过 2 个。

Do

使用 Item Sliding，让用户通过滑动 item 来显示多个操作。

Don't

不要在单个 item 内放置超过 2 个操作。

在下面的示例中，我们创建了一个联系人列表。每个 item 都像一个按钮，旨在点击后进入该联系人的完整详情页。每个 item 还关联了额外的操作，用户可以通过滑动来显示它们。

表单控件

表单控件包括复选框（checkbox）、输入框（input）、单选框（radio）等表单组件。由于屏幕空间限制，列表中的每个 item 通常最多放置两个控件。

像辅助文本或字符计数这样的元数据，不应在列表视图中与表单控件一起使用。如果需要此类元数据，应将表单控件置于列表之外。填充风格的输入框（Filled Inputs）是一种很好的方式，可以在列表外部直观地定义输入框的容器。

Do

将带有元数据的输入框放在列表之外。

Don't

不要将输入框的元数据放在列表内部。

或者，可以将元数据放在列表底部的 Note（备注） 中。

Do

将输入框的元数据放在列表末尾。

Don't

不要将输入框的元数据放在列表内部。

Item 通常不应包含超过两个控件。如果需要更多控件，可以考虑将这些控件添加到一个可以从该 item 访问的 Modal（模态框） 中。

Do

将额外的控件移至可从 item 访问的子菜单中。

Don't

不要在一个 item 内使用超过两个控件。

在下面的示例中，我们创建了一个待办任务列表。每个 item 都有一个复选框和一个输入框。复选框让用户可以将任务标记为完成，输入框则让用户可以更改任务名称。

可点击项

如果 item 设置了 href 或 button 属性，则被视为“可点击”。可点击的 item 在视觉上有一些差异，表明它们可以交互。例如，在 md 模式下，可点击项在激活时会显示涟漪效果（ripple effect）；在 ios 模式下，激活时会有高亮显示，并且默认会显示一个详情箭头。

详情箭头

默认情况下，在 ios 模式下，可点击的 item 会显示一个右箭头图标。要隐藏可点击元素上的右箭头图标，请将 detail 属性设置为 false。如果要在默认不显示右箭头的 item 上显示它，可以将 detail 属性设置为 true。

边框线

默认情况下，item 会显示一条底部内嵌边框。这条边框左侧有内边距（padding），并且不会出现在放置在 "start" 插槽的内容下方。可以通过将 lines 属性设置为 "full" 或 "none" 来分别显示通栏边框或不显示边框。

Item 中的按钮

按钮在 item 内部时，其样式会比在外部时显得更小。若要使按钮尺寸与 item 外部的按钮一致，可将 size 属性设置为 "default"。

Item 中的输入框

主题

颜色

CSS 阴影部分

CSS 自定义属性

使用指南

以下指南将帮助您确保列表项易于理解和使用。

1. Item 应仅在 List（列表） 内部使用。
2. 列表中的 item 应以一致的格式呈现。例如，如果您的 item 都展示装饰性图标，那么这些图标在各项之间的位置应该保持一致。
3. Item 内绝不应渲染嵌套的可交互元素。因为当存在嵌套交互元素时，屏幕阅读器无法正确选择目标交互元素。例如，避免在一个设置了 button="true" 的 ion-item 内部再放置一个按钮。
4. 正确使用内容类型。Item 组件是设计作为 List（列表） 中的一行来使用的，不应将其用作通用的容器。

可访问性

键盘交互

当满足以下任一条件时，<ion-item> 会具有特定的键盘交互行为：

• button 属性设置为 "true"，此时会渲染原生的 <button> 元素。
• href 属性被设置，此时会渲染原生的 <a> 元素。
• routerLink 属性被设置，此时会渲染原生的 <a> 元素。

按键	描述
Tab	将焦点移动到下一个可聚焦元素。
Shift + Tab	将焦点移动到上一个可聚焦元素。

按钮模式

当 <ion-item> 渲染原生的 <button> 元素时，其键盘交互遵循与 button 角色相同的模式：

按键	描述
Enter	激活该 item，触发其 click 事件。如果 item 位于表单内且 type 设置为 "submit"，则会提交该表单。
Space	激活该 item，触发其 click 事件。即使 item 的 type 为 "submit"，也不会提交表单。

链接模式

当 <ion-item> 渲染原生的 <a> 元素时，其键盘交互遵循与 link 角色相同的模式：

按键	描述
Enter	激活该 item，导航到链接指向的页面，或将焦点移动到页面内的目标位置。

属性

button

Description	If true, a button tag will be rendered and the item will be tappable.
Attribute	button
Type	boolean
Default	false

color

Description	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

detail

Description	If true, a detail arrow will appear on the item. Defaults to false unless the mode is ios and an href or button property is present.
Attribute	detail
Type	boolean ｜ undefined
Default	undefined

detailIcon

Description	The icon to use when detail is set to true.
Attribute	detail-icon
Type	string
Default	chevronForward

disabled

Description	If true, the user cannot interact with the item.
Attribute	disabled
Type	boolean
Default	false

download

Description	This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want).
Attribute	download
Type	string ｜ undefined
Default	undefined

href

Description	Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
Attribute	href
Type	string ｜ undefined
Default	undefined

lines

Description	How the bottom border should be displayed on the item.
Attribute	lines
Type	"full" ｜ "inset" ｜ "none" ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

rel

Description	Specifies the relationship of the target object to the link object. The value is a space-separated list of link types.
Attribute	rel
Type	string ｜ undefined
Default	undefined

routerAnimation

Description	When using a router, it specifies the transition animation when navigating to another page using href.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

routerDirection

Description	When using a router, it specifies the transition direction when navigating to another page using href.
Attribute	router-direction
Type	"back" ｜ "forward" ｜ "root"
Default	'forward'

target

Description	Specifies where to display the linked URL. Only applies when an href is provided. Special keywords: "_blank", "_self", "_parent", "_top".
Attribute	target
Type	string ｜ undefined
Default	undefined

type

Description	The type of the button. Only used when an onclick or button property is present.
Attribute	type
Type	"button" ｜ "reset" ｜ "submit"
Default	'button'

事件

No events available for this component.

方法

No public methods available for this component.

CSS 阴影部分

Name	Description
container	The wrapper element that contains the default slot.
detail-icon	The chevron icon for the item. Only applies when detail="true".
inner	The inner wrapper element that arranges the item content.
native	The native HTML button, anchor or div element that wraps all child elements.

CSS 自定义属性

iOS

Name	Description
--background	Background of the item
--background-activated	Background of the item when pressed. Note: setting this will interfere with the Material Design ripple.
--background-activated-opacity	Opacity of the item background when pressed
--background-focused	Background of the item when focused with the tab key
--background-focused-opacity	Opacity of the item background when focused with the tab key
--background-hover	Background of the item on hover
--background-hover-opacity	Opacity of the background of the item on hover
--border-color	Color of the item border
--border-radius	Radius of the item border
--border-style	Style of the item border
--border-width	Width of the item border
--color	Color of the item
--color-activated	Color of the item when pressed
--color-focused	Color of the item when focused with the tab key
--color-hover	Color of the item on hover
--detail-icon-color	Color of the item detail icon
--detail-icon-font-size	Font size of the item detail icon
--detail-icon-opacity	Opacity of the item detail icon
--inner-border-width	Width of the item inner border
--inner-box-shadow	Box shadow of the item inner
--inner-padding-bottom	Bottom padding of the item inner
--inner-padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item inner
--inner-padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item inner
--inner-padding-top	Top padding of the item inner
--min-height	Minimum height of the item
--padding-bottom	Bottom padding of the item
--padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item
--padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item
--padding-top	Top padding of the item
--ripple-color	Color of the item ripple effect
--transition	Transition of the item

MD

Name	Description
--background	Background of the item
--background-activated	Background of the item when pressed. Note: setting this will interfere with the Material Design ripple.
--background-activated-opacity	Opacity of the item background when pressed
--background-focused	Background of the item when focused with the tab key
--background-focused-opacity	Opacity of the item background when focused with the tab key
--background-hover	Background of the item on hover
--background-hover-opacity	Opacity of the background of the item on hover
--border-color	Color of the item border
--border-radius	Radius of the item border
--border-style	Style of the item border
--border-width	Width of the item border
--color	Color of the item
--color-activated	Color of the item when pressed
--color-focused	Color of the item when focused with the tab key
--color-hover	Color of the item on hover
--detail-icon-color	Color of the item detail icon
--detail-icon-font-size	Font size of the item detail icon
--detail-icon-opacity	Opacity of the item detail icon
--inner-border-width	Width of the item inner border
--inner-box-shadow	Box shadow of the item inner
--inner-padding-bottom	Bottom padding of the item inner
--inner-padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item inner
--inner-padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item inner
--inner-padding-top	Top padding of the item inner
--min-height	Minimum height of the item
--padding-bottom	Bottom padding of the item
--padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item
--padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item
--padding-top	Top padding of the item
--ripple-color	Color of the item ripple effect
--transition	Transition of the item

插槽

Name	Description
``	Content is placed between the named slots if provided without a slot.
end	Content is placed to the right of the item text in LTR, and to the left in RTL.
start	Content is placed to the left of the item text in LTR, and to the right in RTL.