多设备地图导航界面

概述

UX设计

出行导航类场景通常包含查询地点信息、路线建议、导航、打车等核心功能，用户可以通过悬浮面板体验到面板与底层地图间的交互，围绕此核心场景，此类应用有如下特点：

• 手机使用底部半模态面板，其他设备上使用侧边半模态面板。
• 面板支持多档位高度滑动调节。
• 面板默认高度，需要依据屏幕尺寸的不同而有所区分，充分发挥屏幕尺寸优势。
• 折叠屏&平板上侧边的半模态面板支持用户自行拖拽至左侧或右侧位置。
• 建议折叠屏和平板等宽屏设备上，Tab放置在半模态面板内。

地图导航应用的UX设计可参考出行导航类多设备响应式设计指南，设计参考图如下所示。

工程管理

考虑到“一多”工程代码的复用性和可维护性，推荐开发者使用分层架构组织代码工程。分层架构将项目工程划分为产品定制层（products）、基础特性层（features）和公共能力层（commons）三个层级，各层级权责清晰、各司其职，为开发者提供了一套清晰、高效且可扩展的设计架构。关于分层架构的具体设计细节，可参考分层架构设计。

[h2]创建工程

建议开发者参考多设备工程部署与发布相关内容，掌握分层架构工程的创建与配置方法后，创建出模板项目工程。然后根据地图导航应用的开发需求进行针对性修改，确保工程架构贴合实际业务需求。

[h2]工程结构

在创建“一多”工程时，开发者会面临工程结构目录的划分问题。考虑到复用性和可维护性，本文以地图导航应用为例，提供推荐的参考方案。

HarmonyOS的分层架构主要包括三个层次：产品定制层、基础特性层和公共能力层，为开发者构建了一个清晰、高效、可扩展的设计架构。更多详情请参考分层架构设计的逻辑设计。

地图导航应用根据一多推荐的commons、features、products的“三层工程架构”划分目录。各层级设计如下：

• commons层：集中存放窗口管理、断点工具、定位状态、地图状态和公共常量等需要被不同页面依赖引用的内容，实现代码复用并减少冗余。

• features层：地图容器、地点探索和实况窗能力相互独立，根据业务职责划分为三个业务模块：地图容器（mapcontainer）、地点探索（poiexplore）和实况窗（maplive）。
• products层：多设备地图导航应用需要适配的设备包括直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板和电脑。由于电脑界面布局与其他设备有一定差异。因此单独创建“pc”的HAP包作为电脑设备应用入口；直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板界面布局整体相似，部分差异可以通过“一多”的自适应布局和响应式布局进行适配，为此创建名为“default”的HAP包作为这些设备的应用入口。

工程结构如下：

├──commons                                // 公共能力层
│  └──multitravelbase                     // 公共基础模块
│     └──src
│        └──main
│           ├──ets
│           │  ├──constants               // 公共常量
│           │  ├──model                   // 跨模块共享状态和数据模型
│           │  └──utils                   // 日志、位置、窗口、地图场景、资源文本等公共工具
│           └──resources                  // 公共资源
├──features                               // 基础特性层
│  ├──mapcontainer                        // 地图容器模块
│  │  └──src
│  │     └──main
│  │        ├──ets
│  │        │  ├──model                   // 地图视口、边距等地图容器模型
│  │        │  ├──pages                   // 地图主界面页面入口
│  │        │  ├──view                    // 地图画布、面板容器、PC装饰工具栏等视图
│  │        │  └──viewmodel               // 地图主界面状态管理
│  │        └──resources                  // 地图容器资源
│  ├──maplive                             // 实况窗模块
│  │  └──src
│  │     └──main
│  │        ├──ets
│  │        │  ├──constants               // 实况窗常量
│  │        │  └──viewmodel               // 实况窗控制逻辑
│  │        └──resources                  // 实况窗资源
│  └──poiexplore                          // 兴趣点探索模块
│     └──src
│        └──main
│           ├──ets
│           │  ├──constants               // 兴趣点探索常量
│           │  ├──model                   // 首页展示、地点详情、搜索和路线规划数据模型
│           │  ├──view                    // 首页、搜索、详情、路线规划等视图
│           │  └──viewmodel               // 搜索、地点详情和路线规划视图模型
│           └──resources                  // 兴趣点探索资源
└──products                               // 产品定制层
   ├──default                             // 默认（手机/平板）产品
   │  └──src
   │     └──main
   │        ├──ets
   │        │  ├──defaultability          // 默认产品入口
   │        │  └──pages                   // 默认产品页面
   │        └──resources                  // 默认产品资源
   └──pc                                  // 电脑产品
      └──src
         └──main
            ├──ets
            │  ├──pages                   // 电脑产品页面
            │  └──pcability               // 电脑产品入口
            └──resources                  // 电脑产品资源

移动端页面

本章将介绍如何针对直板机、双折叠（Mate X系列）、三折叠、阔折叠和平板设备，使用“一多”的布局能力，实现地图导航应用页面层级“一套代码、多端适配”。同时，介绍上述移动设备的窗口适配方案，以及各页面的交互开发和功能开发。

[h2]窗口适配

• 窗口模式

  多设备地图导航示例，根据适配的设备，涉及全屏模式、分屏模式、悬浮窗模式、自由窗口模式，可参考窗口模式。其中分屏模式与悬浮窗通常无特殊设计，可通过系统方式进入。应用监听窗口尺寸变化，通过断点刷新UI，将自动适配全屏、分屏、悬浮窗、自由窗口模式下的布局。

• 窗口方向

  通过设置setPreferredOrientation()设置应用窗口方向，在地图导航应用中，Orientation参数设置为FOLLOW_DESKTOP，使应用跟随桌面的旋转策略。在该旋转策略下，在类直板机上推荐仅竖屏显示，在双折叠展开态、三折叠展开态、平板等大屏幕场景下推荐四方向旋转并受控制中心的旋转开关控制。具体说明可参考为应用配置旋转策略。

• 窗口沉浸式

  为了更好的视觉观感，地图导航应用通常将底部的地图画布设置为全局沉浸。根据UX设计，需要实现不同窗口模式（全屏、分屏、悬浮窗）下窗口的沉浸式，可参考窗口沉浸式。全屏、分屏和悬浮窗的沉浸式均可通过setWindowLayoutFullscreen()实现，并进行动态安全区避让。

[h2]地图容器页

地图容器页是地图导航应用的基础页面，负责承载地图画布、操作按钮和业务内容面板。多设备效果图如下：

界面开发

在移动端的地图容器页，信息面板覆盖在地图画布上，主要包含以下区域：

在不同设备形态下，可以将设备的窗口断点映射为地图面板不同布局，屏蔽业务对设备类型的直接感知。覆盖式布局再根据断点细分为底部面板、底部Mini面板和悬浮面板。

交互开发

地图容器页主要处理容器级交互，不承载具体业务页面的交互逻辑，包含以下交互：

• 面板档位/位置切换：底部面板支持上下拖动切换高度档位，悬浮面板除了支持高度档位切换外，还支持左右拖动切换吸附位置。面板交互完成后，地图容器根据面板高度、侧边位置和可见状态重新计算地图可视区域，使地图Logo、定位控件和路线内容避开面板区域。

底部面板通过PanGesture监听上下拖动，悬浮面板通过PanGesture监听上下和左右拖动；面板高度或位置变化后，地图容器重新计算地图Padding，并调用Map Kit的MapComponentController.setPadding()更新地图可视区域。

面板档位/位置切换示意图如下所示（以首页为例）：

功能开发

地图容器页负责地图实例和地图基础能力的初始化，同时统一维护地图与业务面板之间的状态联动。首页、地点搜索、地点详情和路线规划等业务页面只更新业务状态，地图容器根据当前状态统一刷新地图内容，避免地图标记、选中地点和路线绘制分散在各个业务页面中处理。

地图容器页功能开发流程如下所示：

地图容器页主要包含以下功能：

• 创建地图组件：使用Map Kit（地图服务）的MapComponent创建地图实例，并通过回调获取MapComponentController，为后续定位、标记、路线绘制和地图避让提供控制入口。获取MapComponentController后，开启我的位置、复位按钮、实时路况和建筑物显示等地图基础能力；其中，复位按钮用于快速回到当前位置，底部面板场景下可隐藏缩放控件，避免控件与面板重叠。
• 设置当前位置：定位成功后，地图容器通过MapComponentController.setMyLocation()设置当前位置，并在坐标转换后通过MapComponentController.animateCamera()移动地图镜头，保证用户进入页面后能快速看到当前位置附近的地图内容。
• 更新业务状态：业务页面更新当前地图状态、选中地点、搜索结果和路线数据，地图容器监听状态变化，并统一触发地图内容刷新。
• 刷新地图内容：地图容器根据当前业务场景区分首页、搜索结果、地点详情和路线规划等场景。

[h2]首页

首页是用户进入应用后的默认业务面板，主要承载搜索入口、常用出行功能、地点推荐和快捷操作。该页面的目标是让用户快速发起搜索或选择目的地，同时尽量不破坏地图浏览体验。多设备效果图如下：

界面开发

在直板机和Pura X内屏上，首页内容放在底部面板中，低档位优先露出搜索入口和核心功能，高档位展示更多推荐内容。在Pura X外屏上，Mini面板减少内容密度，只保留搜索和关键操作。在双折叠、三折叠和平板上，首页面板以悬浮方式展示在地图侧边，用户可以一边浏览推荐地点，一边观察地图点位。

首页主要包含以下区域：

交互开发

首页主要包含以下交互：

• 搜索入口交互：用户点击搜索框时，通过点击事件触发回调自动将面板提升到高档位；以直板机为例，点击搜索框面板自动升高示意图如下：

  

[h2]地点搜索页

地点搜索页用于承接用户输入关键字后的结果展示。地图导航应用中，搜索结果列表和地图标记须保持一致：列表展示的地点需要同步显示在地图上，用户选择列表项后，地图也应聚焦到对应位置。效果图如下所示：

界面开发

在底部面板场景中，搜索结果随面板档位展开：中档位下展示主要结果，高档位展示更完整的列表。在Mini面板场景中，结果信息应简化，避免类方屏上地图被过度遮挡。在悬浮面板场景中，搜索结果列表固定在地图侧边，用户可以同时查看列表和标记点。地点搜索页主要包含以下区域：

[h2]地点详情页

地点详情页连接地点搜索和路线规划，是用户确认目的地、查看地址信息并发起导航的中间页面。该页面应在有限空间中优先展示地点名称、地址和导航入口，在宽屏空间中补充更多详情信息。多设备效果图如下：

界面开发

在直板机和Pura X内屏上，详情页通过底部面板展示，低档位保留地点名称和路线按钮，高档位展示完整详情。在Pura X外屏上，详情内容需要控制层级，避免占用过多地图区域。在双折叠、三折叠和平板上，详情面板浮在地图侧边，用户可以同时确认地点详情和地图位置。

地点详情页主要包含以下区域：

[h2]路线规划页

路线规划页是地图导航应用的核心业务页面。用户选择目的地后，页面需要展示起终点、出行方式、路线方案列表，并在地图上同步绘制路线。该页面既要保障路线信息清晰，也要保留足够地图空间观察路线走向。多设备效果图如下：

界面开发

在底部面板场景中，路线规划页中档位优先展示起终点、当前路线摘要和路线列表。在Mini面板场景中，路线信息需要聚焦起终点，减少多方案列表对地图的遮挡。在悬浮面板场景中，路线页面板位于地图侧边，用户可以同时查看路线摘要和地图走向。

路线规划页的具体信息和实现方案如下表所示：

交互开发

路线规划页主要包含以下交互：

• 返回地点详情：用户点击返回按钮时，页面通过按钮点击事件触发返回逻辑，调用路线清理回调并将地图状态恢复为地点详情状态，同时通过页面路由退栈NavPathStack.pop()返回上一页。路线清理后，地图侧重新展示当前地点标记，避免路线折线继续停留在详情场景中。

  以直板机为例，返回清除路线并恢复地点标记的示意图如下：

  

功能开发

路线规划页主要负责路线请求、路线结果处理和地图路线同步：

• 路线请求：页面进入时将地图状态切换为路线规划状态，并清理旧路线；随后优先使用当前定位作为起点，如果当前定位尚未就绪，则等待定位结果。起点坐标会通过map.convertCoordinateSync()完成坐标系转换，再使用Map Kit的navi.getDrivingRoutes()发起驾车路线规划，通过DrivingRouteParams传入起点origins、终点destination等参数。
• 路线结果处理：路线规划成功后，页面保存路径RouteResult.routes，并从首条路线的信息steps中提取RouteRoad数据，用于地图侧绘制路线；同时通过路线步骤中的duration和distance汇总总耗时与总距离，并在路线列表中展示不同路线方案。
• 路线地图同步：路线道路数据准备完成后，页面通过路线就绪回调将RouteRoad传递给地图容器。地图容器将RouteRoad.polyline转换为路线点位集合，调用MapComponentController.addPolyline()接口绘制路线折线，并通过MapPolylineOptions配置折线样式和箭头纹理；随后根据路线点位计算东北角和西南角边界，传入map.newLatLngBounds()生成镜头更新对象，并调用MapComponentController.animateCamera()将路线完整展示在当前地图可视区域内。

[h2]实况窗

导航类应用退到后台后，用户仍希望查看距离、车辆信息或导航状态。实况窗可以在通知中心和胶囊区域展示关键状态，减少用户频繁回到应用的操作。

阅读本章节前，开发者需熟悉Live View Kit简介及实况窗支持对接的场景，并进行开发准备。下面将详细介绍实况窗在“一多”开发中的实践。

界面开发

实况窗页支持卡片和胶囊两种形态，卡片形态的实况窗展示在通知中心，状态栏的实况窗表现为胶囊形态。点击实况胶囊后，可展示实况卡片。在直板机和折叠屏上，可以进行以下设计：

实况窗各场景的具体信息和实现方案如下表所示：

电脑端页面

本章介绍如何基于现有移动端界面开发方案，实现代码逻辑与布局复用，高效完成地图导航应用在电脑设备上的界面开发。电脑端的地图导航应用大部分交互逻辑与移动端应用类似，本章只展示两者的差异。

[h2]窗口适配

• 窗口模式

  地图导航应用在电脑端上支持全屏和自由窗口两种模式，具体实现可参考窗口模式。应用内使用响应式组件，即可根据窗口大小，自动适配全屏和自由窗口模式下的布局

• 窗口沉浸式

  据UX设计规范，需要实现全屏和自由窗口下的沉浸式效果，具体实现可参考窗口沉浸式。全屏模式下，通过window.setWindowLayoutFullscreen()实现沉浸式。自由窗口模式下，通过向window.setWindowDecorVisible()传入false隐藏标题栏，仅保留右上角三键，使页面内容延伸至标题栏区域，实现沉浸式显示效果。

[h2]地图容器页

电脑端地图容器页与移动端功能一致，信息面板固定在侧边栏，面板右侧承载地图画布和电脑端装饰工具栏。效果图如下所示：

界面开发

电脑端地图容器页使用嵌入式布局组织侧边栏、地图画布和工具栏，主要包含以下区域：

[h2]首页

电脑端首页固定展示在侧栏中，地图主区域保持完整可浏览状态。运行效果如下所示：

界面开发

电脑端首页固定展示在侧栏中，主要包含以下区域：

[h2]地点搜索页

电脑端地点搜索页在侧栏中展示搜索结果列表，在地图主区域同步展示搜索结果标记。运行效果如下所示：

界面开发

[h2]地点详情页

电脑端地点详情页固定在侧栏中，用户可以在确认地点信息的同时查看地图中的目的地位置。运行效果如下所示：

界面开发

电脑端地点详情页主要包含以下区域：

[h2]路线规划页

电脑端路线规划页在侧栏中展示起终点和路线方案，在地图主区域展示完整路线走向。运行效果如下所示：

界面开发

电脑端路线规划页主要包含以下区域：

示例代码

多设备地图导航界面