ui_map_view

ui_map_view 模块提供地图视图组件，支持地图显示与兴趣点（POI）点击事件监听。

Class Summary

OHOS::OnPOIClickListener

地图 POI 点击事件的监听器基类，用于接收 POI 点击回调

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnClick	POI 被点击时的回调函数

• 使用包含头文件：#include "components/ui_map_view.h"

• 声明头文件：middleware/services/gui/uikit/proprietary/include/components/ui_map_view.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

OHOS::UIMapView

地图视图组件，支持 SVG 地图渲染、缩放、POI 显示与缓存管理

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取当前视图类型
  SetSVG	通过文件路径设置 SVG 地图源
  SetSVG	通过内存缓冲区设置 SVG 地图源
  SetOnPOIClickListener	设置 POI 点击事件监听器
  EnableCache	启用或禁用地图缓存
  ScaleMap	基于指定锚点缩放地图
  HidePOI	按标签隐藏或显示 POI
  SetX	设置视图 X 坐标位置
  SetY	设置视图 Y 坐标位置

• 使用包含头文件：#include "components/ui_map_view.h"

• 声明头文件：middleware/services/gui/uikit/proprietary/include/components/ui_map_view.h
• 公有运算符：无
• 继承关系：UIViewGroup, UIView::OnClickListener
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::OnPOIClickListener

OnClick

virtual bool OnClick(uint32_t index)

功能说明

• 核心用途：当 POI 被点击时触发的回调函数
• 设计目的：为子类提供 POI 点击事件的响应接口，子类可重写该方法实现自定义点击逻辑
• 使用场景：用户点击地图上的 POI 时，框架调用该回调通知监听器

入参

名称	参数类型	详细说明	约束取值范围
index	uint32_t	被点击 POI 的索引	0 ~ POI 总数 - 1

返回值

• 返回类型：bool

返回点击事件是否被消费

返回值	触发场景
true(1)	点击事件已被消费
false(0)	点击事件未被消费（默认实现返回 false）

OHOS::UIMapView

GetViewType

virtual UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 设计目的：用于框架在视图类型判断和分发时识别 UIMapView 组件
• 使用场景：框架内部视图类型判断、视图遍历与筛选

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_MAP_VIEW	始终返回地图视图类型

SetSVG

bool SetSVG(const char* path)

功能说明

• 核心用途：通过文件路径设置 SVG 地图数据源
• 设计目的：从文件系统加载 SVG 格式的地图资源并解析渲染
• 使用场景：应用启动时或地图切换时，从文件系统加载 SVG 地图

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• 传入的文件路径对应的文件存在且可读

入参

名称	参数类型	详细说明	约束取值范围
path	const char*	SVG 文件路径，入参只读指针，不修改所指对象	非空字符串，指向合法文件路径

返回值

• 返回类型：bool

返回 SVG 设置是否成功

返回值	触发场景
true(1)	SVG 加载并解析成功
false(0)	SVG 加载或解析失败

SetSVG

bool SetSVG(uint8_t* data, uint32_t length)

功能说明

• 核心用途：通过内存缓冲区设置 SVG 地图数据源
• 设计目的：从内存中加载 SVG 格式的地图资源并解析渲染，适用于地图数据已在内存中的场景
• 使用场景：地图数据已加载到内存中（如从网络下载或资源包解压后），无需文件系统访问

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• 传入的数据缓冲区在调用期间保持有效

入参

名称	参数类型	详细说明	约束取值范围
data	uint8_t*	SVG 数据缓冲区指针，入参指针，不可为 nullptr	非空，指向有效的 SVG 数据
length	uint32_t	数据缓冲区长度（字节数）	> 0

返回值

• 返回类型：bool

返回 SVG 设置是否成功

返回值	触发场景
true(1)	SVG 加载并解析成功
false(0)	SVG 加载或解析失败

SetOnPOIClickListener

void SetOnPOIClickListener(OnPOIClickListener* listener)

功能说明

• 核心用途：设置 POI 点击事件的监听器
• 设计目的：为地图视图注册 POI 点击回调，当用户点击 POI 时触发监听器的 OnClick 方法
• 使用场景：需要在地图上响应 POI 点击交互时调用

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• UIMapView 对象已构造完成

入参

名称	参数类型	详细说明	约束取值范围
listener	OnPOIClickListener*	POI 点击监听器指针，入参指针	可为 nullptr（取消监听）或指向有效的 OnPOIClickListener 派生类对象

EnableCache

void EnableCache(bool enable)

功能说明

• 核心用途：启用或禁用地图渲染缓存
• 设计目的：开启缓存时立即缓存当前瓦片渲染结果，关闭缓存时立即释放缓存缓冲区；用于优化地图渲染性能
• 使用场景：设置 SVG 后或缩放完成后应启用缓存，缩放地图前应禁用缓存

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• UIMapView 对象已构造完成

入参

名称	参数类型	详细说明	约束取值范围
enable	bool	是否启用缓存	true：启用缓存；false：禁用缓存

ScaleMap

void ScaleMap(float scale, const Vector2<float>& pivot)

功能说明

• 核心用途：基于指定锚点对地图进行缩放
• 设计目的：以给定的缩放比例和锚点位置对地图内容进行缩放变换
• 使用场景：用户双指缩放或点击缩放控件时调用；缩放前应禁用缓存，缩放完成后应重新启用缓存

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• 缩放前应调用 EnableCache(false) 禁用缓存
• UIMapView 已通过 SetSVG 设置了有效的 SVG 数据源

入参

名称	参数类型	详细说明	约束取值范围
scale	float	缩放比例，入参只读	> 0.0f
pivot	const Vector2&	缩放锚点坐标，入参只读引用	坐标值在视图范围内

HidePOI

void HidePOI(uint16_t tag, bool isHide = true)

功能说明

• 核心用途：按标签隐藏或显示指定 POI
• 设计目的：支持按标签分组控制 POI 的可见性，实现 POI 的分类显示与隐藏
• 使用场景：按类别过滤地图上的 POI 显示（如隐藏某类兴趣点）

前置条件

• 模块宏 ENABLE_VGU_ENGINE 和 CAPABILITY_HWDRAW_PATH 已开启
• UIMapView 已通过 SetSVG 设置了有效的 SVG 数据源

入参

名称	参数类型	详细说明	约束取值范围
tag	uint16_t	POI 标签值	0 ~ 255
isHide	bool	是否隐藏，缺省值为 true	true：隐藏；false：显示

SetX

virtual void SetX(int16_t x) override

功能说明

• 核心用途：设置地图视图的 X 坐标位置
• 设计目的：重写基类方法，在设置 X 坐标时同步更新地图内部渲染位置
• 使用场景：调整地图视图在父容器中的水平位置

入参

名称	参数类型	详细说明	约束取值范围
x	int16_t	视图 X 坐标位置	INT16_MIN ~ INT16_MAX

SetY

virtual void SetY(int16_t y) override

功能说明

• 核心用途：设置地图视图的 Y 坐标位置
• 设计目的：重写基类方法，在设置 Y 坐标时同步更新地图内部渲染位置
• 使用场景：调整地图视图在父容器中的垂直位置

入参

名称	参数类型	详细说明	约束取值范围
y	int16_t	视图 Y 坐标位置	INT16_MIN ~ INT16_MAX

Enumerations

MapCacheGroup

typedef enum {
    MAP_CACHE_GROUP_BACKGROUND = 0,
    MAP_CACHE_GROUP_PATH = 1,
    MAP_CACHE_GROUP_ROAD = 2,
    MAP_CACHE_GROUP_POI = 3
} MapCacheGroup;

枚举成员	取值	描述
MAP_CACHE_GROUP_BACKGROUND	0	背景图层缓存分组
MAP_CACHE_GROUP_PATH	1	路径图层缓存分组
MAP_CACHE_GROUP_ROAD	2	道路图层缓存分组
MAP_CACHE_GROUP_POI	3	POI 图层缓存分组

Structures

POIInfo

struct POIInfo {
    ImageDetail* img = nullptr;
    TextDetail* text[2] = {nullptr, nullptr};
    uint8_t tag = 0;
    uint16_t rank = 0;
    uint16_t id = 0;
    Rect rect;
    Point orignPos = {0, 0};
    bool visible = false;
    bool needUpdateVisible = false;
};

成员说明

成员名称	数据类型	描述
img	ImageDetail*	POI 关联的图片详情指针
text	TextDetail*[2]	POI 关联的文本详情指针数组
tag	uint8_t	POI 标签，用于分类分组，取值范围 0 ~ 255
rank	uint16_t	POI 排序权重
id	uint16_t	POI 唯一标识
rect	Rect	POI 显示区域矩形
orignPos	Point	POI 原始位置坐标
visible	bool	POI 是否可见
needUpdateVisible	bool	POI 可见性是否需要更新

RoadInfo

struct RoadInfo {
    TextDetail* text = nullptr;
    Rect rect;
    Point orignPos = {0, 0};
    bool visible = false;
};

成员说明

成员名称	数据类型	描述
text	TextDetail*	道路关联的文本详情指针
rect	Rect	道路显示区域矩形
orignPos	Point	道路原始位置坐标
visible	bool	道路是否可见