HarmonyOS 6.1 云应用客户端适配实战（三）：触摸输入与坐标映射

前言

在前两篇文章中，我们完成了环境搭建和视频渲染的适配。本文将介绍另一个核心功能：触摸输入的适配。这是云应用客户端交互体验的关键，涉及复杂的坐标转换和协议适配。

本文涉及的关键技术：

• ArkTS 触摸事件 API
• N-API 数据传递
• 三级坐标系转换
• Windows SendInput 协议
• WebSocket 消息序列化（Protobuf）

核心挑战：

1. HarmonyOS 本地坐标 → 远程桌面像素坐标
2. 像素坐标 → Windows 归一化坐标（0-65535）
3. 触摸手势 → 鼠标事件映射
4. 绝对坐标 vs 相对坐标

一、触摸输入架构总览

1.1 数据流向

用户触摸屏幕 ↓ ArkTS TouchEvent (本地坐标) ↓ 坐标转换1: 本地坐标 → 远程像素坐标 ↓ N-API 传递 ↓ C++ SendPointerEvent (远程像素坐标) ↓ 坐标转换2: 像素坐标 → 归一化坐标 (0-65535) ↓ Protobuf 序列化 ↓ WebSocket 发送到服务端 ↓ 服务端 Windows SendInput API

1.2 坐标系统对比

坐标系	范围	说明
本地触摸坐标	0 ~ 屏幕尺寸	HarmonyOS 设备的物理像素
远程像素坐标	0 ~ 远程分辨率	Windows 桌面的像素坐标
归一化坐标	0 ~ 65535	Windows SendInput 要求的格式

为什么需要归一化坐标？
Windows SendInput API 使用MOUSEEVENTF_ABSOLUTE标志时，要求坐标为 0-65535 的归一化值，与实际屏幕分辨率无关。这样可以支持多显示器和不同分辨率。

二、ArkTS 层：触摸事件捕获

2.1 基础触摸事件处理

// ControlPage.ets@Entry@Componentstruct ControlPage{privateremoteWidth:number=0// 远程桌面分辨率privateremoteHeight:number=0privatelocalWidth:number=0// 本地屏幕尺寸privatelocalHeight:number=0build(){XComponent({...}).onAreaChange((oldArea,newArea)=>{// 监听本地尺寸变化this.localWidth=Number(newArea.width)this.localHeight=Number(newArea.height)console.log('[ControlPage] Local size:',this.localWidth,'x',this.localHeight)}).onTouch((event:TouchEvent)=>{this.handleTouch(event)})}handleTouch(event:TouchEvent){// 忽略无效事件if(this.dlcaPlayerId<0||!event.touches||event.touches.length===0){return}// 获取第一个触摸点（单点触摸）consttouch=event.touches[0]constlocalX=Math.floor(touch.x)constlocalY=Math.floor(touch.y)// 坐标转换：本地 → 远程constremoteCoords=this.localToRemote(localX,localY)// 发送到 Native 层this.sendTouchEvent(event.type,remoteCoords.x,remoteCoords.y)}}

2.2 坐标转换实现

// 本地坐标 → 远程像素坐标localToRemote(localX:number,localY:number):{x:number,y:number}{// 使用远程分辨率（从视频流中获取）constremoteW=this.remoteWidth>0?this.remoteWidth:1920constremoteH=this.remoteHeight>0?this.remoteHeight:1080// 使用本地尺寸constlocalW=this.localWidth>0?this.localWidth:1080constlocalH=this.localHeight>0?this.localHeight:720// 等比缩放constx=Math.floor(localX*remoteW/localW)consty=Math.floor(localY*remoteH/localH)return{x,y}}

关键点：

• 使用Math.floor确保坐标为整数
• 处理除零情况（使用默认值）
• 保持宽高比例一致

2.3 触摸事件类型映射

sendTouchEvent(type:TouchType,x:number,y:number){letbuttonMask:numberswitch(type){caseTouchType.Down:// 按下：LEFTDOWN | MOVE | ABSOLUTE = 0x0002 | 0x0001 | 0x8000 = 0x8003buttonMask=0x8003console.log('[Touch] DOWN at',x,y)breakcaseTouchType.Move:// 移动：MOVE | ABSOLUTE = 0x0001 | 0x8000 = 0x8001buttonMask=0x8001// 移动事件过多，不打印日志breakcaseTouchType.Up:// 抬起：LEFTUP | MOVE | ABSOLUTE = 0x0004 | 0x0001 | 0x8000 = 0x8005buttonMask=0x8005console.log('[Touch] UP at',x,y)breakdefault:return}// 调用 N-APIconstret=dlcaPlayer.sendPointerEvent(this.dlcaPlayerId,x,y,// 远程像素坐标buttonMask,// 鼠标事件标志0,// data (鼠标滚轮用)0,// modifiers (Ctrl/Shift等)0,0// xRel, yRel (相对移动))}

MOUSEEVENTF 标志位详解：

标志	值	说明
MOUSEEVENTF_MOVE	0x0001	移动鼠标
MOUSEEVENTF_LEFTDOWN	0x0002	按下左键
MOUSEEVENTF_LEFTUP	0x0004	抬起左键
MOUSEEVENTF_ABSOLUTE	0x8000	使用绝对坐标

为什么 DOWN/UP 也要包含 MOVE？

• Windows SendInput 要求：使用 ABSOLUTE 时，必须同时设置 MOVE 标志
• 这样可以确保鼠标先移动到目标位置，再执行按下/抬起动作
• 否则会出现"从上次位置到当前位置画线"的问题

三、N-API 层：接口封装

3.1 N-API 函数定义

// dlca_player_napi.ccstaticnapi_valueSendPointerEvent(napi_env env,napi_callback_info info){size_t argc=8;napi_value args[8];napi_get_cb_info(env,info,&argc,args,nullptr,nullptr);// 解析参数int32_tplayerId,x,y,buttonMask,data,modifiers,xRel,yRel;napi_get_value_int32(env,args[0],&playerId);napi_get_value_int32(env,args[1],&x);napi_get_value_int32(env,args[2],&y);napi_get_value_int32(env,args[3],&buttonMask);napi_get_value_int32(env,args[4],&data);napi_get_value_int32(env,args[5],&modifiers);napi_get_value_int32(env,args[6],&xRel);napi_get_value_int32(env,args[7],&yRel);// 获取 CloudClient 实例autoclient=GetClientById(playerId);if(!client){LOGE("Client not found: %d",playerId);napi_value result;napi_create_int32(env,-1,&result);returnresult;}// 调用 C++ 方法boolsuccess=client->SendPointerEvent(x,y,buttonMask,data,modifiers,xRel,yRel);// 返回结果napi_value result;napi_create_int32(env,success?0:-1,&result);returnresult;}

注意事项：

• 参数数量和类型必须与 ArkTS 调用一致
• 错误处理：返回 -1 表示失败
• 线程安全：N-API 回调在 ArkTS 线程，需要考虑跨线程访问

3.2 参数验证

boolCloudClient::SendPointerEvent(intx,inty,intbuttonMask,intdata,intmodifiers,intxRel,intyRel){// 检查是否允许发送鼠标事件if(!enable_mouse_event_send_){LOGW("Mouse event sending is disabled");returnfalse;}// 检查控制权限if(!IsRtcRemoteMode()){if(mCurrentControlPrivilege!=cloudapp::kMain){LOGW("Not main controller, cannot send mouse event");returntrue;// 返回 true 避免 ArkTS 层报错}if(GetStatus()==DLCA_STATUS_PAUSE){LOGW("Client is paused");returntrue;}}// 检查连接状态if(!mControl){LOGW("Control client is not initialized");returnfalse;}// 继续处理...}

四、C++ 层：坐标归一化

4.1 问题分析

从服务端日志发现，直接发送像素坐标会导致鼠标只能在左上角很小的区域移动：

// 错误的坐标（像素） x:857, y:433 → 鼠标在左上角 // 正确的坐标（归一化） x:29269, y:26214 → 鼠标覆盖整个屏幕

原因：Windows SendInput 使用 ABSOLUTE 标志时，要求坐标为 0-65535 范围。

4.2 归一化实现

boolCloudClient::SendPointerEvent(intx,inty,intbuttonMask,intdata,intmodifiers,intxRel,intyRel){// ... 前置检查 ...intfinalX=x;intfinalY=y;// 调试日志：转换前LOGI("Before normalize: x=%{public}d y=%{public}d mask=0x%{public}x screen=%{public}dx%{public}d",x,y,buttonMask,mCompressedPacketVideoWidth,mCompressedPacketVideoHeight);// 如果使用绝对坐标，进行归一化if((buttonMask&0x8000)&&mCompressedPacketVideoWidth>0&&mCompressedPacketVideoHeight>0){// 归一化公式：normalized = (pixel * 65535) / screenSizefinalX=(x*65535)/mCompressedPacketVideoWidth;finalY=(y*65535)/mCompressedPacketVideoHeight;LOGI("After normalize: (%{public}d,%{public}d) -> (%{public}d,%{public}d)",x,y,finalX,finalY);}// 创建 Protobuf 消息automessage=std::make_shared<cloudapp::Message>();message->set_type(cloudapp::kMouseEvent2);// 使用新协议cloudapp::MouseEvent*mouseEvent=newcloudapp::MouseEvent;mouseEvent->set_x(finalX);mouseEvent->set_y(finalY);mouseEvent->set_button(buttonMask);mouseEvent->set_data(data);mouseEvent->set_modifiers(modifiers);mouseEvent->set_rel_x(xRel);mouseEvent->set_rel_y(yRel);message->set_allocated_mouseevent(mouseEvent);// 通过 WebSocket 发送returnmControl->AsyncPostMessage(message);}

4.3 屏幕分辨率获取

关键问题：mCompressedPacketVideoWidth和mCompressedPacketVideoHeight在哪里设置？

解决方案：在视频解码循环中设置

// cloud_client.cc - VideoDecodeThread#ifdefined(OHOS)||defined(OHOS_PLATFORM)voidCloudClient::VideoDecodeThread(){while(!mStop){std::shared_ptr<cloudapp::Message>msg=mVideoPacketQueue.Pop();if(!msg)continue;autoframe=&msg->frame();// 关键：从视频帧中获取分辨率mCompressedPacketVideoWidth=frame->width();mCompressedPacketVideoHeight=frame->height();// 继续解码流程...}}#endif

为什么这里设置？

1. 视频帧携带了远程桌面的实际分辨率
2. 每次收到帧都会更新，支持动态分辨率变化
3. 确保触摸输入使用最新的屏幕尺寸

五、协议层：Protobuf 消息

5.1 消息定义

// message.proto message MouseEvent { required int32 x = 1; required int32 y = 2; required int32 button = 3; // buttonMask optional int32 data = 4; // 鼠标滚轮增量 optional int32 modifiers = 5; // Ctrl/Shift/Alt optional int32 rel_x = 6; // 相对移动 X optional int32 rel_y = 7; // 相对移动 Y } message Message { required Type type = 1; optional MouseEvent mouseevent = 10; } enum Type { kMouseEvent = 5; // 旧协议 kMouseEvent2 = 80; // 新协议（支持更多字段） }

5.2 协议版本选择

// 根据服务端版本选择协议if(dl::CompareVersion(mServerVersion,"2.22.0")<0){message->set_type(cloudapp::kMouseEvent);// 旧版本}else{message->set_type(cloudapp::kMouseEvent2);// 新版本}

5.3 序列化与发送

// control_client.ccboolControlClient::AsyncPostMessage(constMessagePtr&message){if(websocket_client_){// 序列化为二进制std::string bin=message->SerializeAsString();// 通过 WebSocket 发送websocket_client_->AsyncSendBin(bin);// 统计流量mSendBytes+=bin.size();LOGI("WS sent: type=%{public}d size=%{public}d",(int)message->type(),(int)bin.size());returntrue;}else{LOGE("WebSocket client is null");returnfalse;}}

六、常见问题与解决方案

6.1 触摸无响应

问题表现：触摸屏幕没有反应，服务端没有收到事件

排查步骤：

1. 检查 ArkTS 事件是否触发

   .onTouch((event:TouchEvent)=>{console.log('[Touch] Event type:',event.type)// 应该打印})

2. 检查 N-API 调用是否成功

   LOGI("SendPointerEvent called: x=%d y=%d",x,y);

3. 检查 WebSocket 连接状态

   if(!websocket_client_){LOGE("WebSocket not connected!");returnfalse;}

4. 检查控制权限

   if(mCurrentControlPrivilege!=cloudapp::kMain){LOGE("Not main controller!");returnfalse;}

6.2 坐标偏移问题

问题表现：触摸位置与实际响应位置不一致

可能原因：

1. 本地坐标转换错误

   // 错误：使用了错误的分辨率constx=localX*1920/1080// ❌ 宽高比错误// 正确constx=localX*remoteW/localW// ✅

2. 归一化坐标计算错误

   // 错误：整数除法截断finalX=x*65535/mCompressedPacketVideoWidth;// ❌// 正确：先乘后除，避免精度损失finalX=(x*65535)/mCompressedPacketVideoWidth;// ✅

3. 屏幕分辨率未正确获取

   // 检查日志LOGI("Screen size: %dx%d",mCompressedPacketVideoWidth,mCompressedPacketVideoHeight);// 应该是实际分辨率，不应该是 0x0

6.3 画线问题

问题表现：抬手后再按下，会从上次位置连一条线到新位置

原因：DOWN 和 UP 事件没有包含 MOVE 标志

解决方案：

// 错误caseTouchType.Down:buttonMask=0x8002// ❌ 只有 LEFTDOWN | ABSOLUTE// 正确caseTouchType.Down:buttonMask=0x8003// ✅ LEFTDOWN | MOVE | ABSOLUTE

原理：

• Windows SendInput 使用 ABSOLUTE 标志时，必须同时指定 MOVE
• 这样系统会先将鼠标移动到目标位置，再执行按下/抬起
• 否则鼠标会在"当前位置→目标位置"之间画线

6.4 HarmonyOS 日志过滤问题

问题表现：日志中的参数值显示为<private>

原因：HarmonyOS hilog 默认过滤隐私数据

解决方案：

// 错误LOGI("x=%d y=%d",x,y);// 显示为 x=<private> y=<private>// 正确：使用 {public} 标记LOGI("x=%{public}d y=%{public}d",x,y);// 显示实际值

适用场景：

• 调试坐标、尺寸等非敏感数据时使用
• 不要在生产环境打印敏感信息（即使使用 {public}）

七、性能优化

7.1 事件节流

触摸移动事件频率很高（60+ FPS），需要适当节流：

privatelastMoveTime:number=0privatemoveThrottleMs:number=16// 约 60 FPShandleTouch(event:TouchEvent){if(event.type===TouchType.Move){constnow=Date.now()if(now-this.lastMoveTime<this.moveThrottleMs){return// 跳过}this.lastMoveTime=now}// 处理事件...}

7.2 批量发送

对于高频事件，可以批量打包发送：

// 暂不实现，保留扩展性std::vector<cloudapp::MouseEvent>mEventBatch;if(mEventBatch.size()>=10){// 批量发送}

7.3 异步发送

// AsyncPostMessage 已经是异步的websocket_client_->AsyncSendBin(bin);// 不阻塞// 避免使用同步发送（会阻塞渲染线程）// SyncSendMessage(message); // ❌

八、Android 对比

Android 平台的触摸输入实现与 HarmonyOS 类似，但有一些差异：

特性	Android	HarmonyOS
触摸事件 API	View.onTouchEvent	XComponent.onTouch
Native 接口	JNI	N-API
坐标转换	Java 层	ArkTS 层
日志 API	__android_log_print	OH_LOG_INFO

共同点：

• 都需要三级坐标转换
• 都使用相同的 Windows SendInput 协议
• 都通过 WebSocket 发送 Protobuf 消息

九、总结

本文详细介绍了 HarmonyOS 触摸输入的完整实现：

1. ArkTS 层：捕获触摸事件，完成本地坐标到远程像素坐标的转换
2. N-API 层：封装接口，传递参数到 C++ 层
3. C++ 层：归一化坐标（像素→0-65535），序列化 Protobuf 消息
4. 协议层：通过 WebSocket 发送到服务端

关键技术点：

• 三级坐标转换：本地→远程像素→归一化
• MOUSEEVENTF 标志位的正确使用
• DOWN/UP 事件必须包含 MOVE 标志
• 屏幕分辨率的动态获取

常见问题：

• 触摸无响应：检查权限和连接状态
• 坐标偏移：检查转换公式和分辨率
• 画线问题：DOWN/UP 加上 MOVE 标志
• 日志过滤：使用 {public} 标记

下一篇预告：
下一篇将介绍内存管理与崩溃修复，包括 C++ 析构顺序问题、ASIO 异步回调的生命周期管理等内容。

---

作者：[Frame Not Work]
日期：2026年6月
系列文章：HarmonyOS 6.1 云应用客户端适配实战