ion-item

shadow

项目（Items）是可以包含文本、图标、头像、图像、输入框以及任何其他原生或自定义元素的组件。项目应仅作为行（rows）与其他项目一起放置在列表（List）中。项目可以被滑动、删除、重新排序、编辑等。

基本用法

当文本宽度超过项目宽度时，项目会左对齐文本并自动换行。我们可以使用 Ionic Framework 提供的 CSS 工具类来修改此行为，例如在下面的示例中使用 .ion-text-nowrap。有关可以添加到项目以转换文本的更多类，请参阅CSS 工具类文档。

内容类型

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

辅助视觉元素

辅助视觉元素是项目的装饰性图标或其他修饰元素。常见的辅助视觉元素示例包括头像（Avatar）、[图标（Icon）](./icon）和[缩略图（Thumbnail）](./thumbnail）。由于此内容对于理解项目的意图不是必需的，因此通常使用 aria-hidden="true" 对屏幕阅读器隐藏。

如果视觉元素需要与项目交互（例如图标按钮），则该视觉元素是操作（action）而不是辅助视觉元素。

辅助视觉元素应以一致的方式呈现。这样可以使每个项目中的信息更容易解析。

Do

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

Don't

不要在同一列表中呈现不同对齐方式的视觉元素

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

文本

文本内容类型包括表单控件标签或其他可见文本。此文本用于表明项目的意图。尽量保持文本简洁明了。

如果你发现需要更多的句子来阐明项目的目的，请考虑将额外的句子移到列表底部的注释（Note）中。将项目放在自己的列表中，可以清楚地表明文本与哪个项目相关联。

Do

将长文本移到列表外部

Don't

不要尝试将长文本放入项目中

在下面的示例中，我们创建了一个包含不同类型文本的列表。“First Name”和“Last Name”标签用于指示在文本输入框中输入什么内容。

切换开关上的“Allow Notifications”标签下方有附加文本，注明用户可以禁用通知。由于此文本较短，因此放置在项目内部。

该列表下方是另一个列表，其中包含一个文本区域（textarea），下方有一个包含长文本的[注释（Note）](./note）。文本区域被放在自己的列表中，以明确长文本与文本区域相关联，而不是与其他字段相关联。

元数据

元数据为项目提供额外的上下文，例如状态文本或计数。[徽章（Badge）](./badge）或[注释（Note）](./note）等组件是显示元数据的好方法。

限制你包含的元数据数量，仅保留最相关的信息。

Do

仅添加最重要的元数据

Don't

不要添加太多元数据，以免让用户不知所措或感到困惑。

开发人员还应考虑元数据的重要性。根据具体用例，吸引对元数据的注意力可能对用户有帮助，或者可能分散他们对更重要信息的注意力。

Do

优先处理最重要的内容。

Caution

优先处理的元数据可能会分散对其他重要内容的注意力。

在下面的示例中，我们创建了两个包含不同类型元数据的列表。第一个列表使用[注释（Note）](./note）来显示每个待办事项列表中有多少任务。

第二个列表模拟 iOS 邮件应用程序来显示收件箱。该列表使用了自定义元数据，包括“start”插槽中的“未读消息”指示器以及“end”插槽中的时间戳和自定义详情图标。“未读消息”指示器以蓝色高亮显示，以吸引用户注意未读消息，而时间戳则更为微妙。

操作

操作是交互式元素，当你激活它们时会执行某些操作。一个项目可以在同一行显示多个操作。但是，开发人员应确保每个操作的点击目标足够大，以便使用。

开发人员应避免创建嵌套交互元素（nested interactives），这可能会破坏屏幕阅读器的用户体验。例如，如果 button 属性设置为 true，开发人员应避免在项目的主要内容中添加按钮。

可以通过使用项目滑动（Item Sliding）组件来添加操作。操作也可以直接放在项目内部，而不使用项目滑动，但这应限制在不超过 2 个操作。

Do

使用项目滑动（Item Sliding）通过在项目上滑动来显示多个操作。

Don't

不要在项目内放置超过 2 个操作。

在下面的示例中，我们创建了一个联系人列表。每个项目都是一个占位按钮，旨在将你带到该项目的完整联系人页面。每个项目都有附加的操作，用户可以通过在项目上滑动来显示这些操作。

控件

控件是表单组件，例如复选框、输入框、单选按钮等。由于屏幕空间限制，列表中的每个项目最多应有两个控件。

不应在列表视图的表单控件上使用元数据，例如帮助文本或字符计数。如果需要此类元数据，应将表单控件放在列表外部。填充输入框（Filled Inputs）是在列表外部视觉定义输入容器的好方法。

Do

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

Don't

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

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

Do

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

Don't

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

项目通常不应超过两个控件。如果需要更多控件，请考虑在可从项目访问的模态框（Modal）中添加额外的控件。

Do

将额外的控件移到可从项目访问的子菜单中。

Don't

不要在项目内使用超过两个控件。

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

可点击项目

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

详情箭头

默认情况下，可点击项目 在 ios 模式下会显示右箭头图标。要隐藏可点击元素上的右箭头图标，请将 detail 属性设置为 false。要在自然不显示右箭头图标的项目上显示该图标，请将 detail 属性设置为 true。

项目线条

项目默认显示一条带内边距的底部边框。该边框在左侧有内边距，并且不会出现在 "start" 插槽中的任何内容下方。lines 属性可以修改为 "full" 或 "none"，分别显示全宽边框或无边框。

项目中的按钮

项目内部的按钮样式比外部的按钮要小。要使按钮大小与项目外部的按钮匹配，请将 size 属性设置为 "default"。

项目输入框

主题定制

颜色

CSS Shadow Parts

CSS 自定义属性

指南

以下指南将有助于确保你的列表项目易于理解和使用。

1. 项目应仅在[列表（List）](./list）内部使用。
2. 列表中的项目应以一致的格式呈现。例如，如果你的项目呈现装饰性图标，则图标应在项目之间以相同的方式定位。
3. 项目不应呈现嵌套交互元素（nested interactives）。当使用嵌套交互元素时，屏幕阅读器无法选择正确的交互元素。例如，避免在设置了 button="true" 的 ion-item 内部放置按钮。
4. 正确使用内容类型。Item 组件设计为[列表（List）](./list）中的一行，不应用作通用容器。

属性

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

counter (deprecated)

Description	If true, a character counter will display the ratio of characters used and the total character limit. Only applies when the maxlength property is set on the inner ion-input or ion-textarea. Deprecated — Use the counter property on ion-input or ion-textarea instead.
Attribute	counter
Type	boolean
Default	false

counterFormatter (deprecated)

Description	A callback used to format the counter text. By default the counter text is set to "itemLength / maxLength". Deprecated — Use the counterFormatter property on ion-input or ion-textarea instead.
Attribute	undefined
Type	((inputLength: number, maxLength: number) => 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

fill (deprecated)

Description	The fill for the item. If "solid" the item will have a background. If "outline" the item will be transparent with a border. Only available in md mode. Deprecated — Use the fill property on ion-input or ion-textarea instead.
Attribute	fill
Type	"outline" ｜ "solid" ｜ 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'

shape

Description	The shape of the item. If "round" it will have increased border radius.
Attribute	shape
Type	"round" ｜ undefined
Default	undefined

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 Shadow Parts

Name	Description
detail-icon	The chevron icon for the item. Only applies when detail="true".
native	The native HTML button, anchor or div element that wraps all child elements.

CSS 自定义属性

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
--highlight-color-focused	The color of the highlight on the item when focused. Only applies to inputs and textareas using the legacy form syntax. DEPRECATED: Highlights can be styled on ion-input or ion-textarea when using the modern form syntax.
--highlight-color-invalid	The color of the highlight on the item when invalid. Only applies to inputs and textareas using the legacy form syntax. DEPRECATED: Highlights can be styled on ion-input or ion-textarea when using the modern form syntax.
--highlight-color-valid	The color of the highlight on the item when valid. Only applies to inputs and textareas using the legacy form syntax. DEPRECATED: Highlights can be styled on ion-input or ion-textarea when using the modern form syntax.
--highlight-height	The height of the highlight on the item. Only applies to inputs and textareas using the legacy form syntax. DEPRECATED: Highlights can be styled on ion-input or ion-textarea when using the modern form syntax.
--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.
error	Content is placed under the item and displayed when an error is detected. DEPRECATED Use the "errorText" property on ion-input or ion-textarea instead.
helper	Content is placed under the item and displayed when no error is detected. DEPRECATED Use the "helperText" property on ion-input or ion-textarea instead.
start	Content is placed to the left of the item text in LTR, and to the right in RTL.