ui_image_view

ui_image_view 模块提供图像视图组件，支持图片显示、自动调整与像素格式转换。

Class Summary

OHOS::UIImageView

图片视图控件，用于显示图片资源并支持图片缩放、旋转、模糊等变换操作

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  GetWidth	获取图片视图宽度
  GetHeight	获取图片视图高度
  OnPreDraw	检查图片视图是否需要被覆盖以优化绘制流程
  OnDraw	绘制图片视图
  SetSrc	设置图片路径或图片信息
  SetAutoEnable	设置图片视图尺寸是否自适应图片尺寸
  GetAutoEnable	获取自适应使能状态
  SetBlurLevel	设置图片旋转或缩放时的模糊级别
  GetBlurLevel	获取图片旋转或缩放时的模糊级别
  SetTransformAlgorithm	设置图片旋转和缩放使用的变换算法
  GetTransformAlgorithm	获取图片旋转和缩放使用的变换算法
  GetPath	获取图片路径
  GetImageInfo	获取图片信息
  GetSrcType	获取图片源类型
  SetResizeMode	设置图片缩放模式
  SetWidth	设置图片视图宽度
  SetHeight	设置图片视图高度
  GetResizeMode	获取图片缩放模式
  GetGifImageAnimator	获取GIF图片动画控制器
  DumpImgInfo	打印图片信息
  GetGuiInfo	获取图片视图GUI调试信息
  SetColor	设置图片颜色

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_image_view.h
• 公有运算符：无
• 继承关系：UIView
• 嵌套类型：ImageResizeMode（公有枚举）
• 模板形参：无

Functions

OHOS::UIImageView

GetViewType

virtual UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回值固定为 UI_IMAGE_VIEW，用于在视图树中区分图片视图与其他视图类型
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_IMAGE_VIEW	当前视图为图片视图

GetWidth

virtual int16_t GetWidth() override

功能说明

• 核心用途：获取图片视图的宽度
• 当自适应使能且需要刷新时，会先触发重新测量再返回宽度
• 该函数重写基类 UIView 的 GetWidth 方法

返回值

• 返回类型：int16_t

返回图片视图宽度值

返回值	触发场景
>= 0	图片视图的实际宽度

GetHeight

virtual int16_t GetHeight() override

功能说明

• 核心用途：获取图片视图的高度
• 当自适应使能且需要刷新时，会先触发重新测量再返回高度
• 该函数重写基类 UIView 的 GetHeight 方法

返回值

• 返回类型：int16_t

返回图片视图高度值

返回值	触发场景
>= 0	图片视图的实际高度

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 核心用途：检查图片视图是否需要被覆盖以优化绘制流程
• 当图片源类型为未知时返回 true，表示跳过绘制
• 当颜色格式为 RGB565 或 RGB888 且无效区域包含在视图区域内时返回 true
• 该函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
invalidatedArea	Rect&	待绘制的无效区域，入参引用，可能被截断为与视图区域的交集	有效的 Rect 对象

返回值

• 返回类型：bool

返回是否需要被覆盖

返回值	触发场景
true	图片源未知或颜色格式为RGB565/RGB888且无效区域在视图内部
false	需要正常绘制

OnDraw

void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

• 核心用途：绘制图片视图内容到目标缓冲区
• 根据图片源类型（文件路径或数组信息）选择不同的绘制路径
• 存在变换映射时使用变换绘制，否则使用平铺绘制

入参

名称	参数类型	详细说明	约束取值范围
gfxDstBuffer	BufferInfo&	图形目标缓冲区，入参引用，写入绘制内容	有效的 BufferInfo 对象
invalidatedArea	const Rect&	待绘制的无效区域，入参只读引用	有效的 Rect 对象

SetSrc

virtual void SetSrc(const char* src) virtual void SetSrc(const ImageInfo* src)

功能说明

• 核心用途：设置图片源，支持通过文件路径或图片信息数组两种方式
• 设置文件路径时，若启用 GIF 支持且文件为 GIF 格式，会自动创建并启动 GIF 动画控制器
• 设置成功后会触发重新测量和视图刷新
• 该函数为 virtual 成员函数，允许子类重写

入参

名称	参数类型	详细说明	约束取值范围
src	const char*	图片文件路径，入参只读指针，不可为 nullptr	有效的文件路径字符串
src	const ImageInfo*	图片信息指针，入参只读指针，不可为 nullptr	有效的 ImageInfo 对象指针

SetAutoEnable

void SetAutoEnable(bool enable)

功能说明

• 核心用途：设置图片视图尺寸是否自适应图片尺寸
• 启用自适应后，视图尺寸将自动调整为与图片尺寸一致
• 从禁用切换为启用时会触发刷新标记并更新变换映射

入参

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

GetAutoEnable

bool GetAutoEnable() const

功能说明

• 核心用途：获取图片视图自适应使能状态
• 该函数为 const 成员函数，不修改对象状态
• 返回值为构造时初始化的默认状态或通过 SetAutoEnable 设置的值

返回值

• 返回类型：bool

返回自适应使能状态

返回值	触发场景
true	自适应已启用
false	自适应已禁用

SetBlurLevel

void SetBlurLevel(BlurLevel level)

功能说明

• 核心用途：设置图片在旋转或缩放时的模糊级别
• 模糊级别影响图片变换后的渲染质量
• 设置后在下一次绘制时生效

入参

名称	参数类型	详细说明	约束取值范围
level	BlurLevel	模糊级别	BlurLevel 枚举值

GetBlurLevel

BlurLevel GetBlurLevel() const

功能说明

• 核心用途：获取图片在旋转或缩放时的模糊级别
• 该函数为 const 成员函数，不修改对象状态
• 返回值为通过 SetBlurLevel 设置的值或默认值 LEVEL0

返回值

• 返回类型：BlurLevel

返回模糊级别

返回值	触发场景
LEVEL0	无模糊（默认值）
LEVEL1	模糊一行
LEVEL2	模糊两行

SetTransformAlgorithm

void SetTransformAlgorithm(TransformAlgorithm algorithm)

功能说明

• 核心用途：设置图片旋转和缩放使用的变换算法
• 不同算法在渲染质量与性能之间有不同的权衡
• 设置后在下一次绘制时生效

入参

名称	参数类型	详细说明	约束取值范围
algorithm	TransformAlgorithm	图片变换算法	TransformAlgorithm 枚举值

GetTransformAlgorithm

TransformAlgorithm GetTransformAlgorithm() const

功能说明

• 核心用途：获取图片旋转和缩放使用的变换算法
• 该函数为 const 成员函数，不修改对象状态
• 返回值为通过 SetTransformAlgorithm 设置的值或默认值 BILINEAR

返回值

• 返回类型：TransformAlgorithm

返回变换算法

返回值	触发场景
NEAREST_NEIGHBOR	最近邻插值算法
BILINEAR	双线性插值算法（默认值）

GetPath

const char* GetPath() const

功能说明

• 核心用途：获取图片文件路径
• 该函数为 const 成员函数，不修改对象状态
• 仅当图片源为文件路径时返回有效值

返回值

• 返回类型：const char*

返回图片路径字符串指针

返回值	触发场景
非 nullptr	图片源为文件路径
nullptr	图片源非文件路径或未设置

GetImageInfo

const ImageInfo* GetImageInfo() const

功能说明

• 核心用途：获取图片信息
• 该函数为 const 成员函数，不修改对象状态
• 仅当图片源为数组信息时返回有效值

返回值

• 返回类型：const ImageInfo*

返回图片信息指针

返回值	触发场景
非 nullptr	图片源为数组信息
nullptr	图片源非数组信息或未设置

GetSrcType

uint8_t GetSrcType() const

功能说明

• 核心用途：获取图片源类型
• 该函数为 const 成员函数，不修改对象状态
• 用于判断当前图片是通过文件路径还是数组信息加载

返回值

• 返回类型：uint8_t

返回图片源类型

返回值	触发场景
IMG_SRC_VARIABLE	图片源为数组信息
IMG_SRC_FILE	图片源为文件路径

SetResizeMode

void SetResizeMode(ImageResizeMode mode)

功能说明

• 核心用途：设置图片缩放模式
• 自适应启用时仅保存模式值，不立即更新变换映射
• 自适应禁用时，设置新模式会触发重新测量并更新变换映射

入参

名称	参数类型	详细说明	约束取值范围
mode	ImageResizeMode	图片缩放模式	ImageResizeMode 枚举值

SetWidth

virtual void SetWidth(int16_t width) override

功能说明

• 核心用途：设置图片视图宽度
• 当宽度值发生变化时，会更新变换映射
• 该函数重写基类 UIView 的 SetWidth 方法

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	目标宽度值	>= 0

SetHeight

virtual void SetHeight(int16_t height) override

功能说明

• 核心用途：设置图片视图高度
• 当高度值发生变化时，会更新变换映射
• 该函数重写基类 UIView 的 SetHeight 方法

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	目标高度值	>= 0

GetResizeMode

ImageResizeMode GetResizeMode() const

功能说明

• 核心用途：获取图片缩放模式
• 该函数为 const 成员函数，不修改对象状态
• 默认值为 ImageResizeMode::NONE

返回值

• 返回类型：ImageResizeMode

返回图片缩放模式

返回值	触发场景
NONE(0)	无缩放
COVER(1)	覆盖模式
CONTAIN(2)	包含模式
FILL(3)	填充模式
CENTER(4)	居中模式
SCALE_DOWN(5)	缩小模式

GetGifImageAnimator

Animator* GetGifImageAnimator() const

功能说明

• 核心用途：获取 GIF 图片动画控制器
• 该函数为 const 成员函数，不修改对象状态
• 仅在启用 GIF 支持（ENABLE_GIF == 1）时可用

Kconfig 配置

配置项	说明	默认值
ENABLE_GIF	是否启用GIF动画支持	n

返回值

• 返回类型：Animator*

返回GIF动画控制器指针

返回值	触发场景
非 nullptr	GIF动画控制器已创建
nullptr	未创建GIF动画控制器或未启用GIF支持

DumpImgInfo

void DumpImgInfo() override

功能说明

• 核心用途：打印图片信息到标准输出
• 仅当图片源类型为 IMG_SRC_VARIABLE 时输出信息
• 输出内容包括视图指针和视图类型

GetGuiInfo

virtual std::string GetGuiInfo() const override

功能说明

• 核心用途：获取图片视图的 GUI 调试信息字符串
• 该函数为 const 成员函数，不修改对象状态
• 仅当图片源类型为 IMG_SRC_VARIABLE 时返回有效信息字符串
• 该函数为 virtual 成员函数，允许子类重写

返回值

• 返回类型：std::string

返回GUI调试信息字符串

返回值	触发场景
非空字符串	图片源为数组信息，包含尺寸、格式、数据指针等信息
空字符串	图片源非数组信息或内存分配失败

SetColor

void SetColor(ColorType color)

功能说明

• 核心用途：设置图片颜色，仅对 A8 格式（8位Alpha通道）的图片有效
• 设置颜色后会触发视图刷新
• 非 A8 格式图片调用此接口无效

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	颜色值	有效的 ColorType 值

Enumerations

UIImageView::ImageResizeMode

enum ImageResizeMode : uint8_t {
    NONE = 0,
    COVER = 1,
    CONTAIN = 2,
    FILL = 3,
    CENTER = 4,
    SCALE_DOWN = 5,
};

枚举成员	取值	描述
NONE	0	无缩放，按原始尺寸显示
COVER	1	覆盖模式，缩放图片以完全覆盖视图区域，可能裁剪图片
CONTAIN	2	包含模式，缩放图片以完整显示在视图区域内，可能留有空白
FILL	3	填充模式，独立缩放宽高以填满视图区域，图片可能变形
CENTER	4	居中模式，不缩放，图片居中显示
SCALE_DOWN	5	缩小模式，仅在图片大于视图时缩小至包含模式尺寸，否则原始尺寸

BlurLevel

enum BlurLevel : uint8_t {
    INVALID,
    LEVEL0,
    LEVEL1,
    LEVEL2,
};

枚举成员	取值	描述
INVALID	0	无效值
LEVEL0	1	无模糊
LEVEL1	2	模糊一行
LEVEL2	3	模糊两行

TransformAlgorithm

enum TransformAlgorithm : uint8_t {
    NEAREST_NEIGHBOR,
    BILINEAR,
};

枚举成员	取值	描述
NEAREST_NEIGHBOR	0	最近邻插值算法，速度快但质量较低
BILINEAR	1	双线性插值算法，质量较高但计算量较大