30分钟快速跑通HarmonyOS AdventureWheel元服务:云手机+AI编译打包安装完整教程

原创2026-11-12 12:29:461,819 阅读
文章标签:移动开发示例工程教程前端游戏开发

30分钟快速跑通HarmonyOS AdventureWheel元服务:云手机+AI编译打包安装完整教程

这篇教程带你用云手机 + AI 编译打包的方式,在 30 分钟内跑通 HarmonyOS「冒险大转盘」(AdventureWheel)元服务:克隆工程 → AI 生成 HAP → 创建鸿蒙云手机 → 安装并启动 → 体验转盘抽取与本地任务库。项目为朋友聚会提供纯本地的真心话大冒险玩法,内置 190 条任务,支持 JSON/TXT 导入导出,无需服务器。

一、项目是什么:一个聚会可用的真心话大冒险元服务 🎡

AdventureWheel 是一个鸿蒙元服务(手机侧、Stage 模型、ArkTS/ArkUI 开发),核心体验闭环是:

  1. 开局设置:选「真心话 / 大冒险 / 混合局」,设置 2–20 个任务和最高挑战程度;
  2. 清单确认:点击「立即开始」先看本局任务清单,不满意可重新生成,确认后才开局;
  3. 轮流转盘:每人点击一次,Canvas 转盘减速停下、突出命中扇区,动画弹出完整任务卡片;
  4. 交接与去重:「交给下一位」后该扇区变灰标记「完成」,同局不再重复抽取;
  5. 任务库:浏览 190 条内置任务,添加/编辑/启停/删除自己的任务,并可导出 JSON 或分享 TXT 带到另一台设备。

技术栈一览:Canvas + 透视变换做 2.5D 转盘动画、Preferences 做本地持久化、DocumentViewPicker + 文件 URI 做导入导出与分享。

AdventureWheel 鸿蒙元服务成品预览:开局设置页、轮流转动转盘与本地任务库

冒险大转盘元服务学习卡片:ArkUI、随机转盘、本地任务库三项核心知识

二、开始前的环境与资源准备 🧰

项目 要求 说明
云端开发入口 鸿蒙开发实践中心作业中心的可用工作区 创建项目时能带入案例仓库
测试设备 鸿蒙云手机(或本地模拟器) 云端「设备管理 → 鸿蒙云手机」创建
版本兼容 目标 API 23,最低兼容 API 20 云手机镜像需满足工程要求
签名 本地模拟器可无签名调试 真机/云手机按平台实际要求准备
网络 联网 获取源码、SDK 与依赖;游戏运行本身不依赖网络

💡 本案例无需创建云函数、数据库或服务器,云手机只是运行验证设备,不是应用后端。

完成本文后,你也可以顺着 README.md 第 4 章,从空项目开始用 AI 独立构建自己的版本。

三、第一步:克隆工程并核对目录结构

在开发环境或本机执行克隆:

git clone https://gitcode.com/harmony-practice-center/HarmonyOS-AtomSer-AdventureWheel

完成标志:目录中出现以下关键路径,说明工程导入完整。

AdventureWheel/
├── AppScope/                    # 元服务标识、名称和图标
├── entry/src/main/
│   ├── module.json5             # 元服务入口与设备范围
│   └── ets/
│       ├── pages/               # 首页、任务库、转盘页
│       ├── components/WheelCanvas.ets  # Canvas 转盘
│       ├── engine/TaskEngine.ets       # 随机抽取与同局去重
│       └── store/LocalTaskStore.ets    # Preferences 本地存储
├── data/内置任务-v1.0.json       # 190 条内置教学任务
├── build-profile.json5
└── oh-package.json5

关键文件对照:

文件 作用
entry/src/main/ets/pages/SetupPage.ets 首页开局设置,恢复上次玩法与任务数
entry/src/main/ets/engine/TaskEngine.ets 开局筛选 + Fisher–Yates 洗牌抽样
entry/src/main/ets/components/WheelCanvas.ets 2.5D 转盘绘制与旋转动画
entry/src/main/ets/store/LocalTaskStore.ets 自定义任务本地持久化
data/内置任务-v1.0.json 95 条真心话 + 95 条大冒险

四、第二步:让 AI 编译打包生成 HAP 🤖

在 AI 对话中直接粘贴下面这段提示词(来自 README.md 云端快速体验路线):

请解析当前“冒险大转盘”工程,找到 HarmonyOS 入口,
检查现有 SDK、依赖和构建工具,编译生成 HAP。
可自行处理的问题根据日志修复并重新构建,保持现有功能、包名、
目标 API 23 和最低兼容 API 20。
需要安装工具、修改环境或变更需求时,先说明,由我决定。
完成后告诉我 HAP 的实际位置,以及设备安装的系统和签名条件。

完成标志:构建成功,AI 给出 HAP 的实际路径。

⚠️ 高频构建报错速查:

现象/错误码 常见原因 处理方式
00303313 固定编译 SDK 与工具不匹配 使用配套 SDK,保留目标 API 23 / 兼容 API 20 再重新构建
找不到工具、Java 或 HAP 路径、目录或环境不匹配 让 AI 读取日志定位,确认本次构建产物存在
案例未导入 「案例仓地址」与「Git 仓库地址」字段填混 核对案例仓地址,工程出现后再构建

记住一条原则:构建成功 ≠ 运行成功,安装与启动要分别核对。

五、第三步:创建并连接鸿蒙云手机 ☁️

  1. 进入开发环境的「设备管理 → 鸿蒙云手机」;
  2. 选择满足工程要求(目标 API 23、最低兼容 API 20)的手机镜像,点击创建;
  3. 连接设备,回到开发环境确认能识别。

完成标志:云手机处于运行状态,且 AI/命令行能识别该设备。多设备同时连接时,后续步骤先列出设备让你选择。

六、第四步:AI 安装 HAP 并启动元服务 📲

继续粘贴提示词:

请识别已连接的鸿蒙云手机,将刚才生成的 HAP 推送、安装,
并启动“冒险大转盘”元服务。多个设备时先列出让我选择。
失败时依据实际错误排查;需要我准备签名或操作时告诉我。
完成后告诉我使用的设备,以及是否已打开首页。

完成标志:云手机桌面/元服务列表中出现「冒险大转盘」并打开首页。

关于签名:公开工程默认不配置签名,可生成无签名 HAP;本地模拟器按官方无签名方式调试即可,真机或云手机若平台明确要求签名,再用自己的调试签名,不要复用他人私钥。

七、第五步:5 分钟体验核心功能 ✅

安装成功后,按这条路线走一遍:

  1. 首页选「混合局」,任务数拉到 6、挑战程度「适中」,点击「立即开始」;
  2. 查看本局清单,点击「确认开局」进入转盘页;
  3. 点击转盘中心「开始」,观察减速、命中扇区高亮与结果卡片入场动画;
  4. 点击「交给下一位」,该扇区变灰标记「完成」,再转一次——结果不会重复;
  5. 返回首页进入「任务库」,浏览 190 条内置任务与「我添加的」入口。

AdventureWheel 元服务转盘页实拍:轮流开转、同局不重复,完成扇区变灰并保留位置

进阶玩法:在任务库新增一条「大冒险 / 轻松」的任务,重启应用确认本地保留;再用「分享我的任务」生成 TXT(正文仍是 JSON),在另一台设备导入恢复——这就是本案例的文件迁移能力,契约细节见 docs/任务文件格式.md。

八、跑不通时怎么排查 🔍

按「工程和素材 → 工具与构建 → 设备与签名 → 业务状态」的顺序缩小范围:

现象 环节 恢复方式
无设备或安装失败 设备 检查连接、API 版本与签名条件,依据原始报错处理,实际安装并打开后再继续
TXT 不能导入 迁移 对照 docs/任务文件格式.md 检查正文是否为 JSON、是否超过 1 MiB / 1000 条
分享只打开一个应用 迁移 接收目标由已安装应用决定;核对文件是否实际接收,必要时改用导出
自定义任务没被抽到 开局 检查是否停用、条件不符或超过「本局数量 50%」上限
AI 忘记之前约束 实践 让 AI 重读需求文档与素材,最小修复后复查

排障提示词(直接粘贴给 AI):

请依据实际失败的日志或页面现象复现并定位问题。
区分环境、素材、构建、设备和业务问题,最小修复后重跑失败步骤;
需要改环境或需求先告诉我,由我决定。
说明原因、修改内容和重试结果。

九、接下来可以做什么 🚀

  • 想理解实现原理:读 docs/设计说明.md,掌握「两层随机规则」「完成状态不持久化」「动画与结果分离」的设计取舍;
  • 想从空项目独立构建:按 README.md 第 4 章「完整实践」,用统一教学素材和八步提示词,2–4 小时做出自己的版本;
  • 备份数据超限时:参考 docs/批量迁移说明.md 用工程自带工具安全拆分再逐份导入;
  • 素材与字段细节:docs/实践素材说明.md 与 NOTICE.md。

30 分钟跑通「克隆 → AI 编译 → 云手机安装 → 转盘体验」,你就同时完成了 HarmonyOS 元服务打包、设备安装和 ArkTS/ArkUI 动画、本地存储、文件迁移三个知识点的实战验证。祝开局顺利,玩得开心 🎉

登录后查看全文
HarmonyOS-AtomSer-AdventureWheel