出发前两小时,帐篷、照明、炉具都被勾选了,但切到微信小程序后又变成未打包。先不要急于接云同步,先明确“一条装备记录”究竟由谁拥有、以什么版本被保存。

把问题归咎于设备差异之前,应先确认业务状态是不是在页面之间保持了同一含义。 我们围绕“露营装备清单”的“我的装备”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

本篇跨平台技术封面

出发前的具体需求

实体由稳定 id、名称、类别、是否打包、更新时间组成;页面需要的是勾选状态,而持久层需要的是可恢复、可迁移的数据。数组的显示顺序不能担任业务身份,索引一旦变化,勾选就会错位。

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

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

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

用数据结构约束交互

用统一的 Repo 返回 GearItem[],持久化时携带 schemaVersion 和 savedAt。编辑采用不可变替换并一次写入快照,不把响应式 Proxy 直接序列化;保存失败时保留页面状态并展示“未写入本地”。

装备记录的 ID 一经生成就不能随着列表排序变化。一个简单但常见的错误,是在 v-for 里把 index 当 key,用户从“照明”筛选回“全部”后,勾选控件保留了上一行的状态。记录层还需要确定标题是否允许重名:帐篷和帐篷地钉都可能被用户简称为“帐篷”,因此唯一性不能依赖名称。第一次启动要返回空清单,损坏数据则应该有恢复提示。只有这种区分存在,用户才不会把意外的数据损坏误认为正常重置。

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

写出第一条可恢复路径

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

// stores/gear.ts
export interface GearItem {
  id: string; title: string; category: string;
  packed: boolean; updatedAt: number;
}
interface GearSnapshot { schemaVersion: 1; items: GearItem[] }
const KEY = 'gear.records.v1';
const EMPTY: GearSnapshot = { schemaVersion: 1, items: [] };
export function loadGear(): GearItem[] {
  try {
    const value = uni.getStorageSync(KEY) as GearSnapshot | '';
    if (!value) return [];
    if (value.schemaVersion !== 1 || !Array.isArray(value.items)) {
      throw new Error('不支持的存储版本');
    }
    return value.items.filter(v =>
      typeof v.id === 'string' && typeof v.packed === 'boolean');
  } catch (error) { console.warn('清单读取失败', error); throw error; }
}
export function commitGear(items: GearItem[]): void {
  const snapshot: GearSnapshot = {
    ...EMPTY, items: items.map(v => ({ ...v }))
  };
  uni.setStorageSync(KEY, snapshot);
}
export function setPacked(items: GearItem[], id: string, packed: boolean) {
  const next = items.map(g => g.id === id
    ? { ...g, packed, updatedAt: Date.now() } : g);
  commitGear(next);
  return next;
}

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

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

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

不同运行容器的真实限制

uni.setStorageSync 在 App、Web 和小程序上的底层存储空间、清理策略并不相同,不适合放大尺寸照片或大量二进制文件。这里存的是小型结构化记录;文件另建映射表,后续再谈离线资源。

Web / H5:H5 浏览器存储会受隐私模式、用户清理站点数据和容量策略影响。把它当作本地缓存而不是持久云备份,能减少跨浏览器恢复期待。 在“我的装备”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。

微信小程序:小程序的本地存储与用户在微信里的安装环境绑定,重新进入通常可恢复,但清缓存、换手机并不自动同步。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。

App:App 数据由应用沙盒管理,卸载或清理数据时同样可能失去记录。需要给用户提供清单导出入口的产品规划。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。

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

跨端边界或应用运行状态

逐项走完交付测试

旧记录缺少 id、同名装备被重复录入、关闭应用后恢复顺序变化,需要独立排查。尤其不能把“读取为空”混同于“第一次安装”,两者可能分别表示用户确实没有数据与文件格式损坏。

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

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

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

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

2)同名装备保留不同 id,删除其中一条不误删另一条。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“我的装备”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

3)手动写入非法 JSON,应用不崩溃而提示恢复入口。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“我的装备”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

4)快速勾选十次,只保存最终可解释快照。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“我的装备”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

5)把旧数据中的 packed 缺省,观察是否正确设置为 false。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“我的装备”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

如果后续会云同步,第一版就应给记录可追踪的 ID 和 updatedAt;但没有必要现在就引入复杂冲突算法。先建立序列化契约,再建立变更历史,最后才考虑多端数据一致性。

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

收尾与适用范围

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

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

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

Logo

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

更多推荐