diff --git a/arkui/ace_engine/native/libace.ndk.json b/arkui/ace_engine/native/libace.ndk.json index 34e04ae3cb1d9c4fbc8e8397f525f7cdc1cc4795..c4c65e5d1d4131bff6f43a569eeca0f7dba2d822 100644 --- a/arkui/ace_engine/native/libace.ndk.json +++ b/arkui/ace_engine/native/libace.ndk.json @@ -2694,6 +2694,30 @@ "first_introduced": "15", "name": "OH_ArkUI_CancelDataLoading" }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_Create" + }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_Dispose" + }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_SetRatios" + }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_SetExpectedUpdateInterval" + }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_GetRatios" + }, + { + "first_introduced": "17", + "name": "OH_ArkUI_VisibleAreaEventOptions_GetExpectedUpdateInterval" + }, { "first_introduced": "15", "name": "OH_ArkUI_DisableDropDataPrefetchOnNode" diff --git a/arkui/ace_engine/native/native_node.h b/arkui/ace_engine/native/native_node.h index fe0c8624094da074cc710119d31458cd4736f42b..78bbdb47400f7684fda8d0e9e454f2ec256e107f 100644 --- a/arkui/ace_engine/native/native_node.h +++ b/arkui/ace_engine/native/native_node.h @@ -1865,6 +1865,28 @@ typedef enum { */ NODE_BACKDROP_BLUR = 99, + /** + * @brief Sets the parameters for visible area change events. + * + * @note The visible area change callback is not a real-time callback. The actual callback interval may differ from + * the expected interval due to system load and other factors. + * The interval between two visible area change callbacks will not be less than the expected update interval. If the + * provided expected interval is too short, the actual callback interval will be determined by the system load. + * By default, the interval threshold of the visible area change callback includes 0. This means that, + * if the provided threshold is [0.5], the effective threshold will be [0.0, 0.5]. + * + * Format of the {@link ArkUI_AttributeItem} parameter for setting the attribute:\n + * .object: parameters for visible area change events. + * The parameter type is {@link ArkUI_VisibleAreaEventOptions}. \n + * \n + * Format of the return value {@link ArkUI_AttributeItem}:\n + * .object: parameters for visible area change events. + * The parameter type is {@link ArkUI_VisibleAreaEventOptions}. \n + * + * @since 17 + */ + NODE_VISIBLE_AREA_APPROXIMATE_CHANGE_RATIO = 102, + /** * @brief Defines the text content attribute, which can be set, reset, and obtained as required through APIs. * @@ -6161,6 +6183,25 @@ typedef enum { */ NODE_DISPATCH_KEY_EVENT = 24, + /** + * @brief Sets the callback for the NODE_EVENT_ON_VISIBLE_AREA_CHANGE event, which limits the callback interval. + * + * The callback is triggered when the ratio of the component's visible area to its total area is greater than or + * less than the threshold. Before registering the callback, you must configure the threshold and update interval + * using NODE_VISIBLE_AREA_APPROXIMATE_CHANGE_RATIO. \n + * When the event callback occurs, the union type in the {@link ArkUI_NodeEvent} object is + * {@link ArkUI_NodeComponentEvent}. \n + * {@link ArkUI_NodeComponentEvent} contains two parameters:\n + * ArkUI_NodeComponentEvent.data[0].i32: how the ratio of the component's visible area to its total area + * changes compared to the previous one. The value 1 indicates an increase, and 0 indicates + * a decrease. \n + * ArkUI_NodeComponentEvent.data[1].f32: ratio of the component's visible area to its total area + * when this callback is invoked. \n + * + * @since 17 + */ + NODE_VISIBLE_AREA_APPROXIMATE_CHANGE_EVENT = 28, + /** * @brief Defines the hover event. * diff --git a/arkui/ace_engine/native/native_type.h b/arkui/ace_engine/native/native_type.h index 71b534c2f05f2c8aa7a9fa20e992026490f42827..4ba098c11e9607932a2a3507c9b7603df2df26d8 100644 --- a/arkui/ace_engine/native/native_type.h +++ b/arkui/ace_engine/native/native_type.h @@ -4262,6 +4262,89 @@ void OH_ArkUI_DestroySnapshotOptions(ArkUI_SnapshotOptions* snapshotOptions); */ int32_t OH_ArkUI_SnapshotOptions_SetScale(ArkUI_SnapshotOptions* snapshotOptions, float scale); +/** + * @brief Defines the parameters for visible area change events. + * + * @since 17 + */ +typedef struct ArkUI_VisibleAreaEventOptions ArkUI_VisibleAreaEventOptions; + +/** + * @brief Creates an instance of visible area change event parameters + * + * @return Returns the created instance of visible area change event parameters. + * @since 17 + */ +ArkUI_VisibleAreaEventOptions *OH_ArkUI_VisibleAreaEventOptions_Create(); + +/** + * @brief Disposes of an instance of visible area change event parameters. + * + * @param option Instance to be destroyed. + * @since 17 + */ +void OH_ArkUI_VisibleAreaEventOptions_Dispose(ArkUI_VisibleAreaEventOptions *option); + +/** + * @brief Sets the threshold ratios for visible area changes. + * + * @param option Instance of visible area change event parameters. + * @param value Array of threshold ratios. Each element represents the ratio of + * the visible area of a component to its total area. The visible area is + * calculated within the parent component's bounds; any area outside the parent + * component is not considered. Each value must be within the [0.0, 1.0] range. + * Values outside this range will be handled as 0.0 or 1.0. + * @param size Size of the threshold array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is + * successful. Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter + * error occurs. If an error code is returned, it may be due to a failure in + * parameter validation; the parameter must not be null. + * @since 17 + */ +int32_t OH_ArkUI_VisibleAreaEventOptions_SetRatios(ArkUI_VisibleAreaEventOptions *option, float *value, int32_t size); + +/** + * @brief Sets the expected update interval for visible area changes. + * + * @param option Instance of visible area change event parameters. + * @param value Expected update interval, in ms. Default value: 1000. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is + * successful. Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter + * error occurs. If an error code is returned, it may be due to a failure in + * parameter validation; the parameter must not be null. + * @since 17 + */ +int32_t OH_ArkUI_VisibleAreaEventOptions_SetExpectedUpdateInterval( + ArkUI_VisibleAreaEventOptions *option, int32_t value); + +/** + * @brief Obtains the threshold ratios for visible area changes. + * + * @param option Instance of visible area change event parameters. + * @param value Array of threshold ratios. + * @param size Size of the threshold array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is + * successful. Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter + * error occurs. Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the + * provided buffer size is insufficient. If an error code is returned, it may be + * due to a failure in parameter validation; the parameter must not be null. + * @since 17 + */ +int32_t OH_ArkUI_VisibleAreaEventOptions_GetRatios(ArkUI_VisibleAreaEventOptions *option, float *value, int32_t *size); + +/** + * @brief Obtains the expected update interval for visible area changes. + * + * @param option Instance of visible area change event parameters. + * @return Returns the expected update interval, in ms. Default value: + * 1000. + * @since 17 + */ +int32_t OH_ArkUI_VisibleAreaEventOptions_GetExpectedUpdateInterval(ArkUI_VisibleAreaEventOptions *option); + /** * @brief Create a cross-language option instance. *