List 列表
列表按稳定顺序呈现同类对象摘要,适合扫描、进入详情或执行少量行级动作,不强调跨列精确比较。
数据与任务边界
列表适合按稳定顺序扫描同类对象、进入详情和执行少量项目级命令。排序、分页和返回位置共同定义阅读连续性;其中任一项不稳定都会产生重复项目、遗漏项目或返回后位置丢失。
前置知识:ul/ol/li、链接与按钮、稳定排序、游标分页、历史记录和滚动容器。
数据模型
{
"queryId": "tickets-priority",
"order": [
"priority:desc",
"updatedAt:desc"
],
"cursor": "next-42",
"items": [
{
"id": "ticket-731",
"title": "支付失败",
"status": "open",
"priority": "p1"
}
],
"hasMore": true
}queryId 或查询指纹标识筛选与排序条件,cursor 只能在同一查询上继续。项目 id 用于去重、实时合并和恢复锚点;hasMore 来自服务端分页结果,不能用“本页数量等于页容量”猜测。
工作机制
- 集合使用 ul/ol 与 li 表达无序或有序关系。
- 每项有稳定 ID、主标题、摘要、状态和少量操作。
- 顺序依据优先级、时间或人工排序,不能只靠视觉位置。
- 列表项进入详情使用链接,行级动作使用独立按钮。
- 分页、加载更多和无限滚动分别定义历史与返回位置。
- 空、加载、失败、无权限和没有更多分开。
- 删除或插入项目时保持焦点与阅读位置。
- 本地乐观更新与服务端确认使用不同状态。
flowchart LR
Q["筛选与稳定排序"] --> P1["首批项目 + 游标"]
P1 --> P2["加载下一批并按 ID 去重"]
P2 --> A["记录可见锚点"]
A --> D["进入项目详情"]
D --> H["返回并恢复查询、页面与锚点"]交互规则
- 筛选和排序写入可恢复 URL。
- 加载更多保留已有项和焦点,不重排已阅读内容。
- 返回列表恢复查询、滚动位置和选中上下文。
- 多选出现后显示作用范围与已选数量。
- 长标题换行,不用 tooltip 承载唯一信息。
- 刷新时按对象 ID 合并,不用数组位置覆盖。
List 列表状态
| 状态 | 专属行为 |
|---|---|
| 首次加载 | 列表框架与查询可见 |
| 加载更多 | 保留已有项和焦点 |
| 无更多 | 明确集合结束 |
| 实时更新 | 稳定ID合并,不夺走阅读位置 |
| 返回恢复 | 查询、滚动和选中上下文恢复 |
| 离线 | 本地项与未同步状态分开 |
案例 1:客服按优先级处理工单队列
约束与输入
- 200 个开放工单;P1 在前;状态实时变化。
- 客服从列表进入详情,处理后返回下一项。
处理过程
- 服务端排序规则包含优先级和更新时间。
- 每项显示标题、客户、SLA 与状态。
- 详情返回恢复查询与原位置。
- 工单被他人领取时就地更新并播报。
- 处理成功后根据排序规则移动或移除该项。
失败分支
实时更新把当前焦点项目移走,焦点退到 body。修正为延迟重排到用户完成操作,并保留稳定焦点目标。
专属验证
- 构造相同更新时间的 P1 工单,以稳定 ID 作为最终平局键,连续翻页不得重复或遗漏。
- 从第 73 个工单进入详情并返回,原查询、已加载页和该工单相对视口位置应恢复。
- 当前焦点工单被他人领取时先原位更新状态;用户完成操作后再按队列规则移动。
- 处理成功移除当前项后,焦点落在原位置的下一张工单;若没有下一项则落到上一项。
案例 2:移动端浏览离线下载任务
约束与输入
- 15 个下载;部分离线;任务有进度和错误。
- 用户需要暂停、继续和删除。
处理过程
- 每项显示文件名、大小、进度与真实状态。
- 暂停和继续是按钮,不让整项同时可点击。
- 离线时允许查看本地任务但标记未同步。
- 重新联网后按任务 ID 对账。
- 删除已下载文件前说明本地与云端影响。
失败分支
无限加载历史任务没有结束标识,键盘用户无法到达页面后续内容。改为分页或提供明确“加载更多”按钮。
专属验证
- 断网后 15 个任务仍显示本地文件名、已下载字节和暂停状态,远端未确认动作有明确标记。
- 快速点击暂停再继续时,只接纳最新请求版本,迟到的暂停响应不能覆盖“下载中”。
- 删除任务的确认文案分别说明移除本地文件和删除云端记录的后果,不把两者合并为模糊“删除”。
- 键盘依次操作暂停、继续和删除不会触发任务详情导航,最后一个历史页明确宣布集合结束。
语义与键盘
- 集合使用
ul或ol,每个业务对象只对应一个li。 - 列表标题说明集合范围;排序有业务含义时在标题或控件中写明。
- 项目标题是链接,收藏、暂停、删除等命令是具有对象名称的并列按钮。
- “加载更多”位于当前集合之后,加载完成后焦点保留在触发位置,新项目接续进入阅读顺序。
- 实时新增先形成可操作提示,不把正在阅读的项目向下推移。
- 删除、过滤或返回恢复后,焦点和滚动锚点都依据稳定项目 ID 计算。
List 列表工程实现
1. ul/ol 只表达集合与顺序,不给普通列表套 listbox。
ul 适合顺序不构成含义的集合,ol 适合排名、步骤或时间顺序。listbox 是复合选择控件,要求选项、焦点和键盘模型;文章列表、搜索结果和任务流仅因“可以点击”并不会变成 listbox。
2. 每项标题链接负责导航,暂停、收藏等按钮独立。
列表项接口应把目标 URL 与命令操作分开,防止点击收藏同时触发导航。重复按钮的可访问名称需要包含项目标题,操作成功后更新该按钮状态,而不是把焦点移动到页面顶部的统一提示。
3. 游标分页保存 cursor 与查询指纹;返回时恢复已加载页和锚点 ID。
查询指纹由筛选、排序和用户权限范围组成;其中任一项变化,旧游标和缓存页都应作废。进入详情前记录首个可见项目 ID 及其像素偏移,返回时先恢复已加载页面,再定位锚点,避免只用易受内容高度影响的绝对滚动值。
4. 实时插入不在用户阅读中强制重排;高优先变化用状态提示。
新项目到达时可累积为“有 8 条新内容”的可操作提示,由用户决定何时合并到顶部。已显示项目的状态更新应按稳定 ID 原位合并;若更新改变排序,也要等用户确认刷新,避免阅读目标突然移动。
5. 无限滚动若阻断页尾内容,改为加载更多或分页。
无限滚动必须提供加载中、加载失败、重试和集合结束状态,并避免观察器反复触发并发请求。如果用户需要访问页脚、记住位置、共享结果范围或完成批量任务,显式“加载更多”或分页具有更稳定的边界。
6. 列表删除当前项后把焦点放到下一项、上一项或列表标题。
删除前记录项目在当前可见序列中的索引;删除成功后优先聚焦占据该索引的下一项,否则聚焦上一项。最后一项被删后把焦点移到列表标题或空状态中的主要操作,并用状态消息说明删除结果。
List 列表调试
- 从详情后退检查滚动锚点
- 让新项实时插入列表顶部
- 删除焦点项
- 断网后暂停和继续任务
- 20,000项检查内存与DOM
- 读屏确认列表长度和项标题
调试记录查询指纹、每次请求的入参游标、返回游标、项目 ID 序列和首个可见锚点。返回详情、实时插入与删除当前项三个场景分别检查滚动偏移、焦点元素和是否出现重复 ID。
List 列表发布检查
- 顺序规则可解释
- 返回位置可恢复
- 加载更多不重复对象
- 实时更新不抢焦点
- 项内操作不与整项点击冲突
- 集合结束可感知
失败注入包括下一页重复最后一项、游标过期、加载请求乱序、单项操作被拒绝、实时新增 100 项和最后一项被删除。实现必须去重或作废旧请求,保留已读内容,并明确集合是否还能继续加载。
综合练习
实现客服队列与离线下载两个列表,分别验证实时排序和本地任务恢复。
验收在 20,000 项数据上完成筛选、连续加载三批、进入详情后返回、接收实时更新和删除焦点项。项目 ID 无重复或遗漏,返回锚点误差可解释,集合结束可感知,且所有项目命令仅用键盘可完成。
列表项结构
每个列表项按稳定顺序提供:
- 主标题或对象名称;
- 支撑识别的摘要;
- 当前状态;
- 与任务相关的时间或优先级;
- 少量行级操作。
标题链接负责进入详情。暂停、收藏、删除等操作使用独立按钮。不要给整个列表项增加模拟链接后再嵌套按钮。
{
"id": "ticket-731",
"title": "支付失败",
"summary": "客户 A · 订单 O-2048",
"status": "open",
"priority": "p1",
"updatedAt": "2026-07-18T10:20:30Z",
"href": "/tickets/ticket-731",
"capabilities": ["read", "claim"]
}顺序与稳定性
列表顺序必须有显式规则:
| 场景 | 主要排序 | 稳定次序 |
|---|---|---|
| 客服队列 | 优先级、SLA | 更新时间、ID |
| 消息列表 | 发生时间 | 服务端序列 |
| 下载任务 | 创建时间 | 任务 ID |
| 搜索结果 | 相关度 | 稳定对象 ID |
| 人工排序 | position | 对象 ID |
实时数据变化时,不要立即移动用户正在阅读或操作的列表项。可采用:
- 显示“有 3 个新项目”按钮;
- 操作完成后再重排;
- 只更新状态,不改变位置;
- 保存阅读锚点后刷新;
- 对最高风险事件使用单独提示。
分页、加载更多与无限滚动
页码分页
适合需要跳页、引用固定页或总数稳定的集合。大偏移查询可能昂贵。
游标分页
适合实时、巨大或排序字段复杂的集合。游标包含排序位置与查询指纹,不能跨筛选复用。
加载更多
用户主动请求下一批,页面后续内容仍可到达。按钮在请求期间表达加载状态,失败后保留已有项目。
无限滚动
只有在连续浏览价值明确时采用。必须解决:
- 无法到达页尾;
- 返回位置丢失;
- 浏览器历史不完整;
- 读屏不知道新增范围;
- 重复或遗漏对象;
- 内存持续增长;
- 键盘焦点与回收 DOM 冲突。
返回位置恢复
保存:
{
"queryId": "tickets-priority-v4",
"anchorId": "ticket-731",
"anchorOffset": 24,
"loadedCursors": ["start", "cursor-50"],
"focusedControl": "ticket-731.claim"
}从详情返回后:
- 恢复同一查询;
- 取得包含锚点的批次;
- 按 ID 定位,而不是按旧数组下标;
- 恢复滚动偏移;
- 焦点回到原链接或下一合理项;
- 若对象已删除,解释变化并定位相邻项。
列表实时更新
事件合并使用对象 ID 与版本:
- 新版本覆盖旧版本;
- 旧事件丢弃;
- 删除事件移除对象;
- 不同查询条件重新判断是否仍属于集合;
- 排序字段变化按阅读策略决定何时移动;
- 重复事件幂等处理。
读屏公告只说明与任务有关的变化,例如“工单支付失败已被李明领取”,不逐条播报后台高频刷新。
列表可访问性
- 普通集合使用
ul或ol,不使用role="listbox"。 - 列表项标题有可区分的链接名称。
- 状态文本不只靠徽标颜色。
- 行级按钮名称包含对象上下文。
- 加载更多后说明新增数量。
- 删除焦点项后焦点位置可预测。
- 虚拟化不让读屏误解集合长度。
- 窄屏下摘要和操作按 DOM 顺序重排。
- 长文本可以换行并保持唯一操作可见。
- 空、加载失败和无权限使用不同状态。
列表专项失败注入
- 两页边界出现相同更新时间。
- 用户查看详情时对象被删除。
- 新 P1 工单在用户操作中到达。
- 加载更多响应乱序。
- 网络离线后本地下载任务继续。
- 返回时原锚点不再属于筛选。
- 20,000 个项目启用虚拟化。
- 状态名称为 40 个汉字。
- 权限只允许查看部分项目。
- 屏幕阅读器正在朗读时列表更新。
List 查询对账
对每次加载保存:
{
"queryId": "tickets-priority-v4",
"cursorIn": "cursor-50",
"cursorOut": "cursor-100",
"itemIds": ["ticket-781", "ticket-779"],
"hasMore": true
}检查相邻批次没有重复 ID,排序字段相同时仍由稳定 ID 决定次序。筛选改变后旧 cursor 必须拒绝。返回恢复时,锚点不存在要给出明确回退规则,而不是滚到页面顶部。
完成客服任务的权威证据是工单状态和处理记录,不是用户点击列表项。离线下载的权威证据是本地文件校验和任务状态,不是进度条到达 100%。
列表发布前还要验证浏览器前进、后退与刷新:查询参数必须恢复同一排序,游标失效时重新取得锚点附近结果,已删除对象进入明确提示。分析事件分别记录加载下一批、进入详情、执行行级操作和恢复位置,禁止把它们压成“列表点击”。
来源
- html.spec.whatwg.org — List 列表相关规范(访问日期:2026-07-18)
- www.w3.org — List 列表相关规范(访问日期:2026-07-18)
- design-system.service.gov.uk — List 列表相关规范(访问日期:2026-07-18)