星海国际机场导航元服务:HarmonyOS 室内导航的 ArkTS 实现要点
一、案例背景
星海国际机场导航元服务是鸿蒙开发实践中心的一个进阶案例:以一座虚构机场为教学场景,从空项目出发,用 ArkTS / ArkUI 构建一个六页原生元服务,完成“选目的地—选起点—看路线—分步抵达”的完整导览流程。案例的工程目标与兼容版本为 HarmonyOS 6.1.0(API 23),数据全部随包下发,不依赖账号、后端与网络定位,适合作为室内导航类应用的入门实现参考。
案例公仓:https://gitcode.com/harmony-practice-center/HarmonyOS-AtomSer-airport-guide
二、整体架构:六页共享一份行程状态
元服务由六页组成:首页、目的地选择、起点选择、路线预览、地铁方向与楼层地图。六页并不各自维护状态,而是共享同一个行程状态对象 PlannerState,由 Navigation 宿主以 @Provide 提供,子页消费。
PlannerState 集中管理五类信息:
- 选择草稿与已确认的起终点;
- 路线偏好;
- 当前阶段(预览 / 指引 / 完成);
- 步骤序号 stepIndex;
- 最近使用的目的地。
“草稿与确认分离”是这个设计最值得借鉴的一点:用户在起点页或偏好页的编辑先改草稿,取消编辑时保留原路线与进度;只有确认后才重新规划、回到预览并把步骤归零。交换起终点、修改偏好同样触发重新规划。状态更新时替换整个对象,保证各页看到一致的行程。
三、地图建模:本地 JSON 生成的六层图
机场地图是一份本地 JSON(data/XHA_xinghai_t1.map.json),覆盖 4F、3F、2F、1F、B1、B2 六层,共 119 个节点、145 条边。工程启动时由生成脚本把 JSON 转成 ArkTS 地图模型,供地点搜索与寻路使用,原始 JSON 始终保留。
节点分为三类:可搜索的目的地与设施、普通中转节点、换层设施(电梯 / 扶梯)。搜索列表只混入目的地与设施,不混入普通中转节点;每个节点带中英文名、所属楼层与坐标,便于按分类筛选与按关键字搜索。
四、寻路:带安检约束的 Dijkstra 与四种偏好
寻路在双向图上跑 Dijkstra,核心约束是“中央安检”:当起终点位于安检两侧时,路线必须经过中央安检;同侧两点之间则直接寻路,不绕行安检。
路线规划提供四种偏好:推荐路线、优先电梯、优先扶梯、尽量少换层。偏好只影响换层设施的选择与换层边的代价,不改变安检约束本身。规划结果拆成 RouteStep 序列,区分步行、安检、换层与到达四种步骤;步行距离只统计步行边,换层单独列出,避免把垂直移动算进米数。
五、地图与指引联动:Canvas 楼层地图 + 手动确认
楼层地图用 ArkUI Canvas 绘制,支持平移、缩放、切层与点选。RouteStep 通过 legIndex 与地图联动:当前段、安检段与换层设施在地图上高亮,查看其他楼层或全程步骤不会推进指引进度。
指引采用“手动确认”模式:用户按提示一步步确认,直到确认到达目的地;也可以回退到上一步。地图上设置起点后会给出反馈并引导用户先选目的地;起终点相同、不可达等异常都有明确提示与重选入口。
六、双语与本地保存
中英文双语覆盖全部文案与地点名,语言与最近六个目的地用 Preferences 保存在设备本地;指引进度只保留在会话内,新行程的起终点为空。也就是说,重启后语言与最近地点还在,但每一次新行程都从“你想去哪里?”重新开始。
七、开发流程:先跑通现成工程,再从空项目重建
案例推荐两条实践路径:
- 快速体验:拉取现成工程,让 AI 检查 SDK、依赖与构建工具并编译 HAP,再推送到云手机或模拟器安装运行,走一遍“A101—西出发门—中央安检预览—开始指引”的流程。
- 完整实践:从空项目开始,按八个阶段依次让 AI 创建工程、接入地图、做首页与搜索、完成起点与规划、联动地图与指引、补齐双语与异常处理,最后运行并逐项检查。
无论哪条路径,验收标准都一样:构建成功并给出 HAP 路径;选定设备上首页可打开;地点可搜索,路线预览与指引可完成;错误输入有恢复入口。
八、可迁移的要点
这个案例的方法可以迁移到展馆、商场、校园等室内导览场景:
- 用本地节点—边数据描述空间,地点、通道与受限通行点分开建模;
- 受限路径用“必经点 + 偏好代价”的方式表达,而不是写死路线;
- 多页流程共享一份行程状态,编辑先改草稿、确认再提交;
- 地图只做呈现与点选,进度推进交给显式的手动确认。
掌握这四点,再换一份地图数据,就能做出属于自己的导览元服务。
- 点赞
- 收藏
- 关注作者
评论(0)