react-native-stylus-pen 为 React Native 鸿蒙应用提供了手写画布、Pen Kit 一笔成形与报点预测能力。配套实战项目“智绘手写讲义本”用于讲义圈注、轻触标记和停顿成形验证,并在华为畅享 100 Pro Max 真机与 API 26 模拟器上核对笔迹保留、图形替换及预测通道回退。
配套实战项目已开源在 abaoge/stylus-sketch-notebook,第三方库完整代码已开源在 oh-react-native/react-native-stylus-pen,有问题可到第三方库仓库提 Issue,也可以来 鸿蒙系统 React Native 开源社区 交流。

前言

我在 React Native 0.84 鸿蒙端写了一个手写批注应用“智绘手写讲义本”,用来在讲义页面上圈重点、点圆点做记号,也能把随手画的连接线规整成直线。起初我在 VS Code 里用 HarmonyOS Dev Assistant(v0.2.3,“三方库鸿蒙化”模式) 根据最小接口契约桩生成了手写库的跨端桥接初稿,构建出 HAR 与调试安装包;工具在最后阶段也主动报出多指结束判断与成形竞态风险,同时提醒需要签名真机确认 Pen Kit 实际回调行为。

把代码迁移到标准工程目录并签名装到华为畅享 100 Pro Max 真机手写时,我进一步核对出几处真机细节:轻点留下的圆点一抬手就没了,停顿规整出直线后原来的歪线还叠在底下。顺着触控事件、画布重绘和识别回调逐项重构后,我补上单点实心圆绘制、重写了一笔成形替换条件,并保留可选 C 预测库的运行时懒加载。改完再测,真机上的轻点标记和直线替换都恢复正常;换到缺少 C 预测库的 API 26 模拟器上,应用也能打开页面并回退到 ArkTS 预测。下面结合工具生成与真机重构过程,聊聊接入 Pen Kit 时需要留意的细节。


一、使用场景与真实痛点

1.1 讲义手写批注场景与三个交互难点

📱 “智绘手写讲义本”包含架构草图、几何成形和速写便签三个页签。日常批注时,我通常会先用自由曲线圈出关键段落,在节点旁边轻点一下打上圆点标记,再换种颜色或笔宽补充说明;写错了就单步撤销,或者清空当前页重画。遇到模块之间的连接线时,切到一笔成形模式画线并在末尾按住半秒,让系统把歪斜手绘线替换成规整直线。

要把这套交互在 React Native 鸿蒙页面里做稳,需要解决三个具体问题:

  1. 补回同一帧内合并的历史触点:手指快速划过屏幕时,系统会把同一渲染帧内的多次采样合并进一次移动事件。如果画布只连接每帧末尾的单个坐标,曲线拐角就会发折,送给预测接口的轨迹点也不够密。画布需要先把帧内历史触点取出来拼回点列,再做平滑绘制和预测。
  2. 接入系统一笔成形并替换原笔迹:停顿成图依赖鸿蒙 @kit.Penkit 提供的 InstantShapeGenerator。原生画布不仅要把触控序列喂给识别器,还要在识别成功后准确擦掉刚才那笔手绘线、换上标准几何路径,同时通知前端页面更新本页的笔迹与成形计数。
  3. 兼容缺少 C 预测库的运行镜像:真机固件带有 libhandwrite_ndk.z.so,可直接调用 C 接口 HMS_HandWrite_GetPredictPoint 计算预测点;但本地测试用的 API 26 模拟器镜像没有预装这个共享库。如果编译期把它写成硬链接依赖,应用在 JS 代码执行前就会因找不到动态库而无法启动,因此必须改成运行时按需探测,并在缺库时回退到 ArkTS 的 PointPredictor。

1.2 三层职责分工与 HarmonyOS Dev Assistant 辅助适配

这个实战项目没有把原生画布和 C++ 代码直接堆进业务工程,而是引用了独立的第三方手写库 react-native-stylus-pen(版本 0.1.0,鸿蒙模块名 @rnoh/react-native-stylus-pen,MIT 许可)。底层画布渲染、Pen Kit 引擎生命周期和双通道预测都收拢在手写库内部;实战项目 stylus-sketch-notebook 只通过公开组件和接口组织多页讲义、工具栏与状态面板。系统底座、第三方库与实战应用各自的分工如下:

架构层次所属载体核心职责与边界
系统底座层@kit.Penkit 与手写 NDK 库提供系统能力检测、一笔成形、ArkTS 点预测、单帧加速及 C 侧点预测接口;接口存在不代表当次调用一定成功
通用三方库📦 react-native-stylus-pen提供 StylusCanvasView 画布与 RNStylusPen 模块,负责动态库懒加载与负缓存、历史点补偿、曲线与单点绘制、一笔成形替换及原地撤销清空
独立实战层stylus-sketch-notebook外部引入手写库,管理三页讲义切换、颜色线宽工具栏、按页笔迹类型撤销栈、书写期外层滚动锁定及能力探测面板

表1 三层职责划分

图 1 展示了讲义页面上从画线、停顿到替换成形的交互过程与三层调用关系:

手机画线停顿成形与应用、手写库、Pen Kit 分层

图1 批注成形链路

准备手写库初稿时,我先手写了 src/NativeStylusPen.ts、src/StylusCanvasViewNativeComponent.ts 与 harmony/stylus_pen 下共 6 份最小接口契约桩定好导出函数和画布属性名,随后在 VS Code 中打开 HarmonyOS Dev Assistant(v0.2.3),切换到底栏的 三方库鸿蒙化 模式(模型 DeepSeek/DeepSeek V4.1 Flash 1017)提交适配需求,让工具基于契约桩和 API 26 SDK 声明补齐跨端桥接与画布实现(见图 2)。

在 VS Code HarmonyOS Dev Assistant 三方库鸿蒙化模式提交适配需求

图2 助手输入需求

收到需求后,助手先执行了平台与工程检测,确认当前仓库属于带有 HAR 契约桩但尚未生成的 React Native 模块工程,并将任务路由到适配统一入口,按“现状分析 → 代码编写 → 编码校验”三阶段依次推进(见图 3)。

HarmonyOS Dev Assistant 完成平台识别并路由到三方库鸿蒙化统一入口

图3 助手检测路由

工具帮我快速产出 01-analysis-prd.md、955 行的 StylusCanvasView.ets 与 371 行的 stylus_pen_predictor.cpp 等适配代码,也通过静态检验打出了 stylus_pen.har(25,272 B)和无签名测试安装包。不过助手阶段 3 校验报告同时指出了 3 项功能风险,且由于签名标识不匹配未能安装到实体机验证。随后我结合华为畅享 100 Pro Max 真机实测重写了多项手势与路径逻辑,这部分生成对比放在 3.4 节,真机排查过程则见第三、四节。


二、真机与模拟器双端实测效果与对比

我把实战项目 stylus-sketch-notebook 编译成调试 HAP,分别安装到华为畅享 100 Pro Max 真机和 HarmonyOS API 26 模拟器上,按同样的步骤验证能力探测、报点预测和画板批注。两台运行环境的软件版本与配置记录在表 2:

环境项实测记录
开发主机与工具链macOS,Node.js 22
React Native / React0.84.1 / 19.2.3
RNOH 及鸿蒙 CLI@react-native-oh/react-native-harmony 与对应 CLI 均为 0.84.6
编译 SDK / 目标 APISDK 26.0.0.105,目标 API 26
实体真机华为畅享 100 Pro Max,OpenHarmony 7.0,API 26,phone,arm64
本地模拟器HarmonyOS API 26,phone,arm64(系统镜像不含 libhandwrite_ndk.z.so)
AI 三方库适配工具VS Code HarmonyOS Dev Assistant v0.2.3
工具模式 / 模型三方库鸿蒙化 / DeepSeek/DeepSeek V4.1 Flash 1017
第三方库与实战工程react-native-stylus-pen 0.1.0;stylus-sketch-notebook 0.1.0
验证方式与输入参数调试包功能与回执核验;手指触控与指令注入,停顿阈值 500 毫秒,笔宽 2、4、7 vp
权限声明与未测范围已声明 ohos.permission.STYLUS_FRAME_BOOST;主动压感笔及 Android、iOS 真机运行未测

表2 设备与环境

这里要把工程声明的最低兼容版本和实际验证范围区分开:鸿蒙工程配置虽然保留了 API 17 下限,但本文记录的能力表现都基于 API 26 环境测得,低版本系统未必具备同等的 Pen Kit 接口支持。

2.1 真机能力自检、C NDK 点预测与模拟器缺库降级

📱 在华为畅享 100 Pro Max 真机上打开“智绘手写讲义本”,首屏默认聚焦讲义书写画布(见图 4),顶部提供“架构草图 / 几何成形 / 速写便签”三个讲义页签,底部集成“自由手绘 / 一笔成形”切换、四色墨水与三档笔宽工具栏。页面挂载时会自动调用 getCapabilities() 汇总 ArkTS 与 C++ 两侧的探测结果,点击右上角“运行详情”即可随时展开底层能力与预测探针卡片。

真机运行智绘手写讲义本清爽画板首屏

图4 真机讲义首屏

展开真机的“运行详情”诊断面板可以看到,Pen Kit 系统能力、InstantShapeGenerator 和 PointPredictor 全部可用;原生手写动态库状态为 loaded · arm64,预测主通道走 ndk (ndk=yes, arkts=yes)。而单帧加速 StylusFrameBoost 在这次探针调用中返回了 1,卡片如实显示“不可用(1)”与 forceRefreshOneFrame returned 1 (failed),总状态标为降级态。返回 1 只代表当次刷帧调用未成功,不能凭这一个数字推断是签名权限不足还是机型限制。

接着点击卡片里的“多点预测”按钮,并顺带点按“单点预测”、“NDK 状态”与“帧加速”核对回执。真机通过 NAPI 调用底层 HMS_HandWrite_GetPredictPoint,返回 {"ok":true,"x":81,"y":141,"code":0,"source":"ndk","message":"ok"}(见图 5)。多次点击预测和状态查询后,原生层记录的动态库加载次数 attempts 一直保持为 1,没有重复执行打开操作。

真机触发多点预测返回 C NDK 预测坐标

图5 真机预测回执

💻 把同一个实战安装包放到 HarmonyOS API 26 模拟器运行后,动态加载器返回 Error loading shared library libhandwrite_ndk.z.so: No such file or directory。得益于运行时懒加载隔离,应用没有在启动阶段闪退,而是正常渲染出讲义主页,并将预测主通道切换为 arkts (ndk=no, arkts=yes)(见图 6)。

API 26 模拟器缺库自动降级为 ArkTS 预测通道

图6 模拟器降级页

我在模拟器上连续点击“单点预测”和“NDK 状态”,attempts 同样保持在 1 次——第一次探测发现缺库后,负缓存直接拦住了后续的重复查找。真机与模拟器的实测对照整理如下:

对比项华为畅享 100 Pro Max 真机HarmonyOS API 26 模拟器
Pen Kit ArkTS 引擎一笔成形与点预测均可用一笔成形与点预测均可用
手写 C 动态库加载loaded · arm64,符号解析通过缺少共享库,记录负缓存并返回错误详情
重复调用 attempts保持 1 次,直接复用已打开句柄保持 1 次,负缓存跳过后续 dlopen
报点预测主通道ndk (ndk=yes, arkts=yes)回退至 arkts (ndk=no, arkts=yes)
预测按钮调用回执返回坐标 (81, 141),状态码 0走 ArkTS 预测与参数校验,测试操作未见异常退出
单帧加速探针结果返回码 1,界面显示降级提示返回码 1,界面显示降级提示

表3 双端实测对照

2.2 单点圆点保留、多色分笔隔离与一笔成形动态验证

在讲义上做批注时,随手点一个圆点标出重点位置是很常见的操作。修复单点被折线门槛过滤的问题后,我在真机画板上选了 7 号粗笔,先后切换红色和绿色在画布左右两侧各点一下并立刻抬手。重绘完成后,红、绿两个实心圆点稳稳留在画布上,底部状态栏记录累计事件数为 4(见图 7)。

真机轻点画布抬手后红绿实心圆点完好保留

图7 单点圆点保留

接着点一下“清空画布”(实战页把受控属性 clearCount 加 1,由原生画布原地擦除,不卸载重建视图),再依次换成蓝色 4 号笔、红色 7 号笔和绿色 2 号笔划出三条不同方向的曲线。从图 8 可以看到,后画的笔色和粗细不会串染前面的历史笔迹。此时页面顶部计为“本页笔迹 3 · 成形 0”,累计事件数 123,末尾抬笔坐标为 up (286.7, 260.0) force=0.00,当笔触点与历史点计数为 87 / 0,预测状态显示 ndk ok=true code=0 ok。

真机自由手绘蓝红绿三笔颜色与线宽独立隔离

图8 三笔样式隔离

再切换到“一笔成形”模式并清空画布,用绿色画笔从左往右拉出一条线,笔尾按住停顿半秒左右。图 9 录下了从手指滑动到自动变直线的过程:起始移动阶段事件数为 51,触点与历史点显示 112 / 1,说明这次移动回调里确实带回了被合并的帧内历史采样点;按住满 500 毫秒后,InstantShapeGenerator 触发识别回调,画布当场擦除原来的手绘线并绘出标准直线。松手后的终态见图 10,画面干净,没有残留旧笔迹重影或终点圆点。

真机一笔成形划线停顿自动规整为直线动态过程

图9 一笔成形过程

真机一笔成形识别完成后的画布与遥测终态

图10 一笔成形终态

图 10 顶部统计更新为“本页笔迹 1 · 成形 1”,下方显示累计事件数 183、抬笔位置 up (293.3, 176.7) force=0.00,识别结果为 line (shapeType=1) 已替换笔迹,编码串为 shapeString: 1,50,146.667,291.667,176.667。

我也抓取了真机运行期间的 hilog 日志核对底层执行顺序(见图 11):应用启动后 styluspen_native 先完成模块注册,随后 RNOH 创建 RNStylusPen 实例并打印 handwrite ndk loaded (arm64);等到手指停顿触发一笔成形时,画布层输出了带 hasShapePath=true 标记与完整形状编码串的 shapeRecognized 日志,和前端面板展示的数据一致。

真机全链路原生加载与一笔成形日志记录

图11 真机关键日志


三、原理与核心代码分析

3.1 跨端接口契约与实战页笔迹状态同步

HarmonyOS API 26 的手写能力分布在两层接口里:系统能力查询、InstantShapeGenerator、PointPredictor 和 StylusFrameBoost 位于 @kit.Penkit 的 ArkTS 模块中;而低延迟点预测函数 HMS_HandWrite_GetPredictPoint 与底层刷帧开关则放在系统共享库 libhandwrite_ndk.z.so 的 C 符号表中。

为了把这两层能力干净地暴露给前端,react-native-stylus-pen 在 NativeStylusPen.ts 里统一用异步 JSON 字符串返回能力报告、原生状态和预测回执,把缺库、参数越界和调用失败转成状态码字段。而在画布组件 StylusCanvasViewNativeComponent.ts 上,高频触发的触控事件直接用扁平数值回传坐标、压力和预测点,避免每帧构造嵌套数组;同时提供整型受控属性 clearCount 和 undoCount,前端把数字加 1 即可通知画布原地清空或弹出最后一笔,不用卸载重建画布实例。一次触控在页面、手写库与系统引擎间的流转顺序见图 12:

双通道预测与一笔成形跨端交互时序

图12 跨端桥接时序

实战项目在 App.tsx 中用滚动视图包裹了诊断卡片和画板。为了防止竖向画长线时被外层容器半途抢走手势,页面在画布按下和移动阶段暂停外层纵向滚动,抬笔或手势取消后再恢复。同时,页面按页维护笔迹类型栈,收到一笔成形回调时根据 replaced 字段同步栈内记录,保证多次点击“撤销上笔”时顶部的笔迹数和成形数准确回退:

const onShapeRecognized = useCallback(
  (event: { nativeEvent: StylusShapeEventPayload }) => {
    const payload = event.nativeEvent;
    setLastShape(payload);
    // 只有原生画布确认已替换原笔迹时,才更新本页的成形统计栈
    if (!payload.replaced) {
      return;
    }
    if (touchSessionRef.current.active) {
      // 笔尖仍按在屏幕上停顿触发成形:原生已直接把规整图形压入画布栈
      touchSessionRef.current.inStrokeShapePushed = true;
      updatePageHistory(activeNote.id, (list) => [...list, 'shape']);
    } else {
      // 刚抬笔瞬间到达的识别回调:把刚入栈的最后一笔自由线改成规整图形
      updatePageHistory(activeNote.id, (list) => {
        if (list.length === 0) {
          return list;
        }
        const copy = list.slice();
        copy[copy.length - 1] = 'shape';
        return copy;
      });
    }
  },
  [activeNote.id, updatePageHistory],
);

3.2 动态库懒加载、负缓存与宿主原生接线

前面在模拟器实测时提到,并非所有 HarmonyOS 镜像都带有 libhandwrite_ndk.z.so。一旦在 CMake 构建脚本里把它写进 target_link_libraries,动态链接器在加载应用主模块时就会因为找不到依赖库直接报错中断。

因此手写库把 C++ 产物拆成了两部分:静态胶水库 rnoh_stylus_pen 只对接 RNOH 的组件与模块注册;独立共享库 styluspen_native 只链接 NAPI、HiLog 与系统 dl 库,把 libhandwrite_ndk.z.so 留到运行时按需打开。实战宿主工程 stylus-sketch-notebook 在 harmony/entry 下挂载这套原生模块的实际配置如图 13 所示:

实战宿主工程 CMake 挂载与双侧模块注册配置

图13 宿主原生接线

运行时,handwrite_predictor.cpp 里的 LoadLocked() 负责打开共享库并解析预测函数符号(调用方已加锁)。这里做了两处防护:一是把缺库和缺符号状态缓存在 state_ 枚举中,后续移动帧命中失败缓存便直接返回,避免反复执行 dlopen 刷屏报错;二是若共享库已打开却找不到目标符号,当场调用 dlclose 释放句柄再记录失败状态:

bool HandwritePredictor::LoadLocked() {
  if (state_ == LibraryState::kLoaded) {
    return true;
  }
  // 命中缺库或缺符号负缓存时直接返回,避免移动帧反复触发 dlopen
  if (state_ == LibraryState::kMissing || state_ == LibraryState::kSymbolMissing) {
    return false;
  }
  attempts_ += 1;

  dlerror();  // 先清空残留的动态链接错误信息
  handle_ = dlopen(kLibraryName, RTLD_LAZY | RTLD_LOCAL);
  if (handle_ == nullptr) {
    const char* err = dlerror();
    last_error_ = err == nullptr ? std::string("dlopen failed") : std::string(err);
    state_ = LibraryState::kMissing;
    OH_LOG_Print(LOG_APP, LOG_WARN, 0, kLogDomain, "dlopen %{public}s failed: %{public}s", kLibraryName,
                 last_error_.c_str());
    return false;
  }

  dlerror();
  void* symbol = dlsym(handle_, kSymbolName);
  if (symbol == nullptr) {
    const char* err = dlerror();
    last_error_ = err == nullptr ? std::string("dlsym failed") : std::string(err);
    // 库已打开但缺少预测符号,必须先关闭句柄防止资源泄漏
    dlclose(handle_);
    handle_ = nullptr;
    state_ = LibraryState::kSymbolMissing;
    OH_LOG_Print(LOG_APP, LOG_ERROR, 0, kLogDomain, "dlsym %{public}s failed: %{public}s", kSymbolName,
                 last_error_.c_str());
    return false;
  }

  get_predict_point_ = reinterpret_cast<GetPredictPointFn>(symbol);
  state_ = LibraryState::kLoaded;
  last_error_.clear();
  OH_LOG_Print(LOG_APP, LOG_INFO, 0, kLogDomain, "handwrite ndk loaded (%{public}s)", AbiName().c_str());
  return true;
}

3.3 历史触点补偿、尾部 32 点切片与单点绘制

在手指滑动过程中,StylusCanvasView.ets 每收到一次移动事件,都会先调 event.getHistoricalPoints() 把同一帧内合并的中间采样点取出来,再追加当前帧末尾触点。由于合成事件或降频场景下历史点时间戳可能上报为 0,代码在换算时间戳时加了有限数判断与非负下限保护,防止算出负数时间戳被 C 预测层当成非法参数拦截。同时,C 侧预测接口单次最多只消费最近 32 个点,画布在发起预测前只截取当前点列的末尾 32 个点跨桥传输,避免长笔画累积上百个点后反复整组拷贝。

绘制笔迹时,多点轨迹用相邻采样点中点作为锚点连成平滑二次贝塞尔曲线;但如果用户只是在讲义上轻点了一下做标记,points 数组里就只有 1 个坐标点。Canvas 2D 的折线描边在单个点上画不出可见线段,所以 drawStroke 专门把单点笔迹分流给 drawDot 画成实心圆,已识别的标准几何图形则直接描边各自保存的 Path2D 路径:

private drawStroke(ctx: CanvasRenderingContext2D, stroke: Stroke) {
  if (stroke.kind === 'freehand') {
    // 单点轻触没有线段长度,走折线描边会消失,需单独填充实心圆
    if (stroke.points.length === 1) {
      this.drawDot(ctx, stroke.points[0].x, stroke.points[0].y, stroke.color, stroke.width);
    } else {
      this.drawPolyline(ctx, stroke.points, stroke.color, stroke.width);
    }
  } else {
    // 一笔成形图形按该笔落笔时保存的颜色、线宽与原生路径独立描边
    ctx.strokeStyle = stroke.color;
    ctx.lineWidth = stroke.width;
    ctx.lineJoin = 'round';
    ctx.lineCap = 'round';
    ctx.stroke(stroke.path);
  }
}

private drawDot(ctx: CanvasRenderingContext2D, x: number, y: number, color: string, width: number) {
  ctx.fillStyle = color;
  ctx.beginPath();
  // 圆点半径取线宽的一半,并保留 0.5 的最小可见半径下限
  ctx.arc(x, y, Math.max(0.5, width / 2), 0, 2 * Math.PI);
  ctx.fill();
}

3.4 HarmonyOS Dev Assistant 生成产出与真机重构对照

🔍 回过头对比工具自动生成阶段产出与最终真机重构代码,能更清楚看出 HarmonyOS Dev Assistant(三方库鸿蒙化模式) 帮开发者解决了什么、又把哪些问题交回真机阶段把关。图 14 记录了助手生成核心 C++ 预测桥接源码 stylus_pen_predictor.cpp 时的实时工作区界面——可以看到它已经准确按无链接策略用 dlopen("libhandwrite_ndk.z.so") 与 dlsym 懒加载 HMS_HandWrite_GetPredictPoint,在文件头主动用 static_assert(sizeof(StylusHistoricalPoint) == 24) 对齐 C ABI 结构体,并列出 12 条参数与缺库负缓存边界。

HarmonyOS Dev Assistant 生成 C++ dlopen 预测桥接源码过程

图14 助手生成桥接

完成全部三阶段后,助手输出 03-validation-report.md 编码校验报告并给出了构建与抽查统计(见图 15):自动生成了 955 行的 StylusCanvasView.ets、201 行的 StylusPredictor.ets、170 行的 RNStylusPenTurboModule.ets 与 371 行的 stylus_pen_predictor.cpp,通过静态检查打出 25,272 字节的 HAR 与无签名 HAP,并经 llvm-nm 确认预测符号未硬链接进二进制。同时,工具自己也标出 0 个 P0、3 个 P1:第二指抬起误结束活动笔、成形回调 generation 竞态可能错替下一笔、以及 strokeWidth 1–2 被强制抬高至 3,并如实注明因签名与真机不匹配未能上机验证。

HarmonyOS Dev Assistant 输出构建校验统计与待确认 P1 风险

图15 助手适配总结

把工具三阶段生成结果与最终公开在社区仓里的真机重构版本对照,两边的分工与收敛点如下:

对比维度HarmonyOS Dev Assistant(v0.2.3)产出真机与模拟器实测后人工重构收敛
工程目录与构建脚本临时产出放在 ohos/harmony/stylus_pen 子工程及独立 libstylus_pen_predictor.so收敛回标准根目录 harmony/stylus_pen,合并轻量原生库为 styluspen_native 对接宿主 entry
C NDK 动态加载自动设计 dlopen + dlsym、kUnavailable 负缓存与连续 3 次非 0 降级 kDegraded保留运行时懒加载与负缓存主干,精简导出接口给前端遥测面板消费
一笔成形回调防错位使用递增 generation 追踪最近落笔,工具自检即提醒“下一笔落笔后迟到回调仍可错替”改为 isTouchActive + 800 毫秒 lastCommittedShapeCandidate 失效窗与新落笔作废守卫
原生路径与微小圆点复用 shapeInfo.shapePath,工具自检提醒 Tap 两次重合点走 lineTo 需真机核对实测确认并加上 resolveShapePath 优先复用与停顿后残留 Move 拦截、drawDot 单点实心圆
多指与参数契约工具阶段 3 独立排查出第二指 Up/Cancel 误触发与 strokeWidth 1–2 被抬高问题改为严格按 activeTouchId 过滤变更触点、放开 1–200 vp 正 finite 校验与 StylusFrameBoost code === 0 判定

表4 助手与实测对照


四、踩坑与边界条件

4.1 一笔成形的原迹残留与快写错位替换

🐛 真机上出现重影时,我发现抬笔事件 TouchType.Up 已把手绘线存入 this.strokes,随后到达的识别回调又追加了一条直线,两笔就叠在一起了。

初稿用 pendingReplaceIndices 记录每次抬笔的下标。连续写几笔都不停顿时,旧下标会留在队列里。等后面一笔触发识别,shift() 可能取到早先的下标,覆盖已经写好的字。

我去掉队列,用 isTouchActive 判断是否还在写,并用 lastCommittedShapeCandidate 只保留最近一次抬笔的候选。

  • 还在写(this.isTouchActive)。回调只处理当前笔迹。shapeType === 0 时保留点列,用户可以继续写。识别出图形后,清空当前点列、存入图形,并将 shapeRecognizedInStroke 设为 true。
  • 已抬笔。识别成功且候选仍有效时,回调可在抬笔后 800 毫秒内替换刚提交的一笔,沿用原来的颜色和线宽。新落笔、取消、撤销、清空或切换模式都会作废候选,超时也会保留原笔迹。

4.2 抬笔点列被提前清空与单帧加速返回码误判

排查前端状态栏时,我发现初稿在 TouchType.Up 分支先调用 commitCurrentStroke() 清空了 this.currentPoints,再序列化 pointsJson,JS 收到的总是空数组。我改成先用 const emittedPoints = this.currentPoints.slice() 保存副本,再提交笔迹。

诊断卡片也把单帧加速的失败回执显示成了可用。我核对了 API 26 SDK 的 @kit.Penkit 声明,StylusFrameBoost.forceRefreshOneFrame(action) 返回 0 表示成功,1 表示失败,权限拒绝会抛出 201 异常。现在 StylusPenCapabilities.ets 中的 probeFrameBoost() 用 code === 0 判断成功,并在提示里保留非 0 返回码。

图 11 里还有一条 ForceRefreshOneFrame same action value 日志。探针每次都传抬笔动作 1,单凭这条日志无法确认失败原因。业务接入单帧加速时,仍要按落笔、移动、抬笔的实际顺序验证。

4.3 真机原生路径复用与停顿后的微小触点拦截

🔍 在华为畅享 100 Pro Max 上,日志已报出 shapeType=1,画布上却只剩笔尾的圆点。图 11 的 hasShapePath=true 帮我确认了直线为什么没画出来。回调已给出画布能用的原生 Path2D,初稿仍用 getPathFromString 重建,结果没画出轮廓。

笔尾圆点来自另一条路径。手指停顿成形后还没离开屏幕,后续 Move 又往已清空的点列加了坐标,抬笔时便画成了圆点。我在 TouchType.Move 与 TouchType.Up 中检查 shapeRecognizedInStroke,已成形的一笔跳过后续采样,抬笔后复位。

StylusCanvasView.ets 中的 resolveShapePath 优先使用 shapeInfo.shapePath。原生路径缺失时才尝试解析字符串,解析失败时会返回空路径,回调仍可能替换原笔迹。

private resolveShapePath(shapeInfo: ShapeInfo, penWidth: number): Path2D {
  // 真机回调已附带原生 Path2D 时直接复用,避免字符串重建后丢失轮廓
  if (shapeInfo.shapePath !== undefined && shapeInfo.shapePath !== null) {
    return shapeInfo.shapePath;
  }
  const generator: InstantShapeGenerator | undefined = this.instantShapeGenerator;
  if (generator !== undefined && shapeInfo.shapeString.length > 0) {
    try {
      return generator.getPathFromString(shapeInfo.shapeString, penWidth);
    } catch (e) {
      // 识别器已释放或编码串非法时捕获异常,交给下方空路径兜底
    }
  }
  return new Path2D();
}

4.4 参数范围校验、防抢占滚动与未测边界

  • 手势中断。画布按 activeTouchId 过滤其他手指的坐标。如果父容器接管手势,导致抬笔事件丢失,画布核对当前按下的触点后会清理残留状态。这项过滤只覆盖触点编号,硬件防掌触另需验证。
  • 画布属性。Pen Kit 的 setPauseTime 接受 200 至 2000 毫秒的整数,画布按这个范围限制 pauseTime。strokeWidth 须为正有限数,上限为 200 vp。识别器初始化中途出错时调用 release() 释放实例。
  • 预测参数。JSON 会把 NaN 和 Infinity 转成 null。JS、ArkTS、C++ 分别检查数值、坐标和时间戳范围,C++ 还检查输出坐标是否有限。给多点预测接口传一个点时,库会补足两个点,满足底层要求。

我也对齐了鸿蒙与非鸿蒙入口的导出字段。库的 18 项自动化测试覆盖接线、候选窗、32 点切片和异常参数,实战项目的 5 项测试核对外部依赖、滚动锁定和撤销栈。

文中的手指触控记录压力为 0.00,主动式手写笔压感及 Android、iOS 设备运行尚未测试。


五、结论与可直接复用的建议

💡 如果你的 React Native 0.84 鸿蒙应用也需要手写圈注、停顿成图或报点预测,可以直接引入 react-native-stylus-pen,不必从头编写 C++ 动态加载和画布路径替换逻辑。接入前建议先在目标设备上调一次 getCapabilities(),根据返回的预测通道状态决定是否开启辅助诊断提示。

5.1 宿主工程依赖安装、原生接线与核心选项

在 React Native 0.84 鸿蒙宿主工程根目录安装官方第三方库 oh-react-native/react-native-stylus-pen,并在 harmony/entry/oh-package.json5 中添加本地模块映射:

npm install "git+https://atomgit.com/oh-react-native/react-native-stylus-pen.git"
{
  "dependencies": {
    "@rnoh/react-native-openharmony": "0.84.6",
    "@rnoh/react-native-stylus-pen": "file:../../node_modules/react-native-stylus-pen/harmony/stylus_pen"
  }
}

执行 ohpm install 后,由于鸿蒙 HAR 包只打包 ArkTS 源码而不内嵌 C++ 编译产物,宿主工程只需对照前文图 13 完成三步原生接线:

  1. 挂载子包 CMake 目录:在宿主 entry/src/main/cpp/CMakeLists.txt 中引入子包 C++ 目录,把 rnoh_stylus_pen 和 styluspen_native 链入 rnoh_app(不要硬链接系统手写预测库);
  2. 注册 Package 与自定义画布:在 PackageProvider.cpp 和 RNPackagesFactory.ets 中注册 RNStylusPenPackage,并在 Index.ets 的 arkTsComponentNames 中登记 'StylusCanvasView';
  3. 对齐 API 等级与可选权限:将编译与目标 SDK 设为 HarmonyOS API 26;若需探测单帧加速,在 module.json5 中声明 ohos.permission.STYLUS_FRAME_BOOST。

StylusCanvasView 常用属性与事件回调说明如下:

属性 / 回调类型与默认值用途与边界说明
mode'freehand'(默认)| 'instantShape'切换自由手绘或 Pen Kit 一笔成形模式,传入未知值时自动回退为自由手绘
strokeColor / strokeWidthstring ('#1F6FEB') / number (默认 3)按笔保存落笔时的颜色与线宽(单位 vp,上限 200),切换样式不影响已画好的笔迹
pauseTimenumber(默认 500 毫秒)一笔成形停顿触发时长,原生层自动限制在 200 至 2000 毫秒整数范围内
enablePredictionboolean(默认 true)开启移动帧报点预测,真机优先走 C NDK,缺少动态库时自动回退到 ArkTS 预测
clearCount / undoCountnumber(默认 0)每次把数值加 1 即可原地清空画布或撤销上一笔,无需销毁重建底层画布视图
onTouchEvent / onShapeRecognized原生事件回调通过 nativeEvent 读取实时触点与成形回执,用 replaced 判断是否已完成替换

表5 画布关键选项

5.2 可直接复用的最小画布组件

下面给出一个精简后的画布接入组件,保留了自由手绘与一笔成形切换、单步撤销、原地清空及成形结果提示;需要多页签与诊断面板时可参考配套实战工程 stylus-sketch-notebook:

import React, { useState } from 'react';
import { Button, Text, View } from 'react-native';
import { StylusCanvasView } from 'react-native-stylus-pen';

export function QuickSketchBoard() {
  const [mode, setMode] = useState<'freehand' | 'instantShape'>('freehand');
  const [clearCount, setClearCount] = useState(0);
  const [undoCount, setUndoCount] = useState(0);
  const [shapeTip, setShapeTip] = useState('切换一笔成形后,画线并按住半秒即可规整图形');

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Button
        title={mode === 'instantShape' ? '切回自由手绘' : '开启一笔成形'}
        onPress={() => setMode(mode === 'instantShape' ? 'freehand' : 'instantShape')}
      />
      {/* 把受控计数器加 1 即可通知原生画布原地撤销或清空,避免重挂载闪烁 */}
      <Button title="撤销上一笔" onPress={() => setUndoCount((n) => n + 1)} />
      <Button title="清空画布" onPress={() => setClearCount((n) => n + 1)} />
      <StylusCanvasView
        mode={mode}
        strokeColor="#1F6FEB"
        strokeWidth={4}
        enablePrediction={true}
        pauseTime={500}
        clearCount={clearCount}
        undoCount={undoCount}
        style={{ height: 340, backgroundColor: '#F6F8FA' }}
        onShapeRecognized={({ nativeEvent }) => {
          // 识别回调触发不等于原笔迹已被替换,需以 replaced 布尔值为准
          setShapeTip(nativeEvent.replaced ? `已替换为 ${nativeEvent.shapeName}` : '未替换,保留原手绘线');
        }}
      />
      <Text>{shapeTip}</Text>
    </View>
  );
}

小结

把这些细节逐一理顺后,“智绘手写讲义本”无论是在真机上随手点记号、换色画重点、停顿半秒拉直连接线,还是在缺 C 预测库的模拟器上回退运行,表现都稳定了下来 🎉。回头看整个过程,VS Code 里的 HarmonyOS Dev Assistant(三方库鸿蒙化模式) 确实能依据最小契约桩快速补全 TurboModule、Fabric 画布、dlopen 懒加载和 24 字节 ABI 镜像骨架,甚至在校验报告里提前点出多指和回调竞态隐患;但像快写几笔后的候选槽错位、真机原生 shapePath 复用以及停顿期间的微小触点过滤,仍然需要签好名装到屏幕上画几笔、对照日志逐帧核对才能抓出来。把每一次触控状态、原生回执和画布重绘对得严丝合缝,手写体验才算真正落了地。


参考资料

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐