列表到底自动翻页时用户恰好下拉刷新,页面出现重复活动。简单地把 page 加一,不足以保证数据顺序正确:两个异步请求可能以相反的顺序返回。

如果代码只能在开发者自己的一台设备上复现正确路径,那么它还没有形成可交付的跨平台能力。 我们围绕“城市场馆预约”的“票务列表”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

本篇跨平台技术封面

设计可复现的交错操作

分页状态至少包含查询条件、当前游标、加载态和请求代次。需要考虑服务端究竟提供 page/size 还是 cursor;本文以 page/size 说明客户端控制,不能保证 offset 翻页在数据实时变化时绝无重复。

如果只把“票务列表”当作一个可见页面,开发时很容易忽略操作背后的状态流。实际应用有用户重复点击、进程被回收、页面重新进入、系统权限被拒绝等情况;这些变化并不会自动遵守 Vue 组件的生命周期。建议先把 onReachBottom 的调用条件写成可阅读的规则,再决定在哪个页面事件里触发。

对“城市场馆预约”而言,页面组件需要能够回答三个问题:当前展示的数据是否已确认、用户现在还能执行什么动作、失败后哪些数据应继续保留。若这三个问题的答案依赖一个模糊的布尔值,后续出现空态、加载态和待确认态时就会不断补丁式增加判断。

从工程划分来看,pages/events/index.vue 是本篇关键实现位置。页面与公共服务不应互相猜测对方的数据形状:应明确参数类型、正常返回和需要处理的失败分类;读取与写入的规则在代码审查时分别核对。在票务链路中,读取活动和创建预约虽然共用网络能力,却必须采用不同的重试规则。只读查询可以按策略重试,影响库存的写入则必须具备服务端幂等保证。将二者混成“请求失败自动发一次”,在弱网里反而更危险。

定义正确的分页状态

刷新先增加 generation,清空旧游标并请求第一页;加载更多只在非忙碌且 hasMore 为真时触发。每次响应落地前检查是否仍属于同一代查询,再按 id 去重合并。

分页接口的排序条件必须稳定。假设第一页返回活动 A 到 T,用户浏览期间活动 A 余票发生变化,只要排序条件是热门程度且后台重新计算,下一页就可能再次出现 A。客户端的 Map 去重能防止重复显示,但跳过的活动不会自动补齐,这不是前端能单独解决的问题。若业务对列表完整性要求很高,应与后台协商 cursor、快照版本或稳定排序键。对刷新结束回调,也要保证异常路径仍执行,否则加载动画会在失败时一直挂着。

落地时先声明最小业务模型,再决定它的持有者。由页面驱动的暂态数据可以用 ref 或 computed;需要在刷新后恢复的结果必须明确读写入口;属于服务端最终决定的字段则不能因为按钮点击而直接写成成功。对“票务列表”的每一种可见状态,都建议找到对应的数据依据。

状态更新与实现代码

下面保留了与“票务列表”直接相关的核心实现。示例以标准 uni-app Vue3 工程为目标,服务端地址、业务表结构和平台授权按照项目实际环境配置。连载文章与前文按相同文件职责衔接:前面建立的类型与仓库不在后篇随意改名;独立文章则可以单独复制相应页面或服务进行验证。

<!-- pages/events/index.vue -->
<template>
  <view>
    <view v-for="event in items" :key="event.id" class="event-row">
      <text>{{ event.title }}</text><text>余票 {{ event.remaining }}</text>
    </view>
    <text v-if="loading">正在加载…</text>
    <text v-else-if="error">{{ error }}</text>
    <text v-else-if="!hasMore">没有更多活动</text>
  </view>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { onLoad, onPullDownRefresh, onReachBottom } from '@dcloudio/uni-app';
import { getJson } from '../../services/http';
interface EventItem { id: string; title: string; remaining: number }
const items = ref<EventItem[]>([]);
const loading = ref(false);
const error = ref('');
const hasMore = ref(true);
let page = 0;
let generation = 0;
async function loadNext(refresh = false) {
  if (loading.value && !refresh) return;
  const current = refresh ? ++generation : generation;
  const target = refresh ? 1 : page + 1;
  if (refresh) { items.value = []; page = 0; hasMore.value = true; }
  loading.value = true; error.value = '';
  try {
    const data = await fetchPage(target);
    if (current !== generation) return;
    const map = new Map(items.value.map(v => [v.id, v]));
    data.items.forEach(v => map.set(v.id, v));
    items.value = [...map.values()]; page = target;
    hasMore.value = data.items.length === 20;
  } catch { if (current === generation) error.value = '加载失败,请重试'; }
  finally { if (current === generation) loading.value = false; }
}
async function fetchPage(p: number): Promise<{items: EventItem[]}> {
  const data = await getJson<{items: EventItem[]}>(`/events?page=${p}&size=20`);
  if (!Array.isArray(data.items)) throw new Error('INVALID_PAGE');
  return data;
}
onLoad(() => { void loadNext(true); });
onReachBottom(() => { if (hasMore.value) void loadNext(); });
onPullDownRefresh(async () => {
  try { await loadNext(true); } finally { uni.stopPullDownRefresh(); }
});
</script>

从源码阅读顺序看,先定位 pages/events/index.vue 中的输入,再找到 onReachBottom 相关调用,最后确认界面状态或存储写回点。代码里最值得注意的是边界上的显式判断。它比向页面堆一个万能 catch 更有价值,因为不完整的数据、权限拒绝和无法联网,分别决定了用户接下来能做什么。业务组件只接收已经整理好的返回结果,才能独立处理加载、取消与重进页面。

这里刻意不把所有规则塞进一个通用帮助函数。跨端适配、数据校验与业务决定属于不同层级;只有约定好每一层的输入和输出,未来更换 UI 或接入新平台时才不会连带修改底层逻辑。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

开发环境或应用界面:本篇核心交互

三端滚动机制的不同入口

在 H5 与小程序中,页面级上拉触底、内部 scroll-view 触底的触发条件不完全相同;项目必须明确只采用一个滚动容器。App 的窗口与底部安全区也会影响最后一项是否进入触底区域。

Web / H5:H5 页面滚动和内部 scroll-view 可能形成双重滚动容器。先只保留一个触底源,避免滚动监听重复执行。 在“票务列表”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。

微信小程序:微信小程序的下拉刷新需要在 pages.json 开启对应配置,刷新结束必须调用 stopPullDownRefresh。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。

App:App 中软键盘、固定底栏、安全区会改变可见区域,最后一页加载条件需要在真实屏幕上检查。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。

三端一致的部分应尽量体现在数据契约与业务语义中,三端不同的部分则应被清楚标识。比如“票务列表”对用户呈现的保存、取消、重试这些动作应同义,但它们内部调用的权限检查、资源路径或系统接口可以不同。只有这样,平台迁移才不会变成整页复制。

跨端边界或应用运行状态

复查边界条件

空列表却被解释为网络故障、刷新结束忘记调用 stopPullDownRefresh、重复触底导致 page 跳过,属于不同层次的缺陷。修复后须用慢网速与快速手势交错检验。

针对“城市场馆预约”,排查时不要把所有可见异常归入同一个“操作失败”。先问失败发生在输入校验、页面状态转换、平台 API 调用、后台返回还是存储恢复;这五个位置至少要能在日志或可见状态中区分。对用户而言,保留已填写内容通常比重复弹窗更重要;对开发者而言,保留最小触发路径比截取一张成功页更有价值。

建议采用有限的日志字段:模块、动作、错误类别、必要的状态编号和构建版本。对于 onReachBottom 所涉及的调用,敏感值、文件内容及完整用户资料不应输出。将错误按是否可重试划分之后,页面才能选择展示“重试”“继续编辑”或“前往授权”,而不是遇到任何问题都自动再执行一次。

关键流程、状态或验证步骤讲解

回归时建议按下面五项逐条操作,不依赖“看起来正常”的主观判断:

1)连续三次触底只发送一个下一页请求。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“票务列表”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

2)刷新旧请求晚返回也不会覆盖新条件数据。 不要只测正常网络和一台设备。若涉及异步步骤,至少安排一次连续快速触发以及一次人为中断;若涉及本地数据,则重新打开页面确认恢复结果。这样比盯着开发者工具里的成功提示可靠。 对“票务列表”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

3)末页不足 size 时 hasMore 置为 false。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“票务列表”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

4)分页出现重复 id 时 UI 不出现重复卡片。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“票务列表”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

5)切换筛选条件后页面编号与列表同时重置。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“票务列表”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

客户端去重只能补救显示层,不能替代服务端稳定排序。如果后端数据持续变化,游标分页或按时间加唯一 ID 的复合排序往往比 page/size 更有解释性。

如果本次只维护一条流程,优先把数据契约、失败状态和用户可执行的下一步做扎实。新增功能前再审视公共服务与平台分支是否仍然清晰;对于需要真实联网、后端配置或设备权限的步骤,应在目标环境执行相应测试,不宜直接把源码静态检查描述成实际编译或真机验证。

收尾与适用范围

这篇围绕“票务列表”建立了一条从数据边界、调用实现到多端验收的路径。它并不依赖于某种固定配色或 UI 库,重要的是业务动作在正常、取消、中断和重新进入时保持可解释。只要记录能够恢复、状态能够解释、异常能够定位,后续新增终端就有了可靠的工程基础。

票务接口治理系列下一篇将沿着同一服务层继续扩展,不另造一套请求协议,重点处理本篇尚未覆盖的交叉状态与恢复路径。

本文所用平台 API 与工程约束可对照 uni-app 官方参考、Vue3 组合式 API 以及 条件编译文档。若使用新版 HBuilderX 或开发 HarmonyOS Next 应以目标版本的文档与设备支持表为准。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐