map

map 模块提供地图渲染接口，定义地图绘制、图像加载与SVG解析等渲染操作抽象。

Class Summary

OHOS::IMapRender

地图渲染抽象接口类，定义地图绘制的基础命令集

• 构造：无

• 成员函数：

  接口名称	功能简述
  BeginDraw	发起一系列绘制命令，设置地图渲染区域
  CommitDraw	提交当前绘制命令
  DrawPoints	绘制一组点
  DrawPolyline	绘制折线
  DrawPolygon	绘制多边形
  DrawRect	绘制矩形
  DrawBitmap	绘制位图
  DrawImage	绘制图片
  DrawText	绘制文本行
  MeasureText	测量文本尺寸
  DrawSvg	绘制SVG图像

• 使用包含头文件：#include "map_render_interface.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/map/map_render_interface.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：TextStyle、PointStyle、PaintType、StrokeStyle、MapPaintStyle、BitmapBufferInfo、ImageType、SvgType、SvgBufferInfo
• 模板形参：无

Functions

OHOS::IMapRender

BeginDraw

virtual void BeginDraw(int32_t width, int32_t height, Rect mapRect) = 0

功能说明

• 核心用途：发起一系列地图绘制命令，设定渲染画布的尺寸与视口区域
• 设计目的：为后续所有绘制操作建立渲染上下文，指定地图布局的范围边界
• 使用场景：在执行任何 Draw* 或 CommitDraw 调用之前，必须首先调用此接口初始化绘制会话

入参

名称	参数类型	详细说明	约束取值范围
width	int32_t	地图渲染的宽度限制，单位：像素	大于0
height	int32_t	地图渲染的高度限制，单位：像素	大于0
mapRect	Rect	地图布局的视口区域，定义地图在画布上的位置和大小	Rect 有效范围，left < right, top < bottom

CommitDraw

virtual void CommitDraw() = 0

功能说明

• 核心用途：提交当前批次的所有绘制命令，完成渲染输出
• 设计目的：将 BeginDraw 之后所有 Draw* 操作产生的绘制指令统一提交执行
• 使用场景：所有绘制命令执行完毕后调用，标志一次完整绘制流程的结束

DrawPoints

virtual void DrawPoints(Point *points, uint32_t pointNum, PointStyle *style) = 0

功能说明

• 核心用途：在地图上绘制一组点
• 设计目的：提供批量点绘制能力，用于地图兴趣点（POI）标注等场景
• 使用场景：需要在地图上标记多个位置点时调用

入参

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

DrawPolyline

virtual void DrawPolyline(Point *points, uint32_t pointNum, StrokeStyle *style) = 0

功能说明

• 核心用途：在地图上绘制折线，连接各断点形成路径
• 设计目的：提供折线绘制能力，用于地图路线规划、道路绘制等场景
• 使用场景：需要在地图上绘制路线、道路等折线图形时调用

入参

名称	参数类型	详细说明	约束取值范围
points	Point *	入参指针，折线各断点的坐标数组	非 nullptr，数组长度不小于 pointNum
pointNum	uint32_t	折线断点的数量	大于等于2
style	StrokeStyle *	入参指针，折线的描边样式，包含画笔宽度、颜色、虚线模式等	非 nullptr

DrawPolygon

virtual void DrawPolygon(Point *points, uint32_t pointNum, MapPaintStyle *style) = 0

功能说明

• 核心用途：在地图上绘制多边形，连接各断点形成封闭区域
• 设计目的：提供多边形绘制能力，用于地图区域标注、行政区划绘制等场景
• 使用场景：需要在地图上绘制区域、面状图形时调用

入参

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

DrawRect

virtual void DrawRect(Rect rect, MapPaintStyle *style, float angle) = 0

功能说明

• 核心用途：在地图上绘制矩形，支持旋转
• 设计目的：提供旋转矩形绘制能力，用于地图图例、标注框等场景
• 使用场景：需要在地图上绘制矩形区域或标注框时调用

入参

名称	参数类型	详细说明	约束取值范围
rect	Rect	待绘制矩形的区域	Rect 有效范围，left < right, top < bottom
style	MapPaintStyle *	入参指针，矩形的画笔样式，包含填充颜色、描边样式和填充类型	非 nullptr
angle	float	矩形顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawBitmap

virtual void DrawBitmap(BitmapBufferInfo *buffer, Rect rect, float angle) = 0

功能说明

• 核心用途：在地图上绘制位图，支持旋转
• 设计目的：提供位图绘制能力，用于地图图标、瓦片等场景
• 使用场景：需要在地图上渲染位图资源时调用

入参

名称	参数类型	详细说明	约束取值范围
buffer	BitmapBufferInfo *	入参指针，位图数据信息，包含像素缓冲区、颜色格式、尺寸等	非 nullptr
rect	Rect	位图绘制的目标区域	Rect 有效范围
angle	float	位图顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawImage

virtual void DrawImage(ImageBufferInfo *image, Rect rect, float angle) = 0

功能说明

• 核心用途：在地图上绘制图片（JPEG格式），支持旋转
• 设计目的：提供图片绘制能力，用于地图图钉图标等场景
• 使用场景：需要在地图上渲染JPEG图片资源时调用

入参

名称	参数类型	详细说明	约束取值范围
image	ImageBufferInfo *	入参指针，图片数据信息，包含图像缓冲区、格式、尺寸等	非 nullptr，uuid 须为有效标识
rect	Rect	图片绘制的目标区域	Rect 有效范围
angle	float	图片顺时针旋转角度，旋转中心为矩形中心	单位：度

DrawText

virtual void DrawText(Point center, const char *text, TextStyle *style, float angle) = 0

功能说明

• 核心用途：在地图上绘制文本行，支持旋转
• 设计目的：提供文本绘制能力，用于地图地名标注、信息标签等场景
• 使用场景：需要在地图上渲染文字标注时调用

入参

名称	参数类型	详细说明	约束取值范围
center	Point	文本绘制的中心位置，同时作为旋转中心	Point 有效坐标范围
text	const char *	入参指针，待绘制的字符串	非 nullptr
style	TextStyle *	入参指针，文本绘制样式，包含字体名、字号、字间距、颜色	非 nullptr
angle	float	文本顺时针旋转角度	单位：度

MeasureText

virtual bool MeasureText(const char *text, TextStyle *style, int32_t *width, int32_t *height) = 0

功能说明

• 核心用途：测量指定文本在给定样式下的像素尺寸
• 设计目的：提供文本尺寸查询能力，用于布局计算和文本排版
• 使用场景：绘制文本前需确定文本宽高以进行布局定位时调用

入参

名称	参数类型	详细说明	约束取值范围
text	const char *	入参指针，待测量的字符串	非 nullptr
style	TextStyle *	入参指针，文本样式，包含字体名、字号等	非 nullptr

出参

名称	数据类型	输出说明
width	int32_t *	出参指针，测量得到的文本宽度，单位：像素
height	int32_t *	出参指针，测量得到的文本高度，单位：像素

返回值

• 返回类型：bool

返回测量操作结果

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

DrawSvg

virtual void DrawSvg(SvgBufferInfo *svg, Rect rect, float angle) = 0

功能说明

• 核心用途：在地图上绘制SVG图像，支持旋转
• 设计目的：提供SVG矢量图绘制能力，用于地图矢量图标渲染等场景
• 使用场景：需要在地图上渲染SVG格式矢量图形时调用

入参

名称	参数类型	详细说明	约束取值范围
svg	SvgBufferInfo *	入参指针，SVG数据信息，包含缓冲区、格式、尺寸等	非 nullptr，uuid 须为有效标识
rect	Rect	SVG绘制的目标区域	Rect 有效范围
angle	float	SVG顺时针旋转角度，旋转中心为矩形中心	单位：度

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	字体颜色

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认为是有效标识，不支持无效标识