MessageList

差出人・件名・本文の冒頭・時刻を並べた受信の一覧です。

使いどころ

  • 受信箱や通知の一覧のように、連絡を差出人・件名・書き出し・時刻で並べ、一件を開かせる時に使います。
  • 開いた連絡の本文や会話を見せる時は Message、連絡ではない一件ずつの物を並べる時は DataList を使います。

使い方

items に id・sender・title と、任意の href・preview・time・datetime・avatar・unread を渡します。行は「件名」と「差出人 – 書き出し」の二段で、時刻と未読の点を末尾側に置き、行の間に行の幅いっぱいの罫線を引きます。件名は青緑の太字に1pxの下線を引き(行にホバーすると赤)、差出人は黒、書き出しは灰色、時刻は茶色の文字です。unread の行は差出人も太字にし、時刻の後ろに青緑の小さな点を置きます。href を渡した行はリンクにし、ホバーすると行を淡い黄色で塗ります。省略した行はリンクにしません。

件名と差出人が空の時は「(件名なし)」「差出人不明」を出します。どれかの行に avatar があれば全ての行にアバターの列を設け、avatar の無い行には同じ大きさ(30px)の淡い灰色の円に手紙のアイコンを置いて列をそろえます。threadCount(2以上)は件名の後ろに件数のピル(淡い青に青緑の数)で、attachments(1以上)はファイルのアイコンと灰色の小さな数で添えます。

行ごとの state は件名の前に共通の Badge で示します。draft は「下書き」、sending は「送信中」で行全体を少し控えめにし、failed は赤の「送信失敗」です。unavailableReason を渡すと state より優先して「閲覧不可」のバッジを出し、書き出しの位置に理由を出して、件名と差出人を灰色にします。current の行は黄色のハイライト(#ffffcc)で示します。面は角を丸めず、行の幅いっぱいに塗ります。

previewLines は、1 で差出人と書き出しを一行に並べて省略し、2 で差出人の下に書き出しを二行まで折り返します。newSince に行の id を渡すと、その行の直前に青緑の細い区切りの線とラベル(既定は「ここから新着」)を置きます。

一覧全体の state は ready・loading・error です。loading と error では行を出さず、一覧の場所に状態の文を出します(loading は文の上に、行の形をした淡い面を二つ並べます。面は動きません)。ready で items が0件の時は empty を EmptyState で出します。0件の表示は、行を後から DOM へ追加すると隠れ、全て消すと再び現れます。

幅が30rem未満では時刻を件名の行に置き、件名を二行まで折り返します。16rem未満ではアバター・件名・書き出し・時刻を縦に積みます。

既読・送信・削除などのデータ処理と、開いた行の current の切り替えは利用側が持ちます。controllerを持たないので、JavaScriptなしでも行のリンクで開けます。

アクセシビリティ

  • ルートは label を名前に持つ ul です。行のリンクは件名・差出人・書き出し・時刻をまとめて読み上げます。
  • current の行のリンクには aria-current="page" を付けます。未読は読み上げ用の「未読」を添え、会話の件数と添付の数は、見える数を読み上げから外し、「4件の会話」「添付ファイル2件」の文を読み上げ用に添えます。
  • 差出人のアバターは読み上げから外します。状態の文と0件の表示は一覧の項目の中の role="status" で、loading では aria-busy="true" を付けます。
  • newSince の区切りは一覧の一項目で、ラベル(既定は「ここから新着」)を読み上げます。一覧の直下の li には項目以外の役割を付けません。

API

MessageList

MessageListのprops
名前型既定値説明
label必須string一覧の名前。ulのaria-labelに入れる。
items必須readonly MessageListItem[]並べる連絡。並び順と絞り込みは利用側で決める。
state"ready" | "loading" | "error""ready"一覧全体の状態。loadingとerrorでは行を出さず、一覧の場所に状態の文を出す。loadingではaria-busyを付ける。
stateContentChild状態の文の代わりに出す内容。readyでは0件の時の表示(empty)の代わりになる。
previewLines1 | 21書き出しの行数。1は差出人と書き出しを一行に並べ、2は差出人の下で書き出しを二行まで折り返す。
newSince{ id: string; label?: string; }この項目の直前に区切りの線とラベルを置き、ここから新しいことを示す。
empty{ title: string; description?: Child; kind?: EmptyStateProps["kind"]; }{ title: "連絡はまだありません" }連絡が一件もない時の表示。EmptyStateで描く。行を後から出し入れしても、行が一つもない時だけ見える。既定は「連絡はまだありません」。

ほかに、<ul>へ標準のHTML属性を渡せます。

読み込むCSS:layers.css、reset.css、tokens.css、base.css、layout.css、components/message-list.css、components/badge.css、components/empty-state.css、components/icon.css、components/divider.css

newSinceの項目

newSinceの項目
名前型既定値説明
id必須string区切りを置く項目のid。この項目の直前に線とラベルを置く。一致する項目が無ければ何も置かない。
labelstring区切りのラベル。既定は「ここから新着」。

emptyの項目

emptyの項目
名前型既定値説明
title必須string空の時の題名。
descriptionChild題名の下に添える説明。
kindEmptyStateProps["kind"]EmptyStateの場面(empty・start・complete)。

MessageListItem

MessageListItem
名前型既定値説明
id必須string連絡を識別する値。行のdata-message-idに入れ、newSinceの位置合わせにも使う。
sender必須string差出人の名前。空白だけの時は「差出人不明」と出す。
title必須string件名。空白だけの時は「(件名なし)」と出す。一行に収まらない分は省略する(幅が30rem未満では二行まで折り返す)。
previewstring本文の書き出し。差出人の後ろに続け、previewLinesの行数に収まらない分は省略する。
hrefstring行を開く移動先。省略すると行はリンクにならない。
timestring行の末尾に出す時刻の文字。書式は利用側で決める。
datetimestringtimeに対応する機械可読の日時。日時として読める値の時だけtime要素にする。
avatarChild差出人のアバター(Avatarなど)。一覧のどれかの行に渡すと全ての行にアバターの列を設け、無い行には手紙のアイコンを置く。
unreadboolean未読。差出人を太字にし、時刻の後ろに青緑の点と読み上げ用の「未読」を添える。
currentboolean今開いている連絡。行を黄色のハイライトで塗り、aria-current="page"を付ける。
threadCountnumber会話の件数。2以上の時だけ件名の後ろに数を出す。
attachmentsnumber添付ファイルの数。1以上の時だけ件名の後ろにファイルのアイコンと数を出す。
state"draft" | "sending" | "failed"送信の状態。件名の前にバッジを置く(draftは「下書き」、sendingは「送信中」で行を控えめに、failedは赤い「送信失敗」)。
unavailableReasonstring閲覧できない理由。指定するとstateより優先して「閲覧不可」のバッジを出し、書き出しの位置に理由を出す。

EmptyStateProps

EmptyStateのpropsと同じです。

コード

HTML
Hono JSX