ui_sweep_clock

ui_sweep_clock 模块提供扫秒时钟组件，支持扫秒动画效果的时钟显示。

Class Summary

OHOS::UISweepClock

提供扫秒时钟相关的功能，支持以图像或线条方式绘制时针、分针、秒针，并支持毫秒级精度的时间设置与显示。

• 构造：UISweepClock()

• 成员函数：

  接口名称	功能简述
  SetInitTime24Hour	以24小时制设置初始时间
  SetInitTime12Hour	以12小时制设置初始时间
  UpdateClock	更新扫秒时钟的时间显示
  SetTime24Hour	以24小时制设置时间
  SetSweepTime24Hour	以24小时制设置含毫秒的扫秒时间
  SetSweepTime12Hour	以12小时制设置含毫秒的扫秒时间
  GetViewType	获取视图类型
  SetHandImage	设置以图像方式绘制时钟指针
  SetHandCircleImage	设置时钟指针圆心的图像
  SetHandLine	设置以线条方式绘制时钟指针
  GetHandRotateCenter	获取指定时钟指针的旋转中心
  GetHandPosition	获取指定时钟指针的位置
  GetHandInitAngle	获取指定时钟指针的初始旋转角度
  GetHandCurrentAngle	获取指定时钟指针的当前旋转角度
  OnDraw	绘制扫秒时钟
  OnPostDraw	执行绘制后的操作
  SetWorkMode	设置扫秒时钟的工作模式
  DumpImgInfo	打印时钟指针图像信息
  ReMeasure	重新测量时钟指针的绘制变换

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

• 声明头文件：middleware/services/gui/uikit/proprietary/include/components/ui_sweep_clock.h
• 公有运算符：无
• 继承关系：UIAbstractClock
• 嵌套类型：HandType、DrawType、HandCircle、Hand
• 模板形参：无

Functions

OHOS::UISweepClock

SetInitTime24Hour

void SetInitTime24Hour(uint8_t hour, uint8_t minute, uint8_t second)

功能说明

• 核心用途：以24小时制设置扫秒时钟的初始时间
• 设计目的：在首次初始化时钟时设定时、分、秒，并计算各指针的初始旋转角度
• 使用场景：时钟组件首次创建或重置时调用，设置起始时间后触发初始化绘制

入参

名称	参数类型	详细说明	约束取值范围
hour	uint8_t	小时值	[0, 23]，取模后有效
minute	uint8_t	分钟值	[0, 59]，取模后有效
second	uint8_t	秒值	[0, 59]，取模后有效

SetInitTime12Hour

void SetInitTime12Hour(uint8_t hour, uint8_t minute, uint8_t second, bool am)

功能说明

• 核心用途：以12小时制设置扫秒时钟的初始时间
• 设计目的：支持12小时格式的时间初始化，内部转换为24小时制处理
• 使用场景：需要以12小时制显示时钟时调用

入参

名称	参数类型	详细说明	约束取值范围
hour	uint8_t	小时值	[0, 11]，取模后有效
minute	uint8_t	分钟值	[0, 59]，取模后有效
second	uint8_t	秒值	[0, 59]，取模后有效
am	bool	是否为上午	true表示上午，false表示下午

UpdateClock

void UpdateClock(bool clockInit) override

功能说明

• 核心用途：更新扫秒时钟的时间显示，根据当前时间计算各指针旋转角度
• 设计目的：根据时、分、秒及毫秒值计算时针、分针、秒针的目标旋转角度，并更新重绘区域
• 使用场景：时间发生变化时调用，更新时钟界面显示

入参

名称	参数类型	详细说明	约束取值范围
clockInit	bool	是否为首次初始化	true表示首次初始化，false表示非首次

SetTime24Hour

void SetTime24Hour(uint8_t hour, uint8_t minute, uint8_t second) override

功能说明

• 核心用途：以24小时制设置当前时间并更新时钟显示
• 设计目的：设置时、分、秒后自动计算毫秒值并触发时钟更新
• 使用场景：运行过程中动态修改时钟时间

入参

名称	参数类型	详细说明	约束取值范围
hour	uint8_t	小时值	[0, 23]，取模后有效
minute	uint8_t	分钟值	[0, 59]，取模后有效
second	uint8_t	秒值	[0, 59]，取模后有效

SetSweepTime24Hour

void SetSweepTime24Hour(uint8_t hour, uint8_t minute, uint16_t millisecond)

功能说明

• 核心用途：以24小时制设置含毫秒精度的扫秒时间
• 设计目的：支持毫秒级时间精度，实现秒针连续扫动效果
• 使用场景：需要秒针连续平滑移动而非逐秒跳动的场景

入参

名称	参数类型	详细说明	约束取值范围
hour	uint8_t	小时值	[0, 23]，取模后有效
minute	uint8_t	分钟值	[0, 59]，取模后有效
millisecond	uint16_t	毫秒值	[0, 59999]，取模后有效

SetSweepTime12Hour

void SetSweepTime12Hour(uint8_t hour, uint8_t minute, uint16_t millisecond, bool am)

功能说明

• 核心用途：以12小时制设置含毫秒精度的扫秒时间
• 设计目的：支持12小时格式的毫秒级时间设置，内部转换为24小时制处理
• 使用场景：需要以12小时制配合秒针连续扫动效果的时钟场景

入参

名称	参数类型	详细说明	约束取值范围
hour	uint8_t	小时值	[0, 11]，取模后有效
minute	uint8_t	分钟值	[0, 59]，取模后有效
millisecond	uint16_t	毫秒值	[0, 59999]，取模后有效
am	bool	是否为上午	true表示上午，false表示下午

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 设计目的：区分扫秒时钟与其他UI组件类型，用于视图类型判断
• 使用场景：在视图管理或类型检查流程中识别扫秒时钟组件

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_SWEEP_CLOCK	当前视图为扫秒时钟类型

SetHandImage

void SetHandImage(HandType type, const Image& img, Point position, Point center)

功能说明

• 核心用途：设置以图像方式绘制指定类型的时钟指针
• 设计目的：为时针、分针或秒针配置图像资源、起始位置和旋转中心
• 使用场景：使用图片资源绘制时钟指针时调用，支持文件路径和内存图像两种来源

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND
img	const Image&	指针图像，入参只读引用，不修改所指对象	支持IMG_SRC_FILE和IMG_SRC_VARIABLE两种来源
position	Point	图像起始位置	像素坐标
center	Point	指针旋转中心	像素坐标

Kconfig 配置

配置项	说明	默认值
ENABLE_SWEEP_CLOCK	启用扫秒时钟组件	y

SetHandCircleImage

void SetHandCircleImage(HandType type, const Image& img, Point position)

功能说明

• 核心用途：设置指定类型时钟指针圆心的图像
• 设计目的：为指针旋转中心位置配置装饰图像，增强时钟视觉效果
• 使用场景：需要在时钟指针中心绘制圆形图像装饰时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND
img	const Image&	圆心图像，入参只读引用，不修改所指对象	支持IMG_SRC_FILE和IMG_SRC_VARIABLE两种来源
position	Point	图像起始位置	像素坐标

Kconfig 配置

配置项	说明	默认值
ENABLE_SWEEP_CLOCK	启用扫秒时钟组件	y

SetHandLine

void SetHandLine(HandType type, Point position, Point center, ColorType color, uint16_t width, uint16_t height, OpacityType opacity)

功能说明

• 核心用途：设置以线条方式绘制指定类型的时钟指针
• 设计目的：为时针、分针或秒针配置线条的几何属性、颜色和透明度
• 使用场景：不使用图像而以线条绘制时钟指针时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND
position	Point	线条靠近旋转中心端点的位置	像素坐标
center	Point	指针旋转中心	像素坐标
color	ColorType	线条颜色	ColorType取值范围
width	uint16_t	线条宽度（12点方向时的宽度）	正整数
height	uint16_t	线条高度（12点方向时的高度）	正整数
opacity	OpacityType	线条透明度	OpacityType取值范围

Kconfig 配置

配置项	说明	默认值
ENABLE_SWEEP_CLOCK	启用扫秒时钟组件	y

GetHandRotateCenter

Point GetHandRotateCenter(HandType type) const

功能说明

• 核心用途：获取指定类型时钟指针的旋转中心坐标
• 设计目的：查询已配置的指针旋转中心，用于外部计算或布局调整
• 使用场景：需要获知指针旋转中心位置进行坐标运算时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

• 返回类型：Point

返回指针旋转中心坐标

返回值	触发场景
Point{center_.x, center_.y}	返回指定类型指针的旋转中心坐标

GetHandPosition

Point GetHandPosition(HandType type) const

功能说明

• 核心用途：获取指定类型时钟指针的位置坐标
• 设计目的：查询已配置的指针起始位置，用于外部计算或布局调整
• 使用场景：需要获知指针位置进行坐标运算时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

• 返回类型：Point

返回指定类型时钟指针的位置坐标

返回值	触发场景
Point{position_.x, position_.y}	返回指定类型指针的位置坐标

GetHandInitAngle

float GetHandInitAngle(HandType type) const

功能说明

• 核心用途：获取指定类型时钟指针的初始旋转角度
• 设计目的：查询指针初始化时设定的旋转角度，默认为0表示垂直向上
• 使用场景：需要获知指针初始角度进行角度差计算时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

• 返回类型：float

返回指定类型时钟指针的初始旋转角度

返回值	触发场景
initAngle_	返回指定类型指针的初始旋转角度，0表示垂直向上

GetHandCurrentAngle

float GetHandCurrentAngle(HandType type) const

功能说明

• 核心用途：获取指定类型时钟指针的当前旋转角度
• 设计目的：查询指针当前指向的角度，用于外部状态判断或动画同步
• 使用场景：需要获知指针当前角度进行状态判断时调用

入参

名称	参数类型	详细说明	约束取值范围
type	HandType	时钟指针类型	HandType：HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

• 返回类型：float

返回指定类型时钟指针的当前旋转角度

返回值	触发场景
nextAngle_	返回指定类型指针的当前旋转角度

OnDraw

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

功能说明

• 核心用途：绘制扫秒时钟的背景矩形区域
• 设计目的：在绘制阶段填充时钟背景，指针的绘制在OnPostDraw中完成
• 使用场景：UI框架绘制流程中自动调用，不应由用户直接调用

入参

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

OnPostDraw

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

功能说明

• 核心用途：在背景绘制完成后绘制时钟指针（时针、分针、秒针）及其圆心图像
• 设计目的：确保指针绘制在所有子视图之上，NORMAL模式下绘制秒针，ALWAYS_ON模式下不绘制秒针
• 使用场景：UI框架绘制流程中自动调用，不应由用户直接调用

入参

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

SetWorkMode

void SetWorkMode(WorkMode newMode) override

功能说明

• 核心用途：设置扫秒时钟的工作模式
• 设计目的：切换NORMAL和ALWAYS_ON模式，ALWAYS_ON模式下不绘制秒针及子控件以节省功耗
• 使用场景：需要在常显模式与正常模式之间切换时调用

入参

名称	参数类型	详细说明	约束取值范围
newMode	WorkMode	工作模式	WorkMode::NORMAL / WorkMode::ALWAYS_ON

DumpImgInfo

void DumpImgInfo() override

功能说明

• 核心用途：打印扫秒时钟各指针及圆心的图像信息到标准输出
• 设计目的：用于调试和诊断，输出视图类型及各指针图像的源类型和图像信息
• 使用场景：调试阶段检查时钟指针图像配置是否正确

ReMeasure

void ReMeasure() override

功能说明

• 核心用途：重新测量并更新所有时钟指针的绘制变换矩阵
• 设计目的：在视图变换（如父视图变换）发生变化时，重新计算时针、分针、秒针的绘制变换
• 使用场景：视图布局或变换发生改变后需要重新计算指针绘制参数时调用

Enumerations

HandType

enum class HandType {
    HOUR_HAND,
    MINUTE_HAND,
    SECOND_HAND,
};

枚举成员	取值	描述
HOUR_HAND	0	时针
MINUTE_HAND	1	分针
SECOND_HAND	2	秒针

DrawType

enum class DrawType {
    DRAW_LINE,
    DRAW_IMAGE
};

枚举成员	取值	描述
DRAW_LINE	0	以线条方式绘制时钟指针
DRAW_IMAGE	1	以图像方式绘制时钟指针

Structures

HandCircle

class HandCircle : public HeapBase {
public:
    HandCircle() : position_{0, 0}, circleImgInfo_{{0, 0, 0, 0, 0}} {}
    Point position_;
    ImageInfo circleImgInfo_;
    Image circleImg_;
};

成员说明

成员名称	数据类型	描述
position_	Point	指针圆心的位置坐标
circleImgInfo_	ImageInfo	指针圆心图像的图像信息
circleImg_	Image	指针圆心的图像对象

Hand

class Hand : public HeapBase {
public:
    Hand()
        : center_{0, 0},
          initAngle_(0),
          preAngle_(0),
          nextAngle_(0),
          position_{0, 0},
          imageInfo_{{0, 0, 0, 0, 0}},
          color_{{0, 0, 0}},
          width_(0),
          height_(0),
          opacity_(0),
          drawtype_(DrawType::DRAW_IMAGE)
    {
    }
    virtual ~Hand() {}
    Point center_;
    float initAngle_;
    float preAngle_;
    float nextAngle_;
    Point position_;
    ImageInfo imageInfo_;
    TransformMap trans_;
    TransformMap drawTransformap_;
    Rect target_;
    ColorType color_;
    uint16_t width_;
    uint16_t height_;
    OpacityType opacity_;
    DrawType drawtype_;
    Image image_;
};

成员说明

成员名称	数据类型	描述
center_	Point	指针旋转中心
initAngle_	float	指针初始旋转角度，默认0表示垂直向上
preAngle_	float	指针上一次旋转角度
nextAngle_	float	指针下一次旋转角度
position_	Point	指针在时钟中的位置
imageInfo_	ImageInfo	指针图像信息
trans_	TransformMap	指针旋转和平移的变换信息
drawTransformap_	TransformMap	指针绘制用的变换信息
target_	Rect	旋转和平移后的新矩形区域
color_	ColorType	指针颜色（线条绘制模式）
width_	uint16_t	指针宽度
height_	uint16_t	指针高度
opacity_	OpacityType	指针透明度
drawtype_	DrawType	指针绘制类型
image_	Image	指针图像对象