ui_amap_view

ui_amap_view 模块提供高德地图视图组件，用于在UI中嵌入地图显示与交互。

Class Summary

OHOS::UIAMapView

地图渲染视图控件，将地图渲染接口与 GUI 视图框架结合，支持在画布上绘制点、线、多边形、矩形、位图、图片、文字及 SVG 等图元

• 构造：无

• 成员函数：

  接口名称	功能简述
  BeginDraw	开始一帧地图绘制，设定绘制区域尺寸与视口范围
  CommitDraw	提交当前帧的全部绘制指令
  DrawPoints	按指定样式绘制一组点
  DrawPolyline	按指定描边样式绘制折线
  DrawPolygon	按指定填充与描边样式绘制多边形
  DrawRect	按指定填充与描边样式绘制旋转矩形
  DrawBitmap	在指定区域绘制位图
  DrawImage	在指定区域绘制图片
  DrawText	在指定中心位置绘制旋转文字
  MeasureText	测量指定文字在给定样式下的宽高尺寸
  DrawSvg	在指定区域绘制 SVG 图形
  Callback	任务回调入口，由 TaskManager 周期调用以驱动渲染任务

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

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

Functions

OHOS::UIAMapView

BeginDraw

void BeginDraw(int32_t width, int32_t height, Rect mapRect) override

功能说明

• 核心用途：发起一帧地图绘制流程，设定地图渲染的宽度、高度限制与视口矩形区域
• 设计目的：作为地图渲染管线的入口，建立绘制上下文，其他 Draw 系列接口基于此上下文执行绘制
• 使用场景：地图数据更新后、视口范围变化时，在绘制任何图元之前调用

入参

名称	参数类型	详细说明	约束取值范围
width	int32_t	地图渲染宽度限制，单位：像素	大于 0
height	int32_t	地图渲染高度限制，单位：像素	大于 0
mapRect	Rect	地图视口矩形区域，定义绘制区域的位置与范围	Rect 坐标有效

CommitDraw

void CommitDraw() override

功能说明

• 核心用途：提交当前帧的全部绘制指令，将缓冲区内容刷新到显示层
• 设计目的：标志一帧绘制流程结束，触发画布内容提交与资源回收
• 使用场景：所有 Draw 系列接口调用完成后调用，与 BeginDraw 配对使用

DrawPoints

void DrawPoints(Point *points, uint32_t pointNum, PointStyle *style) override

功能说明

• 核心用途：按指定点样式绘制一组离散点
• 设计目的：提供地图上的兴趣点（POI）标注渲染能力
• 使用场景：地图上标注关键位置、路径节点等点状图元

入参

名称	参数类型	详细说明	约束取值范围
points	Point *	入参指针，指向待绘制点坐标数组	非 nullptr，数组长度不小于 pointNum
pointNum	uint32_t	待绘制点的数量	大于 0
style	PointStyle *	入参指针，指向点样式描述	非 nullptr

DrawPolyline

void DrawPolyline(Point *points, uint32_t pointNum, StrokeStyle *style) override

功能说明

• 核心用途：按指定描边样式绘制折线
• 设计目的：提供地图路径、路线等线状图元渲染能力
• 使用场景：绘制导航路线、道路网络、边界线等折线图元

入参

名称	参数类型	详细说明	约束取值范围
points	Point *	入参指针，指向折线拐点坐标数组	非 nullptr，数组长度不小于 pointNum
pointNum	uint32_t	折线拐点数量	大于等于 2
style	StrokeStyle *	入参指针，指向描边样式描述	非 nullptr

DrawPolygon

void DrawPolygon(Point *points, uint32_t pointNum, MapPaintStyle *style) override

功能说明

• 核心用途：按指定填充与描边样式绘制多边形
• 设计目的：提供地图区域填充、行政区划等面状图元渲染能力
• 使用场景：绘制行政区划区域、地标区域、水域等多边形图元

入参

名称	参数类型	详细说明	约束取值范围
points	Point *	入参指针，指向多边形顶点坐标数组	非 nullptr，数组长度不小于 pointNum
pointNum	uint32_t	多边形顶点数量	大于等于 3
style	MapPaintStyle *	入参指针，指向画笔样式描述（含填充色与描边样式）	非 nullptr

DrawRect

void DrawRect(Rect rect, MapPaintStyle *style, float angle) override

功能说明

• 核心用途：按指定填充与描边样式绘制可旋转矩形
• 设计目的：提供地图上矩形区域标注的渲染能力，支持绕中心旋转
• 使用场景：绘制地图上的矩形标注框、建筑轮廓等

入参

名称	参数类型	详细说明	约束取值范围
rect	Rect	矩形区域定义	Rect 坐标有效
style	MapPaintStyle *	入参指针，指向画笔样式描述	非 nullptr
angle	float	顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawBitmap

void DrawBitmap(BitmapBufferInfo *buffer, Rect rect, float angle) override

功能说明

• 核心用途：在指定区域绘制位图，支持旋转
• 设计目的：提供地图上像素级位图渲染能力，用于渲染已解码的位图数据
• 使用场景：渲染地图瓦片位图、图标位图等像素数据

入参

名称	参数类型	详细说明	约束取值范围
buffer	BitmapBufferInfo *	入参指针，指向位图缓冲区信息描述	非 nullptr，buffer 成员非 nullptr
rect	Rect	位图绘制区域	Rect 坐标有效
angle	float	顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawImage

void DrawImage(ImageBufferInfo *image, Rect rect, float angle) override

功能说明

• 核心用途：在指定区域绘制图片，支持旋转
• 设计目的：提供地图上图片渲染能力，支持 JPEG 等压缩格式的图片数据
• 使用场景：渲染地图图标、标注图片等压缩格式图像

入参

名称	参数类型	详细说明	约束取值范围
image	ImageBufferInfo *	入参指针，指向图片缓冲区信息描述	非 nullptr，uuid 须为有效标识
rect	Rect	图片绘制区域	Rect 坐标有效
angle	float	顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawText

void DrawText(Point center, const char *text, TextStyle *style, float angle) override

功能说明

• 核心用途：在指定中心位置绘制可旋转文字
• 设计目的：提供地图上文字标注渲染能力，支持自定义字体、字号、颜色和旋转角度
• 使用场景：绘制地图上的地名标注、路名标注、距离标注等文字图元

入参

名称	参数类型	详细说明	约束取值范围
center	Point	文字绘制中心坐标，同时作为旋转中心	坐标有效
text	const char *	入参只读指针，指向待绘制的文字内容	非 nullptr，以 '\0' 结尾
style	TextStyle *	入参指针，指向文字样式描述	非 nullptr
angle	float	顺时针旋转角度	单位：度

MeasureText

bool MeasureText(const char *text, TextStyle *style, int32_t *width, int32_t *height) override

功能说明

• 核心用途：测量指定文字在给定样式下的宽高尺寸
• 设计目的：为文字布局提供尺寸预计算能力，用于在绘制前确定文字占位区域
• 使用场景：文字标注布局计算、自动换行判定、文字居中对齐计算

入参

名称	参数类型	详细说明	约束取值范围
text	const char *	入参只读指针，指向待测量的文字内容	非 nullptr，以 '\0' 结尾
style	TextStyle *	入参指针，指向文字样式描述	非 nullptr
width	int32_t *	出参指针，由被调用方写入测量所得文字宽度	非 nullptr
height	int32_t *	出参指针，由被调用方写入测量所得文字高度	非 nullptr

出参

名称	数据类型	输出说明
width	int32_t *	出参指针，写入文字宽度值，单位：像素
height	int32_t *	出参指针，写入文字高度值，单位：像素

返回值

• 返回类型：bool

返回文字测量结果状态

返回值	触发场景
true(1)	文字测量成功
false(0)	文字测量失败

DrawSvg

void DrawSvg(SvgBufferInfo *svg, Rect rect, float angle) override

功能说明

• 核心用途：在指定区域绘制 SVG 图形，支持旋转
• 设计目的：提供地图上矢量图形渲染能力，支持序列化 SVG 数据
• 使用场景：渲染地图矢量图标、复合矢量标注等 SVG 图形

入参

名称	参数类型	详细说明	约束取值范围
svg	SvgBufferInfo *	入参指针，指向 SVG 缓冲区信息描述	非 nullptr，uuid 须为有效标识
rect	Rect	SVG 绘制区域	Rect 坐标有效
angle	float	顺时针旋转角度，旋转中心为矩形中心	单位：度

Callback

void Callback() override

功能说明

• 核心用途：任务回调入口，由 TaskManager 周期调用以驱动地图渲染任务
• 设计目的：实现 Task 基类的纯虚回调接口，将地图渲染纳入 GUI 任务调度体系
• 使用场景：TaskManager 在每个任务周期内自动调用，无需用户手动调用

Enumerations

IMapRender::PaintType

enum class PaintType {
    PAINT_TYPE_FILL_ONLY,
    PAINT_TYPE_FILL_AND_STROKE,
    PAINT_TYPE_STROKE_ONLY
};

枚举成员	取值	描述
PAINT_TYPE_FILL_ONLY	0	仅填充几何图形
PAINT_TYPE_FILL_AND_STROKE	1	填充几何图形并描边
PAINT_TYPE_STROKE_ONLY	2	仅描边

IMapRender::ImageType

enum class ImageType {
    IMG_TYPE_JPEG,
    IMG_TYPE_MAX
};

枚举成员	取值	描述
IMG_TYPE_JPEG	0	JPEG 格式图片
IMG_TYPE_MAX	1	无效格式边界值

IMapRender::SvgType

enum class SvgType {
    SVG_TYPE_SERIALIZED,
    SVG_TYPE_MAX
};

枚举成员	取值	描述
SVG_TYPE_SERIALIZED	0	序列化的 SVG 文件
SVG_TYPE_MAX	1	无效格式边界值

Structures

IMapRender::TextStyle

typedef struct {
    const char* fontName;
    uint32_t fontSize;
    int16_t letterSpace;
    ColorType color;
} TextStyle;

成员说明

成员名称	数据类型	描述
fontName	const char*	字库文件名
fontSize	uint32_t	字体大小，单位：像素
letterSpace	int16_t	字间距，单位：像素
color	ColorType	字体颜色，ARGB 格式

IMapRender::PointStyle

typedef struct {
    uint32_t radius;
    ColorType color;
} PointStyle;

成员说明

成员名称	数据类型	描述
radius	uint32_t	点半径，单位：像素
color	ColorType	画笔颜色，ARGB 格式

IMapRender::StrokeStyle

typedef struct {
    uint32_t  strokeWidth;
    ColorType strokeColor;
    uint32_t dashCount;
    float *dashArray;
    int32_t dashOffset;
} StrokeStyle;

成员说明

成员名称	数据类型	描述
strokeWidth	uint32_t	画笔宽度，单位：像素
strokeColor	ColorType	画笔颜色，ARGB 格式
dashCount	uint32_t	虚线模式数量
dashArray	float *	虚线模式数组指针
dashOffset	int32_t	虚线偏移量

IMapRender::MapPaintStyle

typedef struct {
    ColorType fillColor;
    StrokeStyle strokeStyle;
    Paint::PaintStyle paintType;
} MapPaintStyle;

成员说明

成员名称	数据类型	描述
fillColor	ColorType	填充颜色，ARGB 格式
strokeStyle	StrokeStyle	描边样式
paintType	Paint::PaintStyle	填充样式类型

IMapRender::BitmapBufferInfo

typedef struct {
    ColorMode colorMode;
    uint8_t compressMode;
    uint8_t *buffer;
    uint32_t bufferSize;
    uint32_t width;
    uint32_t height;
    uint32_t stride;
    bool preMultiplied;
    char *uuid;
} BitmapBufferInfo;

成员说明

成员名称	数据类型	描述
colorMode	ColorMode	位图格式
compressMode	uint8_t	压缩格式
buffer	uint8_t *	位图 buffer 内容，地址需考虑 GPU 对齐要求
bufferSize	uint32_t	位图 buffer 大小
width	uint32_t	位图宽度，单位：像素
height	uint32_t	位图高度，单位：像素
stride	uint32_t	位图每一行像素所占用的实际字节数，需考虑 GPU 对齐要求
preMultiplied	bool	是否已经预乘 alpha 值，仅 ARGB8888 有效
uuid	char *	图像唯一标识，大于 0 认为是有效标识，不强制要求有效标识

IMapRender::ImageBufferInfo

typedef struct {
    ImageType imageType;
    uint8_t *buffer;
    uint32_t bufferSize;
    char *uuid;
} ImageBufferInfo;

成员说明

成员名称	数据类型	描述
imageType	ImageType	图像内容格式
buffer	uint8_t *	图像 buffer 内容，地址需考虑 GPU 对齐要求
bufferSize	uint32_t	图像 buffer 大小
uuid	char *	图像唯一标识，大于 0 认为是有效标识，不支持无效标识

IMapRender::SvgBufferInfo

typedef struct {
    SvgType svgType;
    uint8_t *buffer;
    uint32_t bufferSize;
    char *uuid;
} SvgBufferInfo;

成员说明

成员名称	数据类型	描述
svgType	SvgType	SVG 内容格式
buffer	uint8_t *	SVG 文件内容
bufferSize	uint32_t	SVG 文件大小
uuid	char *	SVG 唯一标识，大于 0 认为是有效标识，不支持无效标识