メインコンテンツまでスキップ
バージョン: v8

ion-item

shadow

アイテムは、テキスト、アイコン、アバター、画像、Input、その他のネイティブまたはカスタム要素を含むことができる要素です。アイテムは他のアイテムと一緒にリストの行としてのみ使用してください。アイテムはスワイプ、削除、並び替え、編集などができます。

基本的な使い方

アイテムはテキストを左寄せにし、テキストがアイテムより幅が広い場合は省略記号を追加しています。この動作は、Ionic Framework が提供する CSS Utilities を使って変更することができます。例えば、以下の例では .ion-text-nowrap を使っています。テキストを変換するためにアイテムに追加できる他のクラスについては、CSS Utilities Documentation を参照してください。

コンテンツの種類

リスト内のアイテムは様々な形をとりますが、一般的にビジュアル、テキスト、メタデータ、アクション、コントロールの5つの異なるコンテンツタイプをサポートします。しかし、これらのコンテンツタイプをすべて同時に使うべきではありません。以下のガイドでは、異なるコンテンツタイプと、アプリケーションでの適切な利用方法を示します。

補助ビジュアル

補助ビジュアル 補助ビジュアルはアイテムの装飾アイコンやその他の飾りです。サポーティングビジュアルの一般的な例は、アバターアイコンサムネイルです。このコンテンツはアイテムの意図を理解するために必要ではないので、通常aria-hidden="true"を使ってスクリーンリーダーから隠されます。

アイコン・ボタンのように、アイテムとのインタラクションにビジュアルが必要な場合、そのビジュアルはサポート・ビジュアルではなく、 アクション となります。

Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse.

A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line.
Do

Align visuals on the same side in a list

A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line
Don't

Don't render visuals with different alignments in the same list

下の例では、ビジュアルをサポートする2つのリストを作成しています。最初のリストはアイコンを使い、2番目のリストはアバターを使います。ビジュアルは装飾的なものなので、すべて aria-hidden="true" を指定しています。さらに、これらは start スロットで一貫して表示されます。

テキスト

テキスト・コンテンツ・タイプには、フォーム制御ラベルやその他の可視テキストが含まれます。このテキストは項目の意図を示す役割を果たします。テキストは短く、要点をまとめるようにしてください。

If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a Note at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.

A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list.
Do

Move long text outside of the list

A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item.
Don't

Don't try to fit long text in an item

下の例では、さまざまなタイプのテキストでリストを作成しています。"First Name"と "Last Name "のラベルは、テキスト入力に何を入力すべきかを示しています。

トグルの "Allow Notifications"ラベルの下には、ユーザーが通知を無効にできることを示すテキストが追加されています。このテキストは短いので、アイテムの内側に配置されています。

そのリストの下には、 Note の下に長いテキストを含むtextareaを含む別のリストがあります。textareaは、長いテキストが他のフィールドではなく、textareaに関連付けられていることを明らかにするために、それ自身のリストに配置されました。

メタデータ

メタデータは、ステータステキストやカウントのようなアイテムの追加コンテキストを提供します。Badge](./badge)やNoteのようなコンポーネントは、メタデータを表示する素晴らしい方法です。

Limit the amount of metadata you include to only the most relevant information.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.
Do

Add only the most important metadata

A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today.
Don't

Don't add too much metadata as it can overwhelm or confuse the user.

Developers should also consider how important the metadata is. Drawing attention to the metadata may be helpful for the user or it may distract them from the more important information depending on the use case.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.
Do

Prioritize the most important content.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list.
Caution

Prioritized metadata may distract from other important content.

以下の例では、異なる種類のメタデータを持つ2つのリストを作成している。最初のリストはNoteを使って、それぞれのToDoリストにいくつのタスクがあるかを表示している。

つ目のリストは、iOSのメールアプリを真似て受信トレイを表示しています。このリストでは、"開始"スロットに "未読メッセージ"インジケータ、"終了"スロットにタイムスタンプとカスタム詳細アイコンを含むカスタムメタデータを使用しています。"未読メッセージ"インジケータは、未読メッセージにユーザーの注意を引くために青くハイライトされ、タイムスタンプはより控えめです。

アクション

アクションは、アクティブにすると何かをするインタラクティブな要素です。アイテムは1行に複数のアクションを表示することができます。しかし、開発者は、各アクションのタップターゲットが十分に大きいことを確認する必要があります。

開発者は、入れ子になったインタラクティブ機能を作成することは避けるべきです。例えば、 button プロパティが true に設定されている場合、開発者はアイテムのメインコンテンツ内にボタンを追加することを避けるべきです。

Actions can be added by using the Item Sliding component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.

A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item.
Do

Use an Item Sliding to reveal multiple actions by swiping on the Item.

A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off.
Don't

Don't put more than 2 actions within an Item.

下の例では、連絡先のリストを作成しています。各項目は、その項目の完全な連絡先ページに移動するためのスタブボタンです。各項目には、ユーザーが項目をスワイプすることで表示できる追加アクションがあります。

コントロール

コントロールは、チェックボックス、入力、ラジオなどのフォームコンポーネントです。リスト内の各項目は、画面スペースの制約上、最大でも2つのコントロールを持つ必要があります。

Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. Filled Inputs are a great way of visually defining the input container outside of a list.

There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with.
Do

Place inputs with metadata outside of the list.

There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with.
Don't

Don't put metadata for inputs in the list.

Alternatively, the metadata can be placed in a Note at the bottom of the list.

There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.
Do

Place metadata for inputs at the end of a list.

There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.
Don't

Don't put metadata for inputs in the list.

Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a Modal that is accessible from the item.

There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.
Do

Move additional controls to a submenu accessible from the item.

There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.
Don't

Don't use more than two controls within an item.

以下の例では、ToDoタスクのリストを作成しています。それぞれの項目にはチェックボックスと入力があります。チェックボックスはユーザーがタスクを完了としてマークできるようにし、入力はユーザーがタスクの名前を変更できるようにします。

クリック可能なItems

hrefbutton プロパティが設定されている場合、itemは "clickable(クリック可能)" と見なされます。clickableなitemsには、インタラクティブに操作できることを示す視覚的な違いがいくつかあります。たとえば、clickableなitemは、md modeではrippleエフェクトを持ち、ios modeではハイライト表示され、ios modeでの detail arrow が表示されます。

Detail Arrows

デフォルトでは、clickableなitems は、ios modeで右矢印アイコンを表示します。clickableな要素の右矢印アイコンを非表示にするには、 detail プロパティを false に設定します。自動的に表示されない項目に右矢印アイコンを表示するには、detailプロパティを true に設定します。

Item Lines

アイテムはデフォルトで下部のボーダーを挿入して表示します。ボーダーは左側にパディングを持ち、 "start" スロットにスロットされたコンテンツの下に表示されることはありません。 lines プロパティを "full" または "none" に変更すると、それぞれ全幅のボーダーが表示され、ボーダーを表示しないようになります。

Buttons in Items

Buttonsは、アイテムの外側にあるときよりも、アイテムの内側にあるときの方が小さくスタイルされます。ボタンのサイズをアイテムの外側のボタンと同じにするには、size属性に"default"を設定します。

Item Inputs

テーマ

Colors

CSS Shadow Parts

CSSカスタムプロパティ

ガイドライン

以下のガイドラインは、リスト項目を理解しやすく、使いやすくするのに役立ちます。

  1. アイテムは Lists の中だけで使用してください。
  2. リスト内のアイテムは、一貫したフォーマットで表示されるべきです。例えば、アイテムに装飾的なアイコンを表示する場合、アイコンはアイテム間で同じように配置されるべきです。
  3. アイテムは決して入れ子になったインタラクティヴをレンダリングすべきではありません。入れ子になったインタラクティブ要素が使用されている場合、スクリーンリーダーは正しいインタラクティブ要素を選択することができません。例えば、button="true"を持つion-itemの中にボタンを置くことは避けてください。
  4. コンテントタイプ](#content-types)を正しく使用してください。Itemコンポーネントは、List内の行として設計されており、汎用コンテナとして使用すべきではありません。

プロパティ

button

DescriptionIf true, a button tag will be rendered and the item will be tappable.
Attributebutton
Typeboolean
Defaultfalse

color

DescriptionThe 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.
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined
Defaultundefined

detail

DescriptionIf 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.
Attributedetail
Typeboolean | undefined
Defaultundefined

detailIcon

DescriptionThe icon to use when detail is set to true.
Attributedetail-icon
Typestring
DefaultchevronForward

disabled

DescriptionIf true, the user cannot interact with the item.
Attributedisabled
Typeboolean
Defaultfalse

download

DescriptionThis 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).
Attributedownload
Typestring | undefined
Defaultundefined

href

DescriptionContains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
Attributehref
Typestring | undefined
Defaultundefined

lines

DescriptionHow the bottom border should be displayed on the item.
Attributelines
Type"full" | "inset" | "none" | undefined
Defaultundefined

mode

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" | "md"
Defaultundefined

rel

DescriptionSpecifies the relationship of the target object to the link object. The value is a space-separated list of link types.
Attributerel
Typestring | undefined
Defaultundefined

routerAnimation

DescriptionWhen using a router, it specifies the transition animation when navigating to another page using href.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) | undefined
Defaultundefined

routerDirection

DescriptionWhen using a router, it specifies the transition direction when navigating to another page using href.
Attributerouter-direction
Type"back" | "forward" | "root"
Default'forward'

target

DescriptionSpecifies where to display the linked URL. Only applies when an href is provided. Special keywords: "_blank", "_self", "_parent", "_top".
Attributetarget
Typestring | undefined
Defaultundefined

type

DescriptionThe type of the button. Only used when an onclick or button property is present.
Attributetype
Type"button" | "reset" | "submit"
Default'button'

イベント

No events available for this component.

メソッド

No public methods available for this component.

CSS Shadow Parts

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

CSSカスタムプロパティ

NameDescription
--backgroundBackground of the item
--background-activatedBackground of the item when pressed. Note: setting this will interfere with the Material Design ripple.
--background-activated-opacityOpacity of the item background when pressed
--background-focusedBackground of the item when focused with the tab key
--background-focused-opacityOpacity of the item background when focused with the tab key
--background-hoverBackground of the item on hover
--background-hover-opacityOpacity of the background of the item on hover
--border-colorColor of the item border
--border-radiusRadius of the item border
--border-styleStyle of the item border
--border-widthWidth of the item border
--colorColor of the item
--color-activatedColor of the item when pressed
--color-focusedColor of the item when focused with the tab key
--color-hoverColor of the item on hover
--detail-icon-colorColor of the item detail icon
--detail-icon-font-sizeFont size of the item detail icon
--detail-icon-opacityOpacity of the item detail icon
--inner-border-widthWidth of the item inner border
--inner-box-shadowBox shadow of the item inner
--inner-padding-bottomBottom padding of the item inner
--inner-padding-endRight padding if direction is left-to-right, and left padding if direction is right-to-left of the item inner
--inner-padding-startLeft padding if direction is left-to-right, and right padding if direction is right-to-left of the item inner
--inner-padding-topTop padding of the item inner
--min-heightMinimum height of the item
--padding-bottomBottom padding of the item
--padding-endRight padding if direction is left-to-right, and left padding if direction is right-to-left of the item
--padding-startLeft padding if direction is left-to-right, and right padding if direction is right-to-left of the item
--padding-topTop padding of the item
--ripple-colorColor of the item ripple effect
--transitionTransition of the item

Slots

NameDescription
``Content is placed between the named slots if provided without a slot.
endContent is placed to the right of the item text in LTR, and to the left in RTL.
startContent is placed to the left of the item text in LTR, and to the right in RTL.