我在哪里

功能描述

“我在哪里”能力用于提供车辆当前位置相关的道路与区域上下文信息，供上层 HMI 或业务模块按需消费。 该能力依赖地图匹配输出 PositionInfo，可在 on-road / off-road 不同状态下提供对应信息字段。

能力边界

• SDK 负责输出位置上下文字段，不负责 UI 展示与文案渲染。
• 上层应用基于字段可用性决定最终页面布局、文案与交互。

输出字段清单

输出字段来源于地图匹配回调参数 PositionInfo，详见 开发指南/地图匹配/地图匹配输出

已匹配到道路（on-road）时：

• 通过 currentRoad（RoadInfo）获取当前路名等道路信息。
• 通过 aheadIntersection / behindIntersection 获取前后路口信息，包括路口名称、距离和坐标。

未匹配到道路（off-road）时：

• 通过 nearbyRoad 获取最近可参考道路，并展示路名、距离等信息。

通用（on-road/off-road 均可能提供）：

• 通过 regionalInfo 获取区域层级信息，如国家、洲、省/县、城市、街区等。

输出时机与状态判定

• SDK 通过 onLocationUpdated(vehicleLocation, positionInfo) 持续输出最新信息。
• positionInfo.isOffRoad() 用于判定当前是否未匹配道路。
• 当 on-road/off-road 状态变化时，上层应按最新字段重新消费数据。

UI 展示建议

已匹配到道路（on-road）

• 主信息：currentRoad.roadName（或 combinedRoadName）。
• 辅助信息：aheadIntersection / behindIntersection（路口名称、距离、坐标）。
• 建议优先展示“前方路口 + 距离”，用于提升驾驶决策可读性。
• 效果示例：显示“当前道路 + 前方路口（距离） + 后方路口（距离）”。

未匹配到道路（off-road）

• 主信息：nearbyRoad 的最近道路名称与距离。
• 辅助信息：regionalInfo 的国家、洲、省/县、城市、街区等层级信息。
• 若 nearbyRoad 暂无有效值，显示“附近无可用道路信息”。
• 效果示例：显示“附近道路 + 距离 + 城市”。