用户连续改了四件装备,返回上一页时发现只保存了两件。看似偶现的丢失通常有迹可循:草稿、列表快照和最后保存时间混进了同一个 Key。

实践中先收紧输入与输出,比第一时间增加新框架更容易获得可解释的结果。 我们围绕“露营装备清单”的“打包草稿”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

本篇跨平台技术封面

先辨认数据的两个生命周期

本地数据分为领域记录和临时编辑态。领域记录要求可恢复、可迁移,临时编辑态只为当前交互服务;把它们混存会造成取消编辑时也改动正式清单。

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

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

从工程划分来看,services/local-repo.ts 是本篇关键实现位置。页面与公共服务不应互相猜测对方的数据形状:应明确参数类型、正常返回和需要处理的失败分类;读取与写入的规则在代码审查时分别核对。在装备清单里,本地可恢复性比立刻接入云服务更重要。状态更新的时间、持久化完成的时间与跨设备同步完成的时间,应该是三个独立概念;任何一个尚未完成,页面都要避免使用含糊的“已同步”。

逐步拆开读写入口

提供 load、commit 和 rollback 三个入口。读取时把未知结构转换为可用快照,写入时先形成值对象再落盘;每次只写一份完整记录,避免多个小 Key 之间出现半提交状态。

同步 API 带来的便利是可以在组件加载时立即拿到小块数据,但也容易诱使开发者在每个输入事件里直接落盘。更好的策略是把未完成编辑放进 draft,并约定什么时候提交:点保存、离开前确认或达到明确的自动保存节奏。取消只丢弃 draft,不应该反向写回正式记录。在多人协作时,还要注意这个本地仓库只对当前设备容器有效,绝不能暗示用户在另一台设备打开后立即能看到同样的数据。

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

核心实现与调用关系

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

// services/local-repo.ts
import type { GearItem } from '../stores/gear';
const FORMAL_KEY = 'gear.records.v1';
const DRAFT_KEY = 'gear.edit.draft';
export interface Draft { id: string; title: string; packed: boolean }
function cloneDraft(source: Draft): Draft { return { ...source }; }
export const localRepo = {
  readFormal(): GearItem[] {
    const snap = uni.getStorageSync(FORMAL_KEY) as {items?: GearItem[]} | '';
    return snap && Array.isArray(snap.items) ? snap.items : [];
  },
  begin(source: Draft): Draft {
    const draft = cloneDraft(source);
    uni.setStorageSync(DRAFT_KEY, draft);
    return draft;
  },
  commit(draft: Draft): void {
    if (!draft.title.trim()) throw new Error('名称不能为空');
    const items = this.readFormal();
    const next = items.map(g => g.id === draft.id
      ? { ...g, title: draft.title.trim(), packed: draft.packed,
          updatedAt: Date.now() } : g);
    uni.setStorageSync(FORMAL_KEY, { schemaVersion: 1, items: next });
    uni.removeStorageSync(DRAFT_KEY);
  },
  rollback(): void { uni.removeStorageSync(DRAFT_KEY); }
};

从源码阅读顺序看,先定位 services/local-repo.ts 中的输入,再找到 uni.getStorageSync 相关调用,最后确认界面状态或存储写回点。第一件事是确定调用的输入从哪里来:它可能来自路由参数、响应式状态,也可能来自本地持久化。第二件事是确定输出由谁消费:不应让 UI 组件直接承担重试协议或数据迁移。第三件事是检查失败路径是否有出口,不能永远停在加载中。

代码里最值得注意的是边界上的显式判断。它比向页面堆一个万能 catch 更有价值,因为不完整的数据、权限拒绝和无法联网,分别决定了用户接下来能做什么。业务组件只接收已经整理好的返回结果,才能独立处理加载、取消与重进页面。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

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

容器差异不是异常分支

同步存储 API 易于理解,但大对象写入会阻塞当前执行路径。清单数量变大或出现连续高频编辑时,可以缓冲编辑操作并切换异步接口;同时确认相应平台的容量与清理策略。

Web / H5:H5 刷新网页后仅保留已提交的快照,未确认的草稿是否保留需要产品明确约定,不应偶尔存在偶尔消失。 在“打包草稿”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。

微信小程序:小程序页面多次进入 onShow 很常见,避免在每次显示时无条件从旧缓存覆盖正在编辑的草稿。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。

App:App 在后台被回收后可能重建页面,所以提交结果要先落盘再返回,而不是依赖 UI 动画完成保存。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。

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

跨端边界或应用运行状态

用反例检查保存机制

同一页面既 onLoad 又 onShow 刷新存储容易发生新旧覆盖;深拷贝方式随意使用 JSON.stringify 也可能丢掉非 JSON 类型。这里明确数据模型只允许可 JSON 序列化字段。

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

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

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

1)编辑后点取消,正式清单保持原样。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“打包草稿”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

2)保存失败时保留草稿并展示重试按钮。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“打包草稿”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

3)重新进入页面只从正式快照恢复一次。 不要只测正常网络和一台设备。若涉及异步步骤,至少安排一次连续快速触发以及一次人为中断;若涉及本地数据,则重新打开页面确认恢复结果。这样比盯着开发者工具里的成功提示可靠。 对“打包草稿”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

4)写入空数组和读取不存在的 Key 不混为一谈。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“打包草稿”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

5)多次快速更新同一装备不产生重复条目。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“打包草稿”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

本地仓库并不承担表单验证或业务提示职责。将写入异常作为返回结果交给页面,既能实现自动重试,也能由界面提示用户复制尚未保存的内容。

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

收尾与适用范围

这篇围绕“打包草稿”建立了一条从数据边界、调用实现到多端验收的路径。它并不依赖于某种固定配色或 UI 库,重要的是业务动作在正常、取消、中断和重新进入时保持可解释。后续迭代可以更换组件和数据源,但输入、失败状态以及用户操作的语义应当持续稳定。

露营装备离线档案系列后续继续沿用本篇的记录身份与保存规则,不通过更换 Key 或重置全部本地数据来绕开兼容问题。

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

Logo

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

更多推荐