HarmonyOS技术精讲-Connectivity Kit实战——多屏协同与文件快传应用从“能用”到“好用”跨设备通信的坑与解HarmonyOS NEXT 的分布式能力最吸引人的地方就是设备间协同。但很多人第一次接触 Connectivity Kit 时会发现官方示例能跑但一放到实际项目里就会遇到各种问题投屏突然断开、文件发送卡住不动、进度条不动、甚至设备都发现不了。这些问题本质不是 API 不会用而是生命周期管理和状态同步没处理好。这篇文章会从头搭建一个“多屏协同 文件快传”的完整应用把分布式屏幕、Wi-Fi P2P、蓝牙 BLE 这三块能力整合到一起重点讲清楚到底有哪些坑需要绕开。这个应用解决了什么问题首先得说清楚为什么要自己写而不是直接用 HarmonyOS 自带的“多设备协同”方案优点缺点系统自带的“多设备协同”无开发成本交互统一高度黑盒无法定制 UI 和传输策略使用 Connectivity Kit 自建完全可控可自定义文件传输进度、UI、策略需要处理生命周期的细节需要解决设备发现和连接稳定性问题第三方方案如自建局域网传输跨平台无法利用 HarmonyOS 的分布式软总线优势延迟高推荐在以下场景自建应用需要在特定应用内实现多屏协作而不是系统级别的屏幕镜像需要实时回传文件传输进度、压缩质量、速度限制需要同时支持多个设备在同一应用内进行不同类型的传输比如一个投屏一个传文件不适合的场景只做一次性的屏幕镜像不需要控制传输细节不需要跨设备拖拽文件环境说明DevEco Studio 版本DevEco Studio 6.1.0 及以上 HarmonyOS SDK 版本HarmonyOS 6.1.0(23) 及以上 目标设备手机 平板均需支持分布式软总线注意模拟器不支持分布式屏幕和 Wi-Fi P2P必须真机。架构设计整个应用分为两层协同层负责设备发现蓝牙 BLE 分布式软总线、设备连接管理、分布式屏幕投射传输层负责 Wi-Fi P2P 的设备连接、文件流的发送与接收、进度上报核心实现第一步设备发现与连接设备发现是首要前提。我们采用蓝牙 BLE 广播 分布式软总线双通道发现策略蓝牙 BLE用于发现附近的设备触发连接请求分布式软总线用于建立稳定的数据通道和控制通道蓝牙 BLE 设备发现这一部分主要在 Service 中进行避免在页面销毁后扫描中断。// BleDiscoverService.etsimport{ble}fromkit.ConnectivityKit;exportclassBleDiscoverService{publiconDeviceFound:(deviceId:string,deviceName:string)void(){};privatescanId:number0;privatediscoveredDevices:Mapstring,stringnewMap();asyncstartScan():Promisevoid{// 每次扫描前先清空缓存避免重复回调this.discoveredDevices.clear();// HarmonyOS BLE 扫描需要指定 Service UUID 过滤器constfilters:ble.BleScanFilter[][{serviceUuid:00001800-0000-1000-8000-00805F9B34FB// 示例服务UUID请替换为实际}];constscanOptions:ble.BleScanOptions{interval:100,// 扫描间隔单位msdutyMode:ble.ScanDutyMode.SCAN_MODE_LOW_POWER};try{this.scanIdble.BLE.createScan(filters,scanOptions);ble.BLE.startScan(this.scanId,(err,data){if(err){console.error(BleDiscoverService: scan failed,${err.code},${err.message});return;}if(data){data.forEach(device{constdeviceIddevice.deviceId;constdeviceNamedevice.deviceName||未知设备;// 避免重复触发排除已发现的设备if(!this.discoveredDevices.has(deviceId)){this.discoveredDevices.set(deviceId,deviceName);this.onDeviceFound(deviceId,deviceName);}});}});}catch(error){console.error(BleDiscoverService: startScan error,${error});}}stopScan():void{if(this.scanId0){try{ble.BLE.stopScan(this.scanId);ble.BLE.destroyScan(this.scanId);}catch(error){console.error(BleDiscoverService: stopScan error,${error});}}}}关键点BleScanFilter里必须填真实的 Service UUID否则扫描不到任何设备onDeviceFound回调在开发者模式下会比较频繁但实际设备上间隔会大一些不要依赖快速连续回调destroyScan容易被遗忘但不调用会导致内存泄漏分布式软总线设备发现蓝牙 BLE 仅做“发现”用实际的数据通道需要走分布式软总线。我们在发现 BLE 设备后通过deviceManager去连接。// DeviceConnectionService.etsimport{deviceManager}fromkit.DistributedServiceKit;exportclassDeviceConnectionService{privatedevManager:deviceManager.DeviceManager|nullnull;publiconDeviceStatusChanged:(deviceId:string,online:boolean)void(){};asyncinit():Promisevoid{try{this.devManagerdeviceManager.createDeviceManager(com.example.multiscreen);// 注意回调必须在 createDeviceManager 之后立即注册否则可能丢失this.devManager.on(deviceOnline,(data){this.onDeviceStatusChanged(data.deviceId,true);});this.devManager.on(deviceOffline,(data){this.onDeviceStatusChanged(data.deviceId,false);});}catch(error){console.error(DeviceConnectionService: init failed,${error});}}getTrustedDeviceList():deviceManager.DeviceInfo[]{if(this.devManager){returnthis.devManager.getTrustedDeviceListSync();}return[];}release():void{// 必须取消注册所有监听否则页面销毁后回调仍会触发if(this.devManager){this.devManager.off(deviceOnline);this.devManager.off(deviceOffline);deviceManager.releaseDeviceManager(this.devManager);this.devManagernull;}}}注意createDeviceManager的bundleName必须和应用的App 包名一致不是 module 名否则会报错回调注册必须在createDeviceManager之后立即进行不要在异步回调里再注册否则可能在注册之前就丢失了设备事件getTrustedDeviceListSync返回的列表需要进行权限判断不是所有在线设备都可以直接连接第二步分布式屏幕投射当两个设备通过分布式软总线建立连接后就可以启动屏幕投射了。我们使用screenCaptureAPI 和分布式RemoteWindow来实现。这里需要明确不是通过“投屏”的系统能力而是通过创建远程窗口的方式。创建远程窗口// ScreenProjectionManager.etsimport{window}fromkit.ArkUI;import{BusinessError}fromkit.BasicServicesKit;exportclassScreenProjectionManager{privatelocalWindow:window.Window|nullnull;privateremoteWindow:window.Window|nullnull;asyncstartProjection(targetDeviceId:string,localWindowStage:window.WindowStage):Promisevoid{try{// 1. 获取当前应用的本地窗口用于后续创建 MirrorWindowthis.localWindowawaitlocalWindowStage.getMainWindow();// 2. 创建远程窗口指向目标设备的窗口管理器// 注意这里直接使用分布式窗口 API不属于 Connectivity Kit但属于分布式能力this.remoteWindowawaitwindow.Window.createWindow(remoteScreen,window.WindowType.TYPE_FLOAT,window.WindowMode.MODE_FLOATING,{displayId:0,deviceId:targetDeviceId}// 指定目标设备);// 3. 绑定本地窗口的内容到远程窗口// 实际上是创建一个新的 Surface将本地窗口渲染内容同步过去awaitthis.remoteWindow.bindWindow(this.localWindow);// 4. 显示远程窗口并根据需求调整布局awaitthis.remoteWindow.showWindow();awaitthis.remoteWindow.resize(500,400);// 设置尺寸awaitthis.remoteWindow.moveWindowTo(100,100);// 在目标设备上的位置}catch(error){console.error(ScreenProjectionManager: start failed,${error});throwerror;}}asyncstopProjection():Promisevoid{try{if(this.remoteWindow){awaitthis.remoteWindow.hideWindow();awaitthis.remoteWindow.destroyWindow();this.remoteWindownull;}this.localWindownull;}catch(error){console.error(ScreenProjectionManager: stop failed,${error});}}release():void{this.stopProjection();}}问题点window.Window.createWindow的第三个参数deviceId是必须的如果传空字符串会在本设备创建而不是远程设备bindWindow只支持绑定到TYPE_FLOAT类型的窗口如果类型不对会报错在目标设备上远程窗口的移动和缩放需要权限有些设备可能不支持第三步Wi-Fi P2P 文件传输屏幕投射搞定后文件传输我们需要一个高速、低延迟的通道。这里选择Wi-Fi P2P而不是蓝牙因为文件体积通常较大几十 MB 到几百 MB蓝牙速度不够。P2P 连接// WifiP2pManager.etsimport{wifiManager}fromkit.ConnectivityKit;exportclassWifiP2pManager{publiconConnectionChanged:(connected:boolean,groupOwner:boolean)void(){};privatep2pListener:number0;asyncstartDiscovery():Promisevoid{try{// 先注册 P2P 状态监听否则可能错过连接事件this.p2pListenerwifiManager.on(p2pConnectionChanged,(data){if(data){constisConnecteddata.isGroupOwner!null;// 代表已有连接this.onConnectionChanged(isConnected,data.isGroupOwner);}});}catch(error){console.error(WifiP2pManager: startDiscovery error,${error});}}asyncconnectToDevice(deviceMac:string):Promisevoid{try{constconfig:wifiManager.WifiP2PConfig{deviceMacAddress:deviceMac,netRole:wifiManager.P2pNetRole.GO,// 设置为 GO 端作为服务器groupOwnerIntent:7// 优先为 GO};awaitwifiManager.p2pConnect(config);}catch(error){console.error(WifiP2pManager: connectToDevice error,${error});}}asyncdisconnectAll():Promisevoid{try{if(this.p2pListener0){wifiManager.off(p2pConnectionChanged,this.p2pListener);}awaitwifiManager.p2pCancelConnect();}catch(error){console.error(WifiP2pManager: disconnectAll error,${error});}}}关键点netRole的配置需要两个设备协商好。我们这里约定发送端为 GO接收端为 GCgroupOwnerIntent越高越有可能成为 Group Owner但两个设备都设为 15 会导致冲突连接成功后需要获取 GO 的 IP 地址然后通过 Socket 直接传输。这部分不在 Connectivity Kit 范围内但需要配合使用文件发送流实现发送端// FileSender.etsimport{socket}fromkit.NetworkKit;import{fileIo}fromkit.CoreFileKit;exportclassFileSender{privatetcpSocket:socket.TCPSocket|nullnull;privateisSending:booleanfalse;asyncsendFile(serverIp:string,serverPort:number,fileUri:string,onProgress:(sentBytes:number,totalBytes:number)void):Promisevoid{if(this.isSending){console.warn(FileSender: already sending);return;}this.isSendingtrue;try{// 1. 创建 TCP SocketconstnetAddress:socket.NetAddress{address:serverIp,port:serverPort,family:1// IPv4};this.tcpSocketsocket.constructTCPSocketInstance();awaitthis.tcpSocket.connect(netAddress);// 2. 打开文件constfileawaitfileIo.open(fileUri,fileIo.OpenMode.READ_ONLY);constfileSizefileIo.statSync(fileUri).size;// 3. 发送文件头信息文件名、大小constheaderJSON.stringify({fileName:fileUri.split(/).pop()||unknown,fileSize:fileSize});constheaderBytesnewTextEncoder().encode(header);// 先发送头部长度4 字节小端序再发送头部内容constheaderLenBuffernewArrayBuffer(4);newDataView(headerLenBuffer).setUint32(0,headerBytes.byteLength,true);awaitthis.tcpSocket.send({data:headerLenBuffer});awaitthis.tcpSocket.send({data:headerBytes.buffer});// 4. 分块发送文件内容constchunkSize1024*1024;// 1MB 块lettotalSent0;constbuffernewArrayBuffer(chunkSize);while(totalSentfileSize){constbytesReadawaitfileIo.read(file.fd,buffer,{offset:totalSent,length:chunkSize});if(bytesRead0)break;constchunkbuffer.slice(0,bytesRead);// 大文件发送时需要加上超时处理避免单次 send 一直卡住awaitthis.tcpSocket.send({data:chunk});totalSentbytesRead;onProgress(totalSent,fileSize);}// 5. 关闭文件和 SocketawaitfileIo.close(file);awaitthis.tcpSocket.close();this.tcpSocketnull;}catch(error){console.error(FileSender: sendFile error,${error});throwerror;}finally{this.isSendingfalse;}}abort():void{if(this.tcpSocket){// 直接关闭会抛出异常但上层可以通过异常判断中止this.tcpSocket.close();this.tcpSocketnull;}this.isSendingfalse;}}如何实现进度条 UI进度条显示依赖于一个State变量progress由文件发送的回调更新。需要注意的是不要在回调里直接 setState因为回调可能在 I/O 线程触发。ArkUI 的 UI 更新必须在主线程进行。// 在页面组件中import{taskpool}fromkit.ArkTS;// 使用 taskpool 确保回调在 UI 主线程执行fileSender.sendFile(ip,port,fileUri,(sent,total){taskpool.executeOnMainThread((){this.sendProgresssent/total;});});踩坑记录坑 1分布式屏幕投影时目标设备闪退现象调用bindWindow后目标设备上的应用直接无响应或闪退。原因bindWindow在绑定后会在目标设备上创建一个新的 Surface这个 Surface 需要从localWindow获取渲染流。如果本地应用处于后台或者被系统回收绑定就会断开导致目标设备上的窗口崩溃。解决方案保持本地应用在前台在投屏期间禁止应用切到后台或者在onForeground/onBackground生命周期里控制投屏的启停。监控绑定状态注册远程窗口的windowEvent监听在目标设备窗口销毁时主动断开绑定。使用softbusAPI 替代如果bindWindow不稳定可以改用softbusSDK 手动同步屏幕数据但开发成本高很多。坑 2Wi-Fi P2P 连接成功后Socket 发送文件时超时现象文件发送到某个大文件100MB时send方法无响应超时后抛出异常。原因TCPSocket.send如果发送缓冲区满了会阻塞等待对方接收。接收端如果没有及时读取缓冲区发送端就会卡住。主要原因是接收端处理不当或者网络抖动。解决方案发送端设置 Socket 超时this.tcpSocket.setExtraOptions({sendTimeout:10000// 10s 超时});接收端必须使用异步 I/O且不要在主线程处理用TaskPool或worker处理文件写入。增加拥塞控制在发送循环里加入await delay(10)让出资源。awaitnewPromise(resolvesetTimeout(resolve,10));坑 3蓝牙 BLE 在升级到 API 12 后扫描回调不触发现象代码完全按照官方文档写但startScan的回调一次也不触发。原因API 12 起BleScanFilter里的serviceUuid不再是可选参数。如果filters数组为空数组扫描不会启动。另外需要检查是否申请了ohos.permission.USE_BLUETOOTH和ohos.permission.BLUETOOTH_SCAN权限。解决方案filters必须包含至少一个有效 Service UUID检查module.json5中的权限声明是否齐全最佳实践1. 不要把服务实例绑定在页面组件的生命周期上很多人的做法是在Component里new一个BleDiscoverService然后在aboutToDisappear里释放。问题在于当用户切到其他页面再返回时服务实例已经消失了。推荐改成在应用级AppStorage或singleton管理服务实例。2. 使用ObjectLink处理跨页面状态同步文件传输进度、设备列表这些数据如果在多个页面都需要展示不要在每个组件的State里缓存。用Observed定义状态类然后用ObjectLink引用。这样更新一次所有组件都刷新。3. 资源释放的“三保险”对于网络连接、Service 注册、扫描提倡在以下三个地方都做释放页面aboutToDisappear应用onDestroy组件disconnectTimer或错误回调里因为 HarmonyOS 的生命周期在某些场景下如直接杀进程可能不会完整执行所以需要多一层保护。
