XComponent（繪制）

surface類型

XComponent設置為surface類型時通常用于EGL/OpenGLES和媒體數(shù)據(jù)寫入，并將其顯示在XComponent組件上。

設置為“surface“類型時XComponent組件可以和其他組件一起進行布局和渲染。

同時XComponent又擁有單獨的“NativeWindow“，可以為開發(fā)者在native側提供native window用來創(chuàng)建EGL/OpenGLES環(huán)境，進而使用標準的OpenGL ES開發(fā)。

除此之外，媒體相關應用（視頻、相機等）也可以將相關數(shù)據(jù)寫入XComponent所提供的NativeWindow，從而實現(xiàn)呈現(xiàn)相應畫面。

使用EGL/OpenGLES渲染

native側代碼開發(fā)要點

HarmonyOS的應用如果要通過js來橋接native，一般需要使用napi接口來處理js交互，XComponent同樣不例外，具體使用請參考Native API在應用工程中的使用指導。

Native側處理js邏輯的文件類型為so：

• 每個模塊對應一個so
• so的命名規(guī)則為 lib{模塊名}.so

Napi模塊注冊

static napi_value Init(napi_env env, napi_value exports)
{
    // 定義暴露在模塊上的方法
    napi_property_descriptor desc[] ={
        DECLARE_NAPI_FUNCTION("changeColor", PluginRender::NapiChangeColor),
    };
    // 通過此接口開發(fā)者可在exports上掛載native方法（即上面的PluginRender::NapiChangeColor），exports會通過js引擎綁定到js層的一個js對象
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    return exports;
}

static napi_module nativerenderModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init, // 指定加載對應模塊時的回調函數(shù)
    .nm_modname = "nativerender", // 指定模塊名稱，對于XComponent相關開發(fā)，這個名稱必須和ArkTS側XComponent中l(wèi)ibraryname的值保持一致
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterModule(void)
{
    // 注冊so模塊
    napi_module_register(&nativerenderModule);
}

解析XComponent組件的NativeXComponent實例

NativeXComponent為XComponent提供了在native層的實例，可作為js層和native層XComponent綁定的橋梁。XComponent所提供的的NDK接口都依賴于該實例。具體NDK接口可參考Native XComponent。

注冊XComponent事件回調

依賴解析XComponent組件的NativeXComponent實例拿到的NativeXComponent指針，通過OH_NativeXComponent_RegisterCallback接口進行回調注冊

創(chuàng)建EGL/OpenGLES環(huán)境

在注冊的OnSurfaceCreated回調中開發(fā)者能拿到native window的句柄（其本質就是XComponent所單獨擁有的NativeWindow），因此可以在這里創(chuàng)建應用自己的EGL/OpenGLES開發(fā)環(huán)境，由此開始具體渲染邏輯的開發(fā)。

EGLCore* eglCore_; // EGLCore為封裝了OpenGL相關接口的類
uint64_t width_;
uint64_t height_;
void OnSurfaceCreatedCB(OH_NativeXComponent* component, void* window)
{
    int32_t ret = OH_NativeXComponent_GetXComponentSize(component, window, &width_, &height_);
    if (ret === OH_NATIVEXCOMPONENT_RESULT_SUCCESS) {
        eglCore_->GLContextInit(window, width_, height_); // 初始化OpenGL環(huán)境
    }
}

ArkTS側語法介紹

開發(fā)者在ArkTS側使用如下代碼即可用XComponent組件進行利用EGL/OpenGLES渲染的開發(fā)。

XComponent({ id: 'xcomponentId1', type: 'surface', libraryname: 'nativerender' })
  .onLoad((context) => {})
  .onDestroy(() => {})

• id : 與XComponent組件為一一對應關系，不可重復。通常開發(fā)者可以在native側通過OH_NativeXComponent_GetXComponentId接口來獲取對應的id從而綁定對應的XComponent。
• libraryname：加載模塊的名稱，必須與在native側Napi模塊注冊時nm_modname的名字一致。
  說明

  應用加載模塊實現(xiàn)跨語言調用有兩種方式：

  1. 使用NAPI的import方式加載：

     import nativerender from "libnativerender.so"

  2. 使用XComponent組件加載，本質也是使用了NAPI機制來加載。

     該加載方式和import加載方式的區(qū)別在于，在加載動態(tài)庫是會將XComponent的NativeXComponent實例暴露到應用的native層中，從而讓開發(fā)者可以使用XComponent的NDK接口。
• onLoad事件
  • 觸發(fā)時刻：XComponent準備好surface后觸發(fā)。
  • 參數(shù)context：其上面掛載了暴露在模塊上的native方法，使用方法類似于利用 import context2 from "libnativerender.so" 直接加載模塊后獲得的context2實例。
  • 時序：onLoad事件的觸發(fā)和Surface相關，其和native側的OnSurfaceCreated的時序如下圖：

    

• onDestroy事件

  觸發(fā)時刻：XComponent組件被銷毀時觸發(fā)與一般ArkUI的組件銷毀時機一致，其和native側的OnSurfaceDestroyed的時序如下圖：

  

媒體數(shù)據(jù)寫入

XComponent所持有的NativeWindow符合“生產(chǎn)者-消費者”模型

HarmonyOS上Camera、AVPlayer等符合生產(chǎn)者設計的部件都可以將數(shù)據(jù)寫入XComponent持有的NativeWindow并通過XComponent顯示。

開發(fā)者可通過綁定XComponentController獲得對應XComponent的surfaceId（該id可以唯一確定一個surface），從而傳給相應的部件接口。

@State surfaceId:string = "";
mXComponentController: XComponentController = new XComponentController();
XComponent({ id: '', type: 'surface', controller: this.mXComponentController })
  .onLoad(() => {
    this.surfaceId = this.mXComponentController.getXComponentSurfaceId()
  })

具體部件接口可參考： VideoPlayer、 等。

component類型

XComponent設置為component類型時通常用于在XComponent內部執(zhí)行非UI邏輯以實現(xiàn)動態(tài)加載顯示內容的目的。

場景示例

@Builder
function addText(label: string): void {
  Text(label)
    .fontSize(40)
}

@Entry
@Component
struct Index {
  @State message: string = 'Hello XComponent'
  @State messageCommon: string = 'Hello World'
  build() {
    Row() {
      Column() {
        XComponent({ id: 'xcomponentId-container', type: 'component' }) {
          addText(this.message)
          Divider()
            .margin(4)
            .strokeWidth(2)
            .color('#F1F3F5')
            .width("80%")
          Column() {
            Text(this.messageCommon)
              .fontSize(30)
          }
        }
      }
      .width('100%')
    }
    .height('100%')
  }
}

相關實例

針對XComponent，有以下示例工程可供參考：

• Native XComponent組件的使用（ArkTS）