2026-10-18-global-list-pagination.md 13 KB
驾驶舱长列表统一分页规范（2026-10-18）
来源：票 57（维护者 2026-10-17 反馈 5）。上位规格：2026-10-17-monitoring-feedback.md §5。
目标与适用判据
凡可能包含表格或卡片列表、且新增数据会无限拉长页面的区域，统一分页行为：
- 每页最多 10 条（
PAGE_SIZE = 10），前端展示窗口恒 ≤10 条； - 控件三件：上一页、下一页、页码直达；只有一页时不画任何控件；
- 先筛选/分类，后分页；条件变化回第 1 页；总数不由当前页反推。
排除（不是条目清单，或数量契约有界，详见盘点表）：聚合图表（柱/环/堆叠/趋势/饼/维度柱）、KPI 行、键值行块、一张图顶部状态栏图例、地图重叠聚合 fan（渲染层）、契约有界小清单（管理信息片区×行业明细、预警分析重点识别）、地图摘要点位装载（渐进保护，见三分法）。
统一行为（规范条文）
- 页大小：
PAGE_SIZE = 10。任何接入区域的展示窗口每页 ≤10 条。 - 控件：
上一页｜页码｜下一页+ 计数行「第 X/Y 页 · 共 N 条」。页码直达＝页码按钮：当前页不可点并标aria-current="page"；总页数 >7 时收缩为「1 … c−1 c c+1 … Y」窗口（恒含首末页与省略号）。 - 禁用态：到边按钮
disabled且保留占位（按钮消失会让计数行跳动，读起来像出错——票 46 既有语义）。 - 一页不画控件：
pageCount <= 1时整个 pager 不渲染（短列表不多出两个死按钮）。 - 筛选先于分页：分类 chips、全局筛选（行业/片区/设备类型/点位状态/范围）、模式切换（预警↔报警）、设备·点位切换、时间范围变化，都先作用于集合或请求参数，再分页。
- 复位规则：上述任何条件变化 → 页码回第 1 页。新鲜度/定时刷新不复位页码（用户停在第 3 页时，周期刷新不得把人弹回第 1 页）；数据变少导致页码越界时由分页函数夹回最后一页。
- 总数口径：服务端分页读响应
pagination.total；前端集合分页读过滤后集合长度；渐进装载用「已装载 M · 共 N」双口径。任何区域不得用「当前页 × 页大小」反推总数。 - 态语义（沿用既有分区词汇，不另造一套）：
- 加载：
正在取数…（分区 pending 语义）；翻页请求进行中保持旧内容或同一占位，不闪空白； - 空态：「真没有」与「条件下没有」分文案（
当前没有记录vs当前分类下没有记录（换一个分类或点「全部」））； - 失败：分区 FAILED/UNAVAILABLE 占位 + 分区状态标签；渐进装载下一批失败不回滚已装载内容（台账既有语义）；
- 竞态：沿用各 store 既有 token/纪元纪律；翻页请求迟到即作废，不落进新页码。
- 加载：
- 无障碍：pager
role="group"+aria-label="「列表名」分页"；页码当前项aria-current="page"；计数行是随页码更新的文本。 - 文案纪律：不把后端
page/pageSize参数名暴露到界面文案（上位规格 §5 原文）；只说「页」「条」。 - 单源：翻页窗口计算只有一份（
domain/pagination.js，自equipmentDetailView.pagedRows升格，HISTORY_PAGE_SIZE/pagedRows原名保留导出兼容），pager 控件只有一份（PagerNav.vue）。禁止任何组件重写翻页算术或另画一套 pager。
三分法：服务端 / 前端集合 / 渐进装载
- 服务端页码分页（翻页即请求，
page+pageSize=10进查询串）： 预警处置·当前事件表（/events/current）；预警处置·历史事件单窗范围（/events/history-analysis近 7 天）。 - 前端集合分页（数据已一次装载，pager 只切窗口、零请求）：
设备详情预警/报警/工单状态；点位摘要设备卡片与关联设备图层清单；运行概况异常设备清单；基础设施·运行信息指标列表（票 64 补入，原误列排除）；历史事件多窗合并范围（近 30/90 天——
historyWindows分窗合并后不存在「全局页」，回退已加载合并集合分页并在页脚如实说明；全局服务端分页需后端另立票，不在本图范围）。 - 渐进装载 + 页码 UI（数据链路保持自动渐进，界面只对已装载集合翻页）： 监测点台账——装载与一张图点位数据同款自动渐进链（条件变化 → 新快照 → 自动连翻到 settled，沿用快照 token 与纪元纪律）；UI 面板对已装载集合做统一页码分页（10/页、页码直达）。
- 排除：地图摘要点位装载保持自动渐进、无列表 UI（票 14/23 契约，不得误改为页码分页）。
维护者裁定（2026-10-18；2026-10-19 追加第 3 条）
- 监测点台账：监测点数据保持自动渐进式加载（与地图中点位数据的加载方式一致），但 UI 页面中要能翻页——「加载下一页监测点」按钮随之退役。
- 事件清单：走服务端页码分页（翻页带
page参数发请求）；多窗合并范围的回退规则见三分法。 - 验收与走查以真实数据为准，不为演示扩写 mock 样例（票 64 引出）：mock 样例数据量小 ⇒ 某些接入区域在 mock 下不足一页、按条文 4 正确地不画控件，这是预期行为而非缺陷，不得为此把 mock 样例补到 >10 条（扩了也没有演示价值，真实数据才是验收口径）。多页与边界行为一律在闸门里用真实载荷或合成载荷证明（往闸门灌数据 ≠ 改 mock 样例：票 62 的 mock 判据、票 64 的 t64 V 组都是这条路）；真实观感归票 18 联调窗口。批次二~五执行票同样适用。
全仓盘点
| 区域 | 代码接缝 | 数据源 · 现状 | 目标 | 批次 |
|---|---|---|---|---|
| 设备详情 · 预警信息 / 报警信息 | EquipmentDetailSections.vue（data-event-list）、domain/equipmentDetailView.js |
设备详情聚合两分区；已每页 10、先分类后翻、一页无控件 | 迁共享 pager，补页码直达 | 一 |
| 设备详情 · 工单状态 | 同上（data-work-order-list） |
设备详情聚合 workOrders；全量直渲 | 前端集合分页 10/页 | 一 |
| 预警处置 · 当前事件表 | EventListPane.vue（data-event-table）、stores/eventStore.js |
/events/current（后端默认 100、上限 1000）；前端砍最新 12 条 |
服务端页码分页（pageSize=10）；mode/筛选/范围变化回第 1 页 |
三 |
| 预警处置 · 历史事件 | domain/warningResponsePanels.js historyAnalysisPanel（PanelBlocks list 块） |
/events/history-analysis 分窗合并；events.slice(0,12) |
单窗（近 7 天）服务端分页；多窗（近 30/90 天）合并集合分页 + 页脚如实说明 | 三 |
| 运行概况 · 异常设备清单 | domain/monitoringPanels.js operationOverview（list 块） |
/monitoring/situation 一次响应；全量直渲 |
前端集合分页 10/页（页脚用 pagination.total） |
四 |
| 运行监测 · 监测点台账 | domain/monitoringPanels.js monitoringPointLedger、stores/monitoringStore.js loadMoreLedger、PanelBlocks data-ledger-more |
/monitoring/distribution 服务端分页 + 快照 token（票 23）；「加载下一页」每次追加后端一页 ≈500 卡 |
装载保持自动渐进（同地图链路）；UI 对已装载集合页码分页 10/页；按钮退役 | 四 |
| 点位摘要 · 设备卡片 | PointDetailCard.vue（data-device-cards） |
设备详情端点 devices[]；全量直渲 |
前端集合分页 10/页 | 二 |
| 点位摘要 · 关联设备图层清单 | PointDetailCard.vue（data-device-layer-list，票 42） |
地图快照 deviceCodes，保留全部编码（含待确认） |
前端集合分页 10/页（数据仍保留全部，窗口化渲染；互斥归类与差额口径不变） | 二 |
| 基础设施 · 运行信息指标列表 | domain/infrastructurePanels.js operationPanel → listBlock('运行指标', …, { paginate: true, pageScope }) |
/infrastructure/operating-information 一次回全部行业指标；实测 6772 条（供水 2497／排水 3576／燃气 699），响应 2.3 MB；原全量直渲、块标题「指标占位」与实际内容不符 |
前端集合分页 10/页（本票 57 曾误列为排除项，2026-10-19 由维护者反馈纠正）；块标题改为如实说法 —— 已由票 64 落地 | 五 ✅ |
| 基础设施 · 管理信息片区×行业明细 | managementPanel（list 块） |
districtIndustry[]，实测 9 行，组合数契约有界（片区×行业） |
排除（有界小清单，实测 <10） | — |
| 基础设施 · 应急保障三段 | domain/infrastructurePanels.js emergencySectionBlock（list 块） |
/infrastructure/emergency-support 三段 items；实测 8+0+20=28 条（防护目标 20 条已超一页） |
前端集合分页 10/页（一页时无控件） | 五 |
| 预警分析 · 重点识别 | eventAnalysisPanel（list 块） |
后端聚合重点，数量少 | 排除 | — |
| 一张图 · 地图摘要点位装载 | stores/mapStore.js、domain/mapSummary.js |
/map/snapshot 快照自动链 |
排除：保持自动渐进装载，不改页码 | — |
| 其余 | 图表块（bars/donut/stacked/trend/pie/dimbars）、KPI、键值行、状态栏图例、地图重叠聚合 fan | 非条目清单 | 排除 | — |
跳页（维护者 2026-10-19 追加）
页码直达按钮之外，pager 还必须提供输入框跳页：
- 一个数字输入框 + 「跳转」按钮（或 Enter 提交），输入目标页号后直接跳到该页；
- 输入非数字/0/超出
pageCount时夹回合法范围（1..pageCount），不报错、不发请求、不清空列表； - 输入框占位提示当前页（
placeholder = 当前页），aria-label="跳转到指定页"； - 总页数 ≤1 时整块 pager（含输入框）不渲染，与本规范第 4 条一致；
- 跳页与「上一页/下一页/页码」共用同一个翻页出口，不新增第二套页码状态。
实施批次
每批一张执行票（本票只收口规范与盘点，不实施）：
- 批次一：共享分页基建（
domain/pagination.js+PagerNav.vue，含页码直达与输入框跳页）+ 设备详情三清单接入（预警/报警迁移、工单状态新接入）。 - 批次二：点位摘要两级清单（设备卡片、关联设备图层清单）分页。
- 批次三：预警处置事件清单服务端页码分页（当前事件表 + 历史事件单窗/多窗规则 + mock 同构）。
- 批次四：运行监测（异常设备清单前端集合分页；台账自动渐进装载链 + 页码 UI、撤「加载下一页」按钮）。
- 批次五：基础设施运行信息指标列表（6772 条，最高优先）+ 应急保障三段接入（PanelBlocks list 块路径收尾）。
执行票：见票 57 正文（批次五已按 2026-10-19 维护者反馈扩为两张：运行信息指标列表 + 应急保障）。
非目标
- 不改后端只读契约与快照 token 语义（票 23）；地图渐进装载不改页码。
- 不改排序口径（「前端不重排」立场不变；服务端分页按后端返回序渲染）。
- 不给聚合图表、KPI、键值行与契约有界小清单加分页。
- 按 AGENTS.md，实施票默认跳过 build/dev/浏览器验证，除非维护者当次明确授权。
修订记录
- 2026-10-18 首版（票 57）。
- 2026-10-19 维护者 8 条反馈后的纠正：① 补齐「输入框跳页」要求；② 撤销运行信息指标列表的排除——实测 6772 条 / 2.3 MB，改列入批次五（原判断基于代码推断"单行业指标条数契约有界"，被真实数据证伪）；③ 应急保障盘点点亮实测量（8+0+20=28）；④ 管理信息实测 9 行，维持排除并补实测依据。
- 2026-10-19 票 64 收口时的追加裁定（见「维护者裁定」第 3 条）：验收以真实数据为准，不为演示扩写 mock 样例；mock 下不足一页不画控件是预期行为，多页行为归闸门用真实/合成载荷证明。
- 2026-10-19 票 60（批次二）维护者当次两条裁定：① 点位摘要里票 14 的「另有 N 台 · 未命中当前筛选」展开子清单同样 ≤10/页、独立第三套页码（判据一视同仁：它可能拉长页面；「另有 N 台」的 N 仍报全量，差额可追溯不变）；② 计数行（条文 2/9）在
PointDetailCard的三处 pager 一律省略——PagerNav新增show-count开关（默认true，批次一既有消费方形态不变）；该组件上方已各有权威总数（设备合计 KPI 读后端统计；清单标题「总数 X 台（已上图 Y）」只认当前快照），并排再画「共 N 条」就成了窗口口径的第二个总数。