函数名称	说明
OH_NativeXComponent_SetExpectedFrameRateRange(OH_NativeXComponent* component, OH_NativeXComponent_ExpectedRateRange* range)	设置期望的帧率范围。
OH_NativeXComponent_RegisterOnFrameCallback(OH_NativeXComponent* component, void (callback)(OH_NativeXComponent component, uint64_t timestamp, uint64_t targetTimestamp))	设置每帧回调函数，同时启动每帧回调。
OH_NativeXComponent_UnregisterOnFrameCallback(OH_NativeXComponent* component)	取消注册的每帧回调函数，同时停止调用回调函数。

详细的接口说明请参考OH_NativeXComponent Native XComponent。

开发步骤

本范例是通过Drawing在Native侧实现图形的绘制，并将其呈现在NativeWindow上，具体可参考使用Drawing实现图形绘制与显示。

添加开发依赖。

CMakeLists.txt中添加以下lib。

target_link_libraries(entry PUBLIC libace_napi.z.so libnative_drawing.so libnative_window.so libace_ndk.z.so)

导入依赖的相关头文件。

#include <ace/xcomponent/native_interface_xcomponent.h>
#include <arpa/nameser.h>
#include <bits/alltypes.h>
#include <native_window/external_window.h>
#include <native_drawing/drawing_bitmap.h>
#include <native_drawing/drawing_color.h>
#include <native_drawing/drawing_canvas.h>
#include <native_drawing/drawing_pen.h>
#include <native_drawing/drawing_brush.h>
#include <native_drawing/drawing_path.h>
#include <cstdint>
#include <map>
#include <sys/mman.h>
#include <string>
#include "napi/native_api.h"

#include <native_drawing/drawing_text_typography.h>

定义ArkTS接口文件XComponentContext.ts，用来对接Native层。

export default interface XComponentContext {
  register(): void;

  unregister(): void;
};

定义演示页面，包含两个XComponent组件。

import XComponentContext from '../interface/XComponentContext';
// ...

@Entry
@Component
struct Index {
  private xComponentContext1: XComponentContext | undefined = undefined;
  private xComponentContext2: XComponentContext | undefined = undefined;

  build() {
    Column() {
      Row() {
        // ...

        XComponent({
          id: 'xcomponentId_30',
          type: XComponentType.SURFACE,
          libraryname: 'entry'
        })
          .onLoad((xComponentContext) => {
            this.xComponentContext1 = xComponentContext as XComponentContext;
          }).width('640px')
          // ...
      }.height('40%')

      Row() {
        // ...

        XComponent({
          id: 'xcomponentId_120',
          type: XComponentType.SURFACE,
          libraryname: 'entry'
        })
          .onLoad((xComponentContext) => {
            this.xComponentContext2 = xComponentContext as XComponentContext;
          }).width('640px')
          // ...
      }.height('40%')

      // ...
    }
  }
}

Native层配置帧率和注册回调函数。

static void TestCallback(OH_NativeXComponent *component, uint64_t timestamp, uint64_t targetTimestamp)
{
    // ...
    
    int32_t xSize = OH_NativeXComponent_GetXComponentSize(component, nativeWindow, &width, &height);
    if ((xSize == OH_NATIVEXCOMPONENT_RESULT_SUCCESS) && (render != nullptr)) {
        render->Prepare();
        render->Create();
        if (id == "xcomponentId_30") {
            int offset = 16;
            render->ConstructPath(offset, offset, render->defaultOffsetY);
        }
        if (id == "xcomponentId_120") {
            int offset = 4;
            render->ConstructPath(offset, offset, render->defaultOffsetY);
        }
        // ...
    }
}

Callback回调函数运行于UI主线程，故涉及UI线程的耗时操作不应运行于回调函数中，以免影响性能。
实例在调用OH_NativeXComponent_RegisterOnFrameCallback后，在不需要进行帧率控制时，应进行OH_NativeXComponent_UnregisterOnFrameCallback操作，避免内存泄漏及性能功耗影响。
API version 18之前，应用调用OH_NativeXComponent_RegisterOnFrameCallback接口设置回调函数，如果没有取消注册，在XComponent实例存在期间，能一直收到期望回调。
从API version 18开始，应用调用OH_NativeXComponent_RegisterOnFrameCallback接口设置回调函数，如果没有取消注册，只在XComponent上树期间，能收到期望回调。

void SampleXComponent::RegisterOnFrameCallback(OH_NativeXComponent *nativeXComponent)
{
    // ...
    OH_NativeXComponent_RegisterOnFrameCallback(nativeXComponent, TestCallback);
}

napi_value SampleXComponent::NapiRegister(napi_env env, napi_callback_info info)
{
    // ...
        render->RegisterOnFrameCallback(nativeXComponent);
        // ...
}

napi_value SampleXComponent::NapiUnregister(napi_env env, napi_callback_info info)
{
    // ...
        OH_NativeXComponent_UnregisterOnFrameCallback(nativeXComponent);
        // ...
}

TS层注册和取消注册每帧回调。

Row() {
  Button('Start')
    .id('Start')
    .fontSize(14)
    .fontWeight(500)
    .margin({ bottom: 20, right: 6, left: 6 })
    .onClick(() => {
      if (this.xComponentContext1) {
        this.xComponentContext1.register();
      }
      if (this.xComponentContext2) {
        this.xComponentContext2.register();
      }
    })
    .width('30%')
    .height(40)
    .shadow(ShadowStyle.OUTER_DEFAULT_LG)

  Button('Stop')
    .id('Stop')
    .fontSize(14)
    .fontWeight(500)
    .margin({ bottom: 20, left: 6 })
    .onClick(() => {
      if (this.xComponentContext1) {
        this.xComponentContext1.unregister();
      }
      if (this.xComponentContext2) {
        this.xComponentContext2.unregister();
      }
    })
    .width('30%')
    .height(40)
    .shadow(ShadowStyle.OUTER_DEFAULT_LG)

  // ...
}

目录

请求自绘制内容绘制帧率

接口说明

开发步骤