从0到1打造鸿蒙「记油耗」App：一场ArkTS与uni-app的实战之旅

阳光先做

236人浏览 · 2026-07-31 11:49:30

阳光先做 · 2026-07-31 11:49:30 发布

一、项目缘起：为什么想做一款油耗记录工具？

开车的人都有过这种体验：每次加油付完钱，心里默默算一下“这次又花了多少”，但时间一长，上个月加了多少钱、油耗是高是低，根本记不清。

市面上其实有不少油耗管理App，但它们的共同特点是——第一步先注册账号。填手机号、收验证码、同意隐私协议，一套流程走下来，真正想记一笔加油时，反而要先完成一堆与记账无关的操作

我的想法很简单：能不能做一个打开即用、不需要登录、数据存在本地的工具？

于是就有了《记油耗》——一款轻量级的加油记账与用车成本分析工具。每次加油后，只需记录日期、金额、油量、单价和当前里程，应用自动帮你整理累计油费、累计加油量、加油次数、参考油耗、每公里成本、月度趋势等数据。

一句话概括：用最少的输入记录每次加油，自动算油耗与真实用车成本。

二、技术选型：为什么选择 Vue 3 + uni-app 来开发鸿蒙App？

2.1 跨端是刚需

作为一个独立开发者，我不可能为每个平台单独维护一套代码。Vue 3 + uni-app 的组合让我能用一套业务代码覆盖多个平台。当前项目已经具备以下平台的构建支持：

HarmonyOS 应用
Android App、iOS App
H5
微信小程序、支付宝小程序、百度小程序、QQ小程序、字节跳动小程序、飞书小程序、京东小程序、快手小程序、小红书小程序、快应用 WebView

当然，依赖中包含某个平台的编译能力，不等于该平台已经完成真机适配和发布。目前已经实际验证通过的是鸿蒙生产构建。

2.2 TypeScript 贯穿全流程

项目使用 TypeScript 定义了完整的领域模型：

车辆模型：本地唯一ID、车辆名称、品牌、型号、排量、车牌号、默认油品等
加油记录模型：所属车辆ID、加油日期、实付金额、加油量、当前里程、油品类型、是否加满、单价、参考油耗、每公里成本等
统计模型：月度统计、总统计、油耗数据点等

项目没有把所有数据都塞进页面，而是先建立领域模型，让记录、计算和展示拥有统一的数据语言。

2.3 Pinia 管理状态，本地持久化

数据存储方案选择了 Pinia + pinia-plugin-persistedstate，底层使用 uni.getStorageSync 和 uni.setStorageSync 将数据持久化到设备本地。

这套方案的优势很明显：

首次打开即可使用，没有注册登录门槛
无需部署服务器，没有持续的服务器成本
个人用车记录不会被默认上传，隐私有保障
离线环境仍可查看和新增数据

当然也有局限性：

卸载应用或清除数据可能造成记录丢失
更换设备后不会自动同步
需要定期通过 CSV 导出进行备份

三、核心功能实现：从数据到统计

3.1 油耗与成本计算算法

这是整个App最核心的算法。项目采用相邻两次加油记录之间的里程差来计算参考数据：

text

行驶里程 = 本次里程 - 上次里程
参考油耗 = 本次加油量 ÷ 行驶里程 × 100
每公里成本 = 本次实付金额 ÷ 行驶里程

第一条记录为什么不显示油耗？ 因为第一条记录只有当前里程，没有上一条记录提供起点，因此会被视为里程基线。从第二条有效记录开始，才能计算参考油耗和每公里成本。

数据有效性处理方面，会排除或提示不合理情况：

当前里程必须大于零
当前里程应高于上一条记录
油量与金额必须是有效正数
金额、油量和单价可填写任意两项，第三项自动计算

3.2 编辑和删除后的级联重算

这是项目中最有技术含量的一个点。

油耗是由相邻记录共同决定的。因此用户编辑里程、金额或油量，或者删除中间一条记录后，项目不会只修改当前卡片，而是重新整理相关记录顺序并计算受影响的区间。

一条加油记录并不是孤立数据。修改或删除历史记录时，相邻里程区间也会随之改变，因此应用会自动重算相关油耗，保证统计结果始终与当前记录一致。

3.3 轻量级数据可视化

统计页面没有引入重量级图表库（如ECharts），而是使用 Vue 模板、响应式计算和 CSS 绘制轻量图表。

当前展示包括：

最近6个月或12个月的月度油费柱状趋势
最近若干次加油的参考油耗趋势
累计费用、累计油量、平均油耗和每公里成本

这种实现的好处：

减少第三方图表依赖
控制安装包体积
样式与应用视觉保持一致
跨端适配成本相对较低

3.4 多车辆数据隔离

每条加油记录都带有 vehicleId，统计时只读取当前车辆的数据。用户切换车辆后，首页累计数据、最近记录、记录列表、统计趋势同步切换。

项目还提供了旧数据迁移逻辑：如果早期版本的记录没有车辆ID，会将其归入默认车辆，避免功能升级后历史记录丢失。

这体现了两个工程考虑：

多车辆数据不是页面临时过滤，而是进入了核心数据模型
产品升级时考虑了已有用户数据的向后兼容

3.5 表单交互：三项联动

加油记录表单最值得一提的交互是金额、油量、单价三项联动——用户只需填写任意两项，第三项自动计算。

表单组件同时服务于“新增记录”和“记录详情编辑”两个场景，通过 Props 接收原记录，通过 Emits 将标准化数据交给页面保存。这种复用减少了新增与编辑页面之间的重复逻辑。

3.6 CSV 数据导出

项目不依赖服务端生成文件，而是在本地将记录转换为 CSV 文本。导出内容包括日期、金额、油量、里程、油品、是否加满、单价、参考油耗、备注等。

实现细节包括：

CSV单元格引号转义
逗号、换行等特殊字符处理
UTF-8 BOM，改善中文在表格软件中的打开效果
复制到剪贴板，方便用户粘贴到 Excel、WPS 等工具

四、鸿蒙原生能力接入：UTS 插件的实践

4.1 为什么要用 UTS？

项目通过 uni-app 的 UTS 插件机制调用鸿蒙原生能力。当前自定义插件位于 src/uni_modules/youfeiji-app-review/，在鸿蒙端引入了：

@kit.AppGalleryKit（应用市场评分能力）
@kit.BasicServicesKit
@kit.AbilityKit

4.2 应用内评分弹窗的实现

核心调用逻辑：

通过 UTSHarmony.getUIAbilityContext() 获取当前 UIAbilityContext
调用 AppGallery Kit 的应用内评论弹窗
将成功、无上下文或调用失败统一转换为业务层结果
页面只关心标准化结果，不直接处理鸿蒙原生异常

系统接口调用成功只表示评分弹窗成功发起，不代表用户最终提交了评价。

4.3 克制的评分策略

评分能力不仅包含原生弹窗，还增加了一层本地触发策略：

自动邀请需要同时满足：

安装或首次使用已满7天
成功新增至少5条加油记录
距离上一次成功发起评分邀请至少10天

首页还提供了手动“去评价”入口，用户主动点击时直接请求评分弹窗，不受自动策略限制。

评分邀请不是简单地“打开应用就弹”，而是结合使用时长、有效记录次数和冷却周期，只在用户完成核心任务后尝试出现，尽量减少打扰。

五、踩坑与填坑

5.1 鸿蒙构建的坑

鸿蒙端的构建并不是开箱即用的。针对 HarmonyOS，构建配置需要主动避开部分第三方根容器和跨包优化逻辑，保留 uni-app 官方启动行为，降低第三方构建改写对鸿蒙页面宿主初始化的影响。

具体来说：

某些第三方插件会尝试修改页面根容器，导致鸿蒙端页面无法正常渲染
需要在 Vite 配置中针对 HarmonyOS 平台做特殊处理
生产构建过程中需要反复验证页面宿主是否正常工作

5.2 旧数据迁移的兼容性

项目早期版本只有单车辆功能，升级到多车辆后，历史记录没有 vehicleId 字段。解决方案是在 Store 初始化时检测记录是否包含 vehicleId，如果没有则归入默认车辆。

5.3 表单三项联动的交互细节

金额、油量、单价三项联动看起来简单，但实现时需要考虑：

用户修改任意一项时，应该清空哪一项的自动计算结果？
如果用户填了三项，以哪一项为准？
输入过程中如何避免循环触发？

最终方案是：用户手动修改任意一项时，自动清空第三项的计算结果，让用户明确知道当前是哪两项决定了第三项。

5.4 评分防重复调用

业务层使用运行中状态防止用户快速点击或多个触发点同时请求评分弹窗。只有系统弹窗成功发起后，才会更新上一次邀请时间；调用失败不会错误地消耗冷却周期。

六、应用展示与未来规划

6.1 页面架构

项目采用原生 TabBar，共四个主页面：

页面	主要职责
首页	累计费用、累计油量、平均油耗、最近记录、快捷记账和评价入口
记录	时间筛选、月度汇总和全部加油记录
统计	月度油费趋势、逐笔油耗趋势和累计指标
我的	当前车辆、默认设置、CSV导出、数据清理和应用信息