Skip to content

List 列表 ​

列表按稳定顺序呈现同类对象摘要,适合扫描、进入详情或执行少量行级动作,不强调跨列精确比较。

数据与任务边界 ​

列表适合按稳定顺序扫描同类对象、进入详情和执行少量项目级命令。排序、分页和返回位置共同定义阅读连续性;其中任一项不稳定都会产生重复项目、遗漏项目或返回后位置丢失。

前置知识:ul/ol/li、链接与按钮、稳定排序、游标分页、历史记录和滚动容器。

数据模型 ​

json
{
  "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、主标题、摘要、状态和少量操作。
  • 顺序依据优先级、时间或人工排序,不能只靠视觉位置。
  • 列表项进入详情使用链接,行级动作使用独立按钮。
  • 分页、加载更多和无限滚动分别定义历史与返回位置。
  • 空、加载、失败、无权限和没有更多分开。
  • 删除或插入项目时保持焦点与阅读位置。
  • 本地乐观更新与服务端确认使用不同状态。
mermaid
flowchart LR
    Q["筛选与稳定排序"] --> P1["首批项目 + 游标"]
    P1 --> P2["加载下一批并按 ID 去重"]
    P2 --> A["记录可见锚点"]
    A --> D["进入项目详情"]
    D --> H["返回并恢复查询、页面与锚点"]

交互规则 ​

  • 筛选和排序写入可恢复 URL。
  • 加载更多保留已有项和焦点,不重排已阅读内容。
  • 返回列表恢复查询、滚动位置和选中上下文。
  • 多选出现后显示作用范围与已选数量。
  • 长标题换行,不用 tooltip 承载唯一信息。
  • 刷新时按对象 ID 合并,不用数组位置覆盖。

List 列表状态 ​

状态专属行为
首次加载列表框架与查询可见
加载更多保留已有项和焦点
无更多明确集合结束
实时更新稳定ID合并,不夺走阅读位置
返回恢复查询、滚动和选中上下文恢复
离线本地项与未同步状态分开

案例 1:客服按优先级处理工单队列 ​

约束与输入 ​

  • 200 个开放工单;P1 在前;状态实时变化。
  • 客服从列表进入详情,处理后返回下一项。

处理过程 ​

  1. 服务端排序规则包含优先级和更新时间。
  2. 每项显示标题、客户、SLA 与状态。
  3. 详情返回恢复查询与原位置。
  4. 工单被他人领取时就地更新并播报。
  5. 处理成功后根据排序规则移动或移除该项。

失败分支 ​

实时更新把当前焦点项目移走,焦点退到 body。修正为延迟重排到用户完成操作,并保留稳定焦点目标。

专属验证 ​

  • 构造相同更新时间的 P1 工单,以稳定 ID 作为最终平局键,连续翻页不得重复或遗漏。
  • 从第 73 个工单进入详情并返回,原查询、已加载页和该工单相对视口位置应恢复。
  • 当前焦点工单被他人领取时先原位更新状态;用户完成操作后再按队列规则移动。
  • 处理成功移除当前项后,焦点落在原位置的下一张工单;若没有下一项则落到上一项。

案例 2:移动端浏览离线下载任务 ​

约束与输入 ​

  • 15 个下载;部分离线;任务有进度和错误。
  • 用户需要暂停、继续和删除。

处理过程 ​

  1. 每项显示文件名、大小、进度与真实状态。
  2. 暂停和继续是按钮,不让整项同时可点击。
  3. 离线时允许查看本地任务但标记未同步。
  4. 重新联网后按任务 ID 对账。
  5. 删除已下载文件前说明本地与云端影响。

失败分支 ​

无限加载历史任务没有结束标识,键盘用户无法到达页面后续内容。改为分页或提供明确“加载更多”按钮。

专属验证 ​

  • 断网后 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 无重复或遗漏,返回锚点误差可解释,集合结束可感知,且所有项目命令仅用键盘可完成。

列表项结构 ​

每个列表项按稳定顺序提供:

  1. 主标题或对象名称;
  2. 支撑识别的摘要;
  3. 当前状态;
  4. 与任务相关的时间或优先级;
  5. 少量行级操作。

标题链接负责进入详情。暂停、收藏、删除等操作使用独立按钮。不要给整个列表项增加模拟链接后再嵌套按钮。

json
{
  "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 冲突。

返回位置恢复 ​

保存:

json
{
  "queryId": "tickets-priority-v4",
  "anchorId": "ticket-731",
  "anchorOffset": 24,
  "loadedCursors": ["start", "cursor-50"],
  "focusedControl": "ticket-731.claim"
}

从详情返回后:

  1. 恢复同一查询;
  2. 取得包含锚点的批次;
  3. 按 ID 定位,而不是按旧数组下标;
  4. 恢复滚动偏移;
  5. 焦点回到原链接或下一合理项;
  6. 若对象已删除,解释变化并定位相邻项。

列表实时更新 ​

事件合并使用对象 ID 与版本:

  • 新版本覆盖旧版本;
  • 旧事件丢弃;
  • 删除事件移除对象;
  • 不同查询条件重新判断是否仍属于集合;
  • 排序字段变化按阅读策略决定何时移动;
  • 重复事件幂等处理。

读屏公告只说明与任务有关的变化,例如“工单支付失败已被李明领取”,不逐条播报后台高频刷新。

列表可访问性 ​

  • 普通集合使用 ul 或 ol,不使用 role="listbox"。
  • 列表项标题有可区分的链接名称。
  • 状态文本不只靠徽标颜色。
  • 行级按钮名称包含对象上下文。
  • 加载更多后说明新增数量。
  • 删除焦点项后焦点位置可预测。
  • 虚拟化不让读屏误解集合长度。
  • 窄屏下摘要和操作按 DOM 顺序重排。
  • 长文本可以换行并保持唯一操作可见。
  • 空、加载失败和无权限使用不同状态。

列表专项失败注入 ​

  1. 两页边界出现相同更新时间。
  2. 用户查看详情时对象被删除。
  3. 新 P1 工单在用户操作中到达。
  4. 加载更多响应乱序。
  5. 网络离线后本地下载任务继续。
  6. 返回时原锚点不再属于筛选。
  7. 20,000 个项目启用虚拟化。
  8. 状态名称为 40 个汉字。
  9. 权限只允许查看部分项目。
  10. 屏幕阅读器正在朗读时列表更新。

List 查询对账 ​

对每次加载保存:

json
{
  "queryId": "tickets-priority-v4",
  "cursorIn": "cursor-50",
  "cursorOut": "cursor-100",
  "itemIds": ["ticket-781", "ticket-779"],
  "hasMore": true
}

检查相邻批次没有重复 ID,排序字段相同时仍由稳定 ID 决定次序。筛选改变后旧 cursor 必须拒绝。返回恢复时,锚点不存在要给出明确回退规则,而不是滚到页面顶部。

完成客服任务的权威证据是工单状态和处理记录,不是用户点击列表项。离线下载的权威证据是本地文件校验和任务状态,不是进度条到达 100%。

列表发布前还要验证浏览器前进、后退与刷新:查询参数必须恢复同一排序,游标失效时重新取得锚点附近结果,已删除对象进入明确提示。分析事件分别记录加载下一批、进入详情、执行行级操作和恢复位置,禁止把它们压成“列表点击”。

来源 ​

从前端走向软件产品工程的长期路线图。