ui_sphere_view
ui_sphere_view 模块提供球体视图组件，支持3D球体的渲染与旋转交互。
Class Summary
OHOS::UISphereView
球体视图控件，以球面布局方式展示子控件并支持拖拽旋转交互。
- 构造：
UISphereView(uint8_t numberOfRow) -
成员函数：
接口名称 功能简述 UISphereView 构造球体视图并指定显示行数 GetViewType 获取视图类型标识 Add 添加子视图到球体视图 Insert 在指定子视图之后插入新的子视图 Remove 移除指定的子视图 SetNumberOfRow 设置球体视图显示的行数 GetNumberOfRow 获取球体视图当前显示的行数 SetChildStateListener 设置子控件角度状态变化监听器 UpdateItemAngle 更新当前球体旋转角度 SetHeight 设置视图高度 SetWidth 设置视图宽度 SetSensitivityFactor 设置拖拽灵敏度因子 GetSensitivityFactor 获取拖拽灵敏度因子 SetSphereCameraPosition 设置球体相机位置 SetSphereCameraDistance 设置球体相机距离 OnRotateStartEvent 旋转输入开始事件处理 OnRotateEvent 旋转输入事件处理 OnRotateEndEvent 旋转输入结束事件处理 OnDragStartEvent 拖拽开始事件处理 OnDragEvent 拖拽事件处理 OnDragEndEvent 拖拽结束事件处理 -
使用包含头文件：
#include "components/ui_sphere_view.h" - 声明头文件：
middleware/services/gui/uikit/proprietary/include/components/ui_sphere_view.h - 公有运算符：无
- 继承关系：UIScrollView
- 嵌套类型：ChildStateListener
- 模板形参：无
Functions
OHOS::UISphereView
UISphereView
UISphereView(uint8_t numberOfRow)
功能说明
- 构造 UISphereView 对象，并指定球体视图显示的行数
- 行数决定了子控件在球面上的纵向分布层数
- 对象构造后即可添加子控件并进行球面交互
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| numberOfRow | uint8_t | 球体视图显示的行数 | 1 ~ 255 |
GetViewType
UIViewType GetViewType() const override
功能说明
- 获取当前视图的类型标识
- 返回固定值 UI_SPHERE_VIEW，用于区分球体视图与其他视图类型
- 该方法为 const 方法，不修改对象状态
返回值
- 返回类型：
UIViewType
返回视图类型标识
| 返回值 | 触发场景 |
|---|---|
| UI_SPHERE_VIEW(63) | 当前对象为球体视图 |
Add
void Add(UIView* view) override
功能说明
- 向球体视图中添加子视图，子视图将以球面布局方式排列
- 添加的子视图会被自动计算球面位置与变换
- 重写基类 UIScrollView 的 Add 方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| view | UIView* | 入参指针，指向待添加的子视图对象 | 非 nullptr |
Insert
void Insert(UIView* prevView, UIView* insertView) override
功能说明
- 在指定子视图之后插入新的子视图
- 插入后球面布局将自动重新计算
- 重写基类 UIScrollView 的 Insert 方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| prevView | UIView* | 入参指针，指向当前已存在的子视图 | 非 nullptr |
| insertView | UIView* | 入参指针，指向待插入的新子视图 | 非 nullptr |
Remove
void Remove(UIView* view) override
功能说明
- 从球体视图中移除指定的子视图
- 移除后球面布局将自动重新计算
- 重写基类 UIScrollView 的 Remove 方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| view | UIView* | 入参指针，指向待移除的子视图 | 非 nullptr |
SetNumberOfRow
void SetNumberOfRow(uint8_t numberOfRow)
功能说明
- 设置球体视图显示的行数
- 行数变更后球面布局将自动重新计算子控件的分布位置
- 该方法触发重新测量操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| numberOfRow | uint8_t | 球体视图显示的行数 | 1 ~ 255 |
GetNumberOfRow
uint8_t GetNumberOfRow()
功能说明
- 获取球体视图当前显示的行数
- 默认值为 1
- 该方法不修改对象状态
返回值
- 返回类型：
uint8_t
返回当前显示行数
| 返回值 | 触发场景 |
|---|---|
| 1 | 默认构造时行数 |
| N | 调用 SetNumberOfRow 设置后的行数 |
SetChildStateListener
void SetChildStateListener(ChildStateListener* listener)
功能说明
- 设置子控件角度状态变化监听器，当子控件在球面上的旋转角度发生变化时触发回调
- 监听器通过 ChildStateListener 类的 StateChange 回调方法通知角度变化
- 设置为 nullptr 可取消监听
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| listener | ChildStateListener* | 入参指针，指向子控件状态监听器对象 | 可为 nullptr |
UpdateItemAngle
void UpdateItemAngle(float angle)
功能说明
- 更新当前球体的旋转角度
- 通过指定角度值移动球面上子控件的位置
- 该方法触发球面变换与重绘操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| angle | float | 球体移动的角度值，单位为度 | 浮点数 |
SetHeight
void SetHeight(int16_t height) override
功能说明
- 设置球体视图的高度
- 高度变更后球面布局将自动重新计算
- 重写基类 UIScrollView 的 SetHeight 方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| height | int16_t | 视图高度值，单位为像素 | 正整数 |
SetWidth
void SetWidth(int16_t width) override
功能说明
- 设置球体视图的宽度
- 宽度变更后球面布局将自动重新计算
- 重写基类 UIScrollView 的 SetWidth 方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| width | int16_t | 视图宽度值，单位为像素 | 正整数 |
SetSensitivityFactor
void SetSensitivityFactor(float sensitivity)
功能说明
- 设置拖拽操作转换为旋转角度的灵敏度因子
- 拖拽距离转换为角度时会乘以该灵敏度因子
- 默认值为 1.0
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| sensitivity | float | 灵敏度因子，拖拽距离转换为角度时的乘数 | 正浮点数 |
GetSensitivityFactor
float GetSensitivityFactor()
功能说明
- 获取当前拖拽操作的灵敏度因子
- 默认值为 1.0
- 该方法不修改对象状态
返回值
- 返回类型：
float
返回灵敏度因子
| 返回值 | 触发场景 |
|---|---|
| 1.0 | 默认灵敏度因子 |
| N | 调用 SetSensitivityFactor 设置后的值 |
SetSphereCameraPosition
void SetSphereCameraPosition(const Vector2<float>& position)
功能说明
- 设置球体相机的位置坐标
- 相机位置影响球面透视变换的计算结果
- 该方法触发相机矩阵重新计算
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| position | const Vector2 |
入参只读引用，相机位置的二维坐标 | 浮点数对 |
SetSphereCameraDistance
void SetSphereCameraDistance(int16_t distance)
功能说明
- 设置球体相机与球面之间的距离
- 相机距离影响球面透视效果的近大远小程度
- 默认值为 -2000
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| distance | int16_t | 相机距离值 | 负整数；默认 -2000 |
OnRotateStartEvent
bool OnRotateStartEvent(const RotateEvent& event) override
功能说明
- 处理旋转输入开始事件
- 重写基类 UIView 的旋转事件处理方法
- 该方法仅在启用 ENABLE_ROTATE_INPUT 宏时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 旋转开始事件已被消费 |
| false | 旋转开始事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能使能宏，控制旋转事件相关接口的可用性 | n |
OnRotateEvent
bool OnRotateEvent(const RotateEvent& event) override
功能说明
- 处理旋转输入持续事件
- 根据旋转角度更新球面上子控件的位置
- 重写基类 UIView 的旋转事件处理方法
- 该方法仅在启用 ENABLE_ROTATE_INPUT 宏时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 旋转事件已被消费 |
| false | 旋转事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能使能宏，控制旋转事件相关接口的可用性 | n |
OnRotateEndEvent
bool OnRotateEndEvent(const RotateEvent& event) override
功能说明
- 处理旋转输入结束事件
- 重写基类 UIView 的旋转事件处理方法
- 该方法仅在启用 ENABLE_ROTATE_INPUT 宏时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 旋转结束事件已被消费 |
| false | 旋转结束事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能使能宏，控制旋转事件相关接口的可用性 | n |
OnDragStartEvent
bool OnDragStartEvent(const DragEvent& event) override
功能说明
- 处理拖拽开始事件
- 记录拖拽起始状态，为后续拖拽移动计算提供基准
- 重写基类 UIScrollView 的拖拽事件处理方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 拖拽开始事件已被消费 |
| false | 拖拽开始事件未被消费 |
OnDragEvent
bool OnDragEvent(const DragEvent& event) override
功能说明
- 处理拖拽持续移动事件
- 将拖拽距离转换为旋转角度并更新球面上子控件的位置
- 重写基类 UIScrollView 的拖拽事件处理方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 拖拽事件已被消费 |
| false | 拖拽事件未被消费 |
OnDragEndEvent
bool OnDragEndEvent(const DragEvent& event) override
功能说明
- 处理拖拽结束事件
- 根据拖拽速度启动惯性滚动动画
- 重写基类 UIScrollView 的拖拽事件处理方法
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件对象 | - |
返回值
- 返回类型：
bool
返回事件是否已被消费
| 返回值 | 触发场景 |
|---|---|
| true | 拖拽结束事件已被消费 |
| false | 拖拽结束事件未被消费 |
Enumerations
UIViewType
enum UIViewType {
UI_ROOT_VIEW = 0,
UI_VIEW_GROUP = 1,
UI_LABEL = 2,
UI_ARC_LABEL = 3,
UI_LABEL_BUTTON = 4,
UI_CHECK_BOX = 5,
UI_TOGGLE_BUTTON = 6,
UI_RADIO_BUTTON = 7,
UI_IMAGE_VIEW = 8,
UI_BOX_PROGRESS = 9,
UI_SLIDER = 10,
UI_CIRCLE_PROGRESS = 11,
UI_SCROLL_VIEW = 12,
UI_LIST = 13,
UI_DIGITAL_CLOCK = 14,
UI_ANALOG_CLOCK = 15,
UI_PICKER = 16,
UI_SWIPE_VIEW = 17,
UI_TIME_PICKER = 18,
UI_ABSTRACT_CLOCK = 19,
UI_ABSTRACT_PROGRESS = 20,
UI_ABSTRACT_SCROLL = 21,
UI_AXIS = 22,
UI_BUTTON = 23,
UI_CANVAS = 24,
UI_CHART = 25,
UI_IMAGE_ANIMATOR_VIEW = 26,
UI_REPEAT_BUTTON = 27,
UI_TEXTURE_MAPPER = 28,
UI_DIALOG = 29,
UI_QRCODE = 30,
UI_LABEL_EXT = 31,
UI_LABEL_BUTTON_EXT = 32,
UI_CANVAS_EXT = 33,
UI_CHART_PILLAR = 34,
UI_CHART_POLYLINE = 35,
UI_X_AXIS = 36,
UI_Y_AXIS = 37,
UI_LITE_SURFACE_VIEW = 38,
LAYOUT = 39,
LIST_LAYOUT = 40,
FLEX_LAYOUT = 41,
GRID_LAYOUT = 42,
UI_EDIT_TEXT = 43,
UI_TEXT_PREVIEW_BOX = 44,
UI_KEYBOARD_BUTTON = 45,
UI_MENU_ITEM = 46,
UI_CARD_PAGE = 47,
UI_COVER_FLOW = 48,
UI_SLIP_FLOW = 49,
UI_FOLDABLE_VIEW = 50,
UI_CROSS_VIEW = 51,
UI_BARCODE = 52,
UI_MAP_VIEW = 53,
UI_KALEIDOSCOPE_VIEW = 54,
UI_ROLLER_VIEW = 55,
UI_HEXAGONS_LIST = 56,
UI_IMAGE_PICKER = 57,
UI_ICOSAHEDRON_VIEW = 58,
UI_TRANSFORM_GROUP = 59,
UI_TRANSFORM_LIST = 60,
UI_COVER_FLOW_2 = 61,
UI_WATERFALL_LIST = 62,
UI_SPHERE_VIEW = 63,
UI_PARTICLE_VIEW = 64,
UI_PLANET_LIST = 65,
UI_OPTION_BOX = 66,
UI_CARD_CONTAINER = 67,
UI_VIDEO = 68,
UI_LOTT_VIEW = 69,
UI_FLOAT_BOX_VIEW = 70,
UI_CHART_PILLAR_EXT = 71,
UI_CUSTOM_PLANET_LIST = 72,
UI_LIST_EXT = 73,
UI_LIST_NESTED = 74,
};
| 枚举成员 | 取值 | 描述 |
|---|---|---|
| UI_SPHERE_VIEW | 63 | 球体视图类型标识，GetViewType 返回此值 |
Structures
OHOS::UISphereView::ChildStateListener
class ChildStateListener : public HeapBase {
public:
virtual bool StateChange(UIView& view, float rowAngle, float colAngle)
{
return false;
}
virtual ~ChildStateListener() {}
};
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| StateChange | virtual bool(UIView&, float, float) | 子控件角度状态变化回调，参数为子控件引用、行方向旋转角度、列方向旋转角度；返回 false 表示未消费该事件 |