《HarmonyOS技术精讲-UI开发 (基于NDK构建UI)》第4篇：高效Canvas绘制——NDK中的2D渲染加速

从JS到Native：一次性能跃迁

HarmonyOS NEXT 开发中，大部分UI交互通过ArkTS的CanvasRenderingContext2D完成。但当你需要处理大量动态图形------比如粒子系统、实时图表、游戏画面------JS桥接的瓶颈会立刻暴露出来。每帧数千次draw调用，每次调用都有JS到C++的跨语言开销，60fps的目标很快变成30fps甚至更低。

这个场景就是NDK绘制的典型应用。通过OH_NativeCanvas或直接调用Skia API，在Native侧完成所有绘制逻辑，只将最终结果渲染到屏幕上。JS侧只负责启动和生命周期管理，性能损耗从O(n)降到O(1)。

不过，NDK绘制不是万能的。如果你的绘制逻辑逻辑简单（比如只画几个静态形状），或者帧率要求不高（10fps以下），用ArkTS的Canvas完全足够。NDK的引入会增加代码复杂度和调试成本，需要合理评估。

环境与项目结构

text 复制代码

DevEco Studio 版本：DevEco Studio 6.1.0
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23)
目标设备：手机（API 12及以上）

项目采用C++侧封装绘制逻辑，ArkTS侧通过XComponent绑定视图。这是一种比较成熟的分层结构，JS负责UI布局，Native负责性能敏感的计算和绘制。

复制代码

entry/src/
├── main/
│   ├── cpp/
│   │   ├── CMakeLists.txt
│   │   ├── napi_particle.cpp       // NAPI接口实现
│   │   ├── particle_renderer.h     // 绘制引擎头文件
│   │   └── particle_renderer.cpp   // 核心绘制实现
│   └── ets/
│       └── pages/
│           └── Index.ets           // 页面入口，包含XComponent

核心实现：粒子引擎与NDK绘制

步骤1：创建绘制引擎

particle_renderer.h 定义粒子系统的核心结构。这里用简单的结构体表示粒子，用std::vector管理所有粒子实例。重点是RenderFrame方法，它接收OH_NativeCanvas*，在Native侧完成所有绘制。

cpp 复制代码

// particle_renderer.h
#ifndef PARTICLE_RENDERER_H
#define PARTICLE_RENDERER_H

#include <vector>
#include <cstdint>
#include "native_buffer_inner.h"
#include "native_window.h"

struct Particle {
    float x, y;      // 位置
    float vx, vy;    // 速度
    float size;      // 大小
    float alpha;     // 透明度
};

class ParticleRenderer {
public:
    ParticleRenderer(int32_t width, int32_t height);
    ~ParticleRenderer();

    // 初始化粒子系统
    void InitParticles(int count);
    // 更新粒子状态，模拟物理运动
    void Update(float deltaTime);
    // 渲染当前帧到Native画布
    void RenderFrame(OH_NativeCanvas* canvas, int32_t width, int32_t height);

private:
    std::vector<Particle> particles_;
    int32_t surfaceWidth_;
    int32_t surfaceHeight_;
};

#endif

初始化时需要注意 ：OH_NativeCanvas* 的类型在arkui/native_interface.h中定义，需要确保CMakeLists正确链接相关库。

步骤2：实现粒子系统逻辑

particle_renderer.cpp 里处理粒子的生成、运动和绘制。这里使用正态分布生成粒子位置，让它们从屏幕中心向四周扩散。Update方法模拟重力加速度和随机运动，让效果更自然。

cpp 复制代码

// particle_renderer.cpp
#include "particle_renderer.h"
#include <cmath>
#include <random>
#include <native_drawing/drawing_canvas.h>
#include <native_drawing/drawing_brush.h>
#include <native_drawing/drawing_path.h>

ParticleRenderer::ParticleRenderer(int32_t width, int32_t height)
    : surfaceWidth_(width), surfaceHeight_(height) {}

ParticleRenderer::~ParticleRenderer() {}

void ParticleRenderer::InitParticles(int count) {
    particles_.clear();
    std::random_device rd;
    std::mt19937 gen(rd());
    std::uniform_real_distribution<float> angleDist(0, 2 * M_PI);
    std::uniform_real_distribution<float> speedDist(50, 200);
    std::uniform_real_distribution<float> sizeDist(4, 12);
    std::uniform_real_distribution<float> alphaDist(0.3, 1.0);

    for (int i = 0; i < count; ++i) {
        float angle = angleDist(gen);
        float speed = speedDist(gen);
        Particle p;
        p.x = surfaceWidth_ / 2.0f;
        p.y = surfaceHeight_ / 2.0f;
        p.vx = cos(angle) * speed;
        p.vy = sin(angle) * speed;
        p.size = sizeDist(gen);
        p.alpha = alphaDist(gen);
        particles_.push_back(p);
    }
}

void ParticleRenderer::Update(float deltaTime) {
    const float gravity = 150.0f; // 向下重力
    for (auto& p : particles_) {
        p.vy += gravity * deltaTime; // 模拟重力
        p.x += p.vx * deltaTime;
        p.y += p.vy * deltaTime;

        // 超出边界回弹
        if (p.x < 0) { p.x = 0; p.vx = -p.vx; }
        if (p.x > surfaceWidth_) { p.x = surfaceWidth_; p.vx = -p.vx; }
        if (p.y > surfaceHeight_) { p.y = surfaceHeight_; p.vy = -p.vy; }

        // 随机衰减透明度
        p.alpha -= deltaTime * 0.3;
        if (p.alpha < 0.0f) {
            p.alpha = 0.0f;
        }
    }

    // 清除完全透明的粒子，并补充新粒子
    particles_.erase(
        std::remove_if(particles_.begin(), particles_.end(),
            [](const Particle& p) { return p.alpha <= 0.0f; }),
        particles_.end());

    // 保持粒子总数
    while (particles_.size() < 200) {
        std::random_device rd;
        std::mt19937 gen(rd());
        std::uniform_real_distribution<float> angleDist(0, 2 * M_PI);
        std::uniform_real_distribution<float> speedDist(100, 300);
        float angle = angleDist(gen);
        float speed = speedDist(gen);
        Particle p;
        p.x = surfaceWidth_ / 2.0f;
        p.y = surfaceHeight_ / 2.0f;
        p.vx = cos(angle) * speed;
        p.vy = sin(angle) * speed;
        p.size = 8.0f;
        p.alpha = 1.0f;
        particles_.push_back(p);
    }
}

void ParticleRenderer::RenderFrame(OH_NativeCanvas* canvas, int32_t width, int32_t height) {
    // 创建画布和画笔
    OH_Drawing_Canvas* drawingCanvas = OH_NativeCanvas_GetDrawingCanvas(canvas);
    OH_Drawing_Brush* brush = OH_Drawing_BrushCreate();
    OH_Drawing_Path* path = OH_Drawing_PathCreate();

    // 清除背景
    OH_Drawing_CanvasClear(drawingCanvas, OH_Drawing_ColorSetArgb(255, 30, 30, 40));

    // 绘制所有粒子
    for (const auto& p : particles_) {
        // 设置画笔颜色和透明度
        uint32_t color = OH_Drawing_ColorSetArgb(
            static_cast<uint8_t>(p.alpha * 255),
            120, 200, 255);
        OH_Drawing_BrushSetColor(brush, color);
        OH_Drawing_CanvasAttachBrush(drawingCanvas, brush);

        // 创建圆形路径
        OH_Drawing_PathReset(path);
        OH_Drawing_PathAddCircle(path, p.x, p.y, p.size, OH_Drawing_PathDirection::PATH_DIRECTION_CW);
        OH_Drawing_CanvasDrawPath(drawingCanvas, path);
    }

    // 释放资源
    OH_Drawing_PathDestroy(path);
    OH_Drawing_BrushDestroy(brush);
}

关键代码解释：

OH_NativeCanvas_GetDrawingCanvas：获取底层Skia画布指针，所有Skia API都可以直接操作。
每一帧都先清理画布，然后遍历所有粒子绘制。这里使用OH_Drawing_PathAddCircle画圆形粒子，如果数量更大（几千个），建议改用批量绘制或纹理方式。
更新逻辑里包含了粒子淘汰和补充机制，避免粒子全部消失后画面静止。

步骤3: NAPI接口对接

napi_particle.cpp 将C++类方法暴露给ArkTS。重点在于OnSurfaceChanged和OnDrawFrame两个回调，它们与XComponent的生命周期绑定。

cpp 复制代码

// napi_particle.cpp
#include "napi/native_api.h"
#include "napi/native_node_api.h"
#include <arkui/native_interface.h>
#include <arkui/native_node.h>
#include <arkui/native_type.h>
#include "particle_renderer.h"

static ParticleRenderer* g_renderer = nullptr;

// 初始化粒子系统，接收粒子数量参数
static napi_value InitParticles(napi_env env, napi_callback_info info) {
    if (!g_renderer) {
        g_renderer = new ParticleRenderer(400, 400);
    }
    g_renderer->InitParticles(200);
    return nullptr;
}

// 每一帧的更新和绘制函数，由ArkTS侧通过requestAnimationFrame触发
static napi_value UpdateAndDraw(napi_env env, napi_callback_info info) {
    if (!g_renderer) return nullptr;

    size_t argc = 3;
    napi_value args[3];
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    double deltaTime;
    napi_get_value_double(env, args[0], &deltaTime);

    // 获取XComponent的Native接口
    void* nativeWindow = nullptr;
    napi_get_value_external(env, args[1], &nativeWindow);
    OHNativeWindow* window = reinterpret_cast<OHNativeWindow*>(nativeWindow);

    int32_t width, height;
    napi_get_value_int32(env, args[2], &width);
    napi_get_value_int32(env, args[2], &height);

    if (window) {
        // 更新物理
        g_renderer->Update(static_cast<float>(deltaTime));

        // 获取Native Canvas
        OH_NativeCanvas* canvas = OH_NativeCanvas_FromNativeWindow(window);
        if (canvas) {
            int32_t canvasWidth, canvasHeight;
            OH_NativeCanvas_GetWidth(canvas, &canvasWidth);
            OH_NativeCanvas_GetHeight(canvas, &canvasHeight);
            // 渲染
            g_renderer->RenderFrame(canvas, canvasWidth, canvasHeight);
            OH_NativeCanvas_Unmap(canvas);
        }
    }

    return nullptr;
}

// 模块注册
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        { "initParticles", nullptr, InitParticles, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "updateAndDraw", nullptr, UpdateAndDraw, nullptr, nullptr, nullptr, napi_default, nullptr },
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}

NAPI_MODULE(particle_engine, Init)

需要特别注意 ：OH_NativeCanvas_FromNativeWindow 返回的画布只对当前帧有效，不能缓存复用。每次绘制前都要重新获取。OH_NativeCanvas_Unmap 必须在绘制完成后调用，否则下一帧无法继续获取画布。

步骤4: ArkTS入口与动画循环

Index.ets 负责创建XComponent，绑定Native模块，并通过requestAnimationFrame驱动动画循环。

typescript 复制代码

// Index.ets
import { particleEngine } from 'libparticle_engine.so';

@Entry
@Component
struct Index {
  private xComponentController: XComponentController = new XComponentController();
  private lastTimestamp: number = 0;

  aboutToAppear() {
    // 初始化粒子系统
    particleEngine.initParticles();
  }

  build() {
    Stack() {
      XComponent({
        id: 'particle_xcomponent',
        type: XComponentType.SURFACE,
        libraryName: 'particle_engine',
        controller: this.xComponentController
      })
        .onLoad(() => {
          // 开始动画循环
          this.startAnimation();
        })
        .width('100%')
        .height('100%')
        .backgroundColor(Color.Black)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  // 动画循环，请求下一帧
  private startAnimation() {
    const animate = (timestamp: number) => {
      const deltaTime = this.lastTimestamp === 0 ?
        0.016 : (timestamp - this.lastTimestamp) / 1000.0;
      this.lastTimestamp = timestamp;

      // 调用Native更新和绘制
      if (this.xComponentController.getXComponentSurfaceId()) {
        const nativeWindow = this.xComponentController.getXComponentSurfaceId();
        // 通过NAPI调用Native绘制
        particleEngine.updateAndDraw(
          deltaTime,
          nativeWindow,
          400, 400
        );
      }
      // 请求下一帧
      requestAnimationFrame(animate);
    };
    requestAnimationFrame(animate);
  }
}

注意：getXComponentSurfaceId()返回的是一个字符串，而在NAPI中我们把它当作void*类型传递。这个行为依赖底层实现，目前所有HarmonyOS NEXT版本都兼容这个用法，但不保证未来版本变化。更稳妥的方式是通过getXComponentNativeWindow()获取OHNativeWindow对象，但API 12上该接口是实验性的。

CMakeLists.txt 依赖配置

cmake 复制代码

cmake_minimum_required(VERSION 3.4.1)
project(particle_engine)

set(CMAKE_CXX_STANDARD 17)

add_library(particle_engine SHARED
    napi_particle.cpp
    particle_renderer.cpp
)

target_link_libraries(particle_engine
    ace_napi.z
    libace_native.z.so
    libnative_window.so
    libnative_drawing.so
)

确保链接了libnative_window.so和libnative_drawing.so，它们是OH_NativeCanvas和底层Skia API的基础。

常见问题

问题1：回调未及时触发

现象：XComponent的onLoad回调有时不执行，导致动画循环无法启动。

原因：XComponent的surface创建是异步操作，如果页面切换过快或者设备性能波动，onLoad可能会延迟甚至丢失。

解决方案 ：在aboutToAppear中先不给XComponent传libraryName，而在onLoad回调中动态绑定。或者在onLoad中添加超时重试逻辑。

问题2：导致死锁

现象：在updateAndDraw中调用OH_NativeCanvas_Unmap时卡住，线程阻塞。

原因：如果在ArkTS线程中直接调用NAPI，而同一个线程又被OH_NativeCanvas的内部锁阻塞，就会产生死锁。这个问题的触发条件比较苛刻，但对高性能动画场景影响很大。

解决方案 ：将绘制逻辑放到独立的Native线程中执行。通过uv_queue_work或pthread创建一个专用渲染线程，避免占用主线程。

最佳实践

避免在每一帧中创建和销毁OH_NativeCanvas ：OH_NativeCanvas_FromNativeWindow 每次返回不同的画布对象，但底层资源是复用的。不需要缓存画布，但要确保每次使用后都调用Unmap。
使用定点数优化粒子的位置更新 ：在粒子数量超过1000时，浮点数运算的消耗会变得明显。可以用int32_t和位移操作代替浮点数，提升20%-30%的性能。
控制粒子数量，优先保证帧率：200个粒子对NDK绘制来说非常轻松，但如果在手表或低端设备上，建议动态调整粒子数量，保证帧率不低于30fps。

总结

通过NDK实现Canvas绘制，核心价值在于消除JS桥接的性能瓶颈。但是，NDK引入的复杂度也带来了生命周期管理和线程安全的新问题。实际开发中，建议先用ArkTS Canvas验证功能，确认性能瓶颈后再迁移到NDK实现。如果一开始就上NDK，调试日志和问题定位会非常困难。

如果你也遇到类似问题，可以先检查XComponent的surface是否准备完毕，以及绘制回调是否在正确的线程中执行。这两个因素是NDK绘制最常见的坑。