从零构建门店巡检应用:React Native 与 Expo 的完整实战指南

原创2026-09-21 09:54:491,665 阅读
文章标签:教程文档Vibe Coding

从零构建门店巡检应用:React Native 与 Expo 的完整实战指南

门店巡检应用需要同时覆盖 Android、iPhone 与浏览器三种运行环境:店员打开首页即可查看当天任务、勾选完成进度、记录现场问题,并在关闭应用后仍然保留数据。本文基于 Datawhale easy-vibe 项目中 React Native 与 Expo 门店巡检专题(德文版)与 中文源文档 编写,从项目创建、交互开发、本地存储到真机验证与发布,完整还原这套"项目制学习"的落地路径。读完你将掌握:用 Expo 脚手架创建 TypeScript 项目、按步迭代出可勾选可保存的巡检页面、用 AsyncStorage 实现本地持久化,并理解 Development Build、内部测试版与三端验收的完整流程。

1. React Native 与 Expo:两个工具如何分工

React Native 负责用 React 与 TypeScript 编写页面,并把它渲染成 Android 和 iOS 的原生界面(不是 HTML,也不是 WebView);Expo 则在此基础上补齐了工程化能力——项目脚手架、开发服务器、设备 API、构建与更新服务。两者结合,让"一套 TypeScript 代码跑三端"成为可能。

仓库中的 架构示意图 直观地展示了这套结构:中间是保存页面、表单、状态与业务规则的可复用代码库;React Native 把 React 界面交给各平台真正渲染;Expo 提供脚手架、Router、设备 API、开发构建与云端构建;Android 最终生成 APK/AAB,iOS 生成 App,Web 端则由 React Native for Web 生成静态资源。

React Native 与 Expo 的项目结构示意图:一套 TypeScript 项目,分别输出 Android、iOS 与 Web 三个运行目标

需要强调的是,共用代码不等于三端完全一致。相机、通知、权限、返回手势和发布流程仍然要分别在每个平台上单独验证——这一点贯穿整个专题的验收标准。

2. 三个已经落地的真实产品

三个知名产品分别展示了 React Native 与 Expo 在不同业务中的用法,也为巡检应用的页面信息顺序提供了参照。

Shopify POS:零售收银场景

Shopify POS 用于门店收银、查库存、退换货调单。Shopify 在正式采用 React Native 前,专门用性能较低的 Android 设备做过实验——开发者电脑上运行流畅,不代表门店里的旧设备也流畅。巡检首页沿用了同样的信息顺序:先显示门店和班次,再显示完成进度、待办任务和现场问题,店员打开页面就能看到当天的巡检状态。

Shopify POS 官方产品页展示的库存和门店界面

Discord:跨端共用的社区产品

Discord 原本分别维护 Android 与 iPhone 应用,新功能经常不能同时到达两边;改用 React Native 后两边共用更多页面和功能,但返回手势、字体和系统习惯仍需分别处理。对巡检应用而言,这意味着主要内容可以共用,但依然要在 Android 和 iPhone 上分别打开检查。

Discord 官方展示的 Android 角色页面改版前后对比

MTA TrainTime:Expo 驱动的公共交通应用

纽约大都会运输署(MTA)用 Expo 开发出行应用,乘客在赶车、买票、上车验票等网络不断变化的场景中使用。Expo 提供的"打包"(把开发中的项目做成可安装的测试应用)与"更新"(把已确认的小修改送到用户设备)能力,让他们在遇到严重问题时能快速发布修复。

Expo 官方案例展示的 MTA TrainTime 应用

3. 创建项目与巡检清单

3.1 准备开发环境

浏览器版本只需两样工具:

  • Node.js:安装页面选择 LTS(维护时间较长的稳定版本)即可;本专题验证环境使用 Node.js 22.14。
  • 代码编辑器:Trae、VS Code 等均可,用于打开项目并与 AI 协作修改文件。

浏览器版本完成后,Android 使用 Android Studio(Google 提供),iPhone 使用 Xcode(Apple 提供,仅支持 Mac)。创建新项目时使用 Expo 官方脚手架给出的当前 SDK 版本即可,本专题验证环境为 Expo SDK 57。

3.2 用脚手架创建空白项目

直接执行 Expo 官方脚手架:

npx create-expo-app@latest store-inspection --template blank-typescript
cd store-inspection
npx expo start

三行命令分别表示:创建项目、进入项目目录、启动项目。终端出现二维码后按 W 在浏览器中打开,看到空白页面即启动成功。也可以让 AI 编程工具代为执行:"请创建一个名为 store-inspection 的 Expo TypeScript 项目。"

如果项目没有启动,把错误信息交给 AI:"Expo 没有启动,错误是【粘贴错误】。请只修复启动问题。"

3.3 用 AI 提示词逐步搭出巡检首页

从最小页面开始,分三步完成首页:

  1. "请把首页标题改成'门店巡检',并显示门店名称和班次。"
  2. "请在首页加入四项巡检任务,先用演示数据。"
  3. "请显示巡检完成进度,并在任务列表下面加入'现场问题'区域。"

任务勾选与进度联动是核心交互,建议按小步迭代并逐次验证:"请让巡检任务可以勾选和取消",确认四项任务都能点击后,再执行"请让完成进度根据已勾选的任务数量变化"。如果进度计算有误,可用"我勾选一项后进度错误。请只修复进度计算,不改页面样式"这类提示词限定修复范围。

下面两张截图来自本次创建的 Expo 项目(页面实际运行在浏览器中)。宽屏下展示门店"江南路门店"、班次"早班·08:30-12:00"、进度 1/4 和巡检任务列表:

门店巡检应用真实运行在 Expo Web:展示门店、班次、任务列表与完成进度

浏览器窗口变窄后,内容应自动切换为手机宽度,按钮和文字不能挤在一起——这张窄屏图仅用于检查窄窗口下的排列,不能代替 Android 与 iPhone 的真机验证:

同一个 Expo Web 应用的窄屏布局,用于检查手机宽度下的排版

4. 保存巡检报告:从内存到本地持久化

4.1 现场问题的输入与保存

在"现场问题"区域加入输入框和保存按钮后,需要依次处理三个细节:

  1. 空内容拦截:"没有填写内容时不要保存,并在输入框下面提示'请填写现场问题'。"
  2. 保存成功反馈:"保存后清空输入框,并把刚才的内容显示在下面。"

实际验证路径是:勾选"检查安全出口"后进度从 1/4 变成 2/4;输入"消防通道有纸箱,已通知值班员移走"并保存,记录出现在页面,输入框恢复为空。下方截图展示的正是保存后的状态——进度 2/4、"已记录 1 条"及问题描述均正确显示:

真实点击和保存后的巡检记录:进度变为 2/4,现场问题已持久显示

4.2 关闭应用后保留数据

刷新页面或关闭应用后记录消失,是因为数据只停留在内存状态里。这一阶段的完成标准是:再次打开应用时,刚才的进度和记录还在。对应的提示词是"请把巡检进度和现场记录保存在本机"。

改完后按固定顺序检查:勾选两项任务 → 保存一条现场问题 → 完全关闭应用 → 重新打开确认数据还在。德语原版文档对此给出了明确的选型建议:

  • AsyncStorage:适合保存少量键值数据,相当于"应用自己的小记事本";
  • expo-sqlite:当记录量增加、需要在"巡检、明细、待办"之间建立关系并支持搜索分类时,改用本地数据库更合适。

4.3 一条记录上传到服务器

本地数据只留在这台设备上,换手机或店长要在后台查看,就需要上传到服务器。建议从一条记录开始:

  1. 先让 AI 列出所需条件:"我想把巡检记录同步到服务器。请先告诉我最少需要准备什么,不要修改代码。"
  2. 再让 AI 只做上传功能:"请先实现'上传一条巡检记录'。"

上传成功时页面显示"已同步";上传失败时本机记录仍然要保留——分别测试成功与失败两种情况,结果清晰后再增加自动重试。一条记录跑通后,再依次增加登录、门店权限、图片上传和数据隔离。

5. 照片与后端:后续阶段的扩展方向

德语版文档明确把照片和后端放在"之后添加"的位置,并给出了两条安全与架构边界:

5.1 照片记录

在开放的问题点允许拍照,需要包含预览与移除能力。文字记录完成后,可以使用 Expo 的拍照与相册工具 ImagePicker(expo-image-picker)增加照片记录。

5.2 凭据安全与离线同步

  • 移动端 Token 属于 SecureStore:敏感凭据应放入 expo-secure-store,而不是普通存储;
  • 企业级机密禁止进客户端:既不能写死在 App 里,也不能放进 EXPO_PUBLIC_ 环境变量——EXPO_PUBLIC_ 前缀的变量会被打进客户端包,任何用户都能提取;
  • 离线同步在本地存储与 API 稳定之后再引入:先保证"本机数据可靠 + 接口可访问",再谈冲突处理与同步策略。

6. 在真实设备上收尾:Expo Go、Development Build 与验收清单

6.1 三端打开与验收

  • Android:安装 Android Studio 并创建启动一台虚拟手机,回到 Expo 终端按 A;也可在真机安装 Expo Go,扫码终端二维码打开项目。验收标准包括:应用可打开、系统返回键可用、输入框不被键盘挡住。
  • iPhone:Xcode 中下载 iPhone 模拟系统,启动模拟器后按 I。检查顶部内容是否被刘海挡住、返回手势是否可用、输入框是否被键盘挡住。浏览器窄屏截图不能作为 iPhone 验证结果。
  • 浏览器:按 W 检查鼠标键盘操作、刷新与窄屏布局;准备发布时生成静态文件:
npx expo export --platform web

本专题在浏览器中实际完成了勾选、进度变化与文字保存三项验证;由于测试机没有可启动的 Android 虚拟手机、也未下载 iPhone 模拟系统,因此没有把 Android 与 iPhone 写成"已验证"——这是文档刻意保持的严谨边界。

6.2 Development Build 与内部测试版

Expo Go 是大家共用的体验工具,适合查看第一版页面;项目继续开发后,需要制作只属于当前项目的测试应用(Development Build)。先让 AI 列出准备项:"请列出配置 Development Build 前需要准备的内容,不要修改项目",再执行"请为当前项目配置 Development Build"。

Expo 支持本机打包与云端打包服务,云端服务需要 Expo 账号;公开发布还需要 App Store 或 Google Play 的开发者账号。开发版安装到真机后,要实测相机、照片、通知、离线恢复和后台切换——模拟器能打开,不代表设备能力已经完成。

准备给同事试用时,Android 与 iOS 分开准备内部测试版("内部测试版"只发给同事,不会出现在应用商店)。在此之前,先给两个已跑通的小功能补上自动测试,一次只测一件事:

  1. "请测试:勾选一项任务后,完成进度会增加。"
  2. "请测试:现场问题为空时不能保存。"

自动测试守住简单规则;相机、权限和手机性能仍需真机检查。最后请一位未参与开发的同事走一遍完整流程:打开当天任务、勾选两项、写一条现场问题、完全关闭再重新打开。如果同事总问"我刚才到底保存了吗",说明页面没有把"已保存在本机"与"已上传"的结果讲清楚,应先把状态显示明白再继续加功能。

7. 验证边界与完成标准小结

德语版文档在结尾给出了一条重要的验证声明:原型基于 Expo SDK 57、TypeScript 与真实 Web 导出测试通过;而在没有 Android 模拟器与 iOS 模拟器运行环境的情况下,移动端构建与签名不能视为"已完成"。

汇总本专题的完整验收链路:

阶段 完成标准 验证手段
首页搭建 门店、班次、任务、进度、现场问题区域齐全 浏览器宽屏 + 窄屏检查
交互逻辑 勾选联动进度、空内容拦截、保存后清空并回显 浏览器实际操作
本地持久化 关闭并重开后进度与记录仍在 完全关闭应用再打开
服务器同步 成功显示"已同步",失败保留本机记录 分别测试成功与失败
三端验证 Android 返回键/键盘、iPhone 刘海/返回手势、浏览器刷新 各端独立验证,互不替代
设备能力 相机、照片、通知、离线恢复、后台切换 Development Build 真机测试
测试与发布 自动测试通过、内部测试版跑通 一次只测一件事,逐项推进

从"一个空白项目"到"一份可保存、可同步、可发布的门店巡检应用",这套流程的关键不在于一次写对,而在于每完成一次修改都重新运行项目并检查页面变化。这正是 easy-vibe 项目"项目制学习"的核心方法论——通过可运行的小步骤持续收敛,最终在真实设备上交付可用的第一版。想继续深入时,可参阅仓库中的 中文源文档(含 13 个步骤的完整提示词与验证清单)以及 stage-3 跨端专题目录 中的其他平台实践。

登录后查看全文
easy-vibe