React Native for OpenHarmony 三方库集成实战现场工具验证日期2026-09-26受测宿主RN能力库0.3.1一、应用背景现场巡检常需要三类轻量能力开始操作时给出触感反馈短时间打开手电筒照亮设备铭牌读取媒体音量判断提示音是否可能被用户听见。这些能力的资源边界不同触感是一次性动作手电筒占用摄像头硬件音量读取只能观察状态不能偷偷修改用户设置。因此页面流程应当是“触感确认 - 请求照明权限 - 打开手电筒 - 完成检查后关闭 - 读取音量”。手电筒无论流程成功、异常还是页面退出都必须进入关闭路径。图 1到场检查完成后界面显示触感已确认、照明已关闭和当前媒体音量。二、应用目标使用触感反馈确认用户已经开始现场操作将摄像头权限拒绝、设备没有闪光灯和开关失败分别反馈关闭照明后再读取媒体音量读取过程不改变系统音量防止重复点击和页面退出留下手电筒常亮。三、三方库与版本三方库锁定版本适配 TAG职责expo-haptics57.0.357.0.3-ohos-1.0.0触感确认react-native-torch1.2.01.2.0-ohos-1.0.0摄像头权限和手电筒开关react-native-volume-control1.0.11.0.1-ohos-1.0.0读取归一化媒体音量三个包均为 MIT 许可证的 OpenHarmony 交付包版本、仓库和 TAG 截止2026-09-26核对。运行时为 React Native0.84.1、RNOH0.84.3、OpenHarmony7.0.0.105。固定版本安装后执行npminstall./node_modules/.bin/react-native link-harmonycdharmonyohpminstall--allcd..npmrun bundle:harmony四、应用方式现场检查函数用try/finally保证手电筒关闭getVolume()返回0..1的归一化值只在展示层转成百分比import * as Haptics from expo-haptics; import Torch from react-native-torch; import VolumeControl from react-native-volume-control; function wait(milliseconds: number) { return new Promise(resolve setTimeout(resolve, milliseconds)); } export async function runFieldCheck() { await Haptics.notificationAsync( Haptics.NotificationFeedbackType.Success, ); const permission await Torch.requestCameraPermission( 现场工具, 用于执行短时照明检查, ); if (!permission) { return {status: permission-denied as const}; } let torchAttempted false; try { torchAttempted true; await Torch.switchState(true); await wait(650); const volume await VolumeControl.getVolume(); return { status: ok as const, torchClosed: true, volumePercent: Math.round(volume * 100), }; } finally { if (torchAttempted) { await Torch.switchState(false).catch(() undefined); } } }如果requestCameraPermission的实现版本返回的不是布尔值应以实际类型定义为准并把“拒绝”和“设备不支持”映射成不同的业务状态。不要在finally外另外写一条正常分支关闭逻辑否则异常分支很容易漏掉。五、工程实现用控制器串行化硬件操作。手电筒是单一硬件资源。用户连续点击“打开”和“关闭”时后发的意图不应被先发的慢 Promise 覆盖。控制器保存desiredState每个操作结束后重新收敛到最后一次意图typeTorchStateoff|turningOn|on|turningOff|error;exportclassTorchController{privatestate:TorchStateoff;privatedesired:on|offoff;privatesequence0;getState(){returnthis.state;}asyncsetDesired(next:on|off){this.desirednext;constsequencethis.sequence;this.statenexton?turningOn:turningOff;try{awaitTorch.switchState(nexton);if(sequence!this.sequence)return;this.statenext;if(this.desired!next)awaitthis.setDesired(this.desired);}catch(error){if(sequencethis.sequence)this.stateerror;throwerror;}}asyncdispose(){this.desiredoff;this.sequence;try{awaitTorch.switchState(false);this.stateoff;}catch(error){this.stateerror;throwerror;}}}页面失焦、应用进入后台、用户取消任务和组件卸载都调用dispose()。它不是取消原生 Promise而是保证硬件最终收到关闭请求。只读音量并校验范围。音量值应在读取层保留浮点数显示层才转成整数百分比。系统服务异常或返回NaN时不能把它当成0%typeVolumeResult|{status:ok;value:number;percent:number}|{status:unavailable;reason:string};exportasyncfunctionreadMediaVolume():PromiseVolumeResult{try{constvalueawaitVolumeControl.getVolume();if(!Number.isFinite(value)||value0||value1){return{status:unavailable,reason:invalid-volume};}return{status:ok,value,percent:Math.round(value*100)};}catch{return{status:unavailable,reason:volume-service-unavailable};}}本场景不调用VolumeControl.change()。如果其他功能确实需要修改音量必须记录原值在流程结束或取消时恢复并再次调用getVolume()核对恢复结果。手电筒请求还要设置超时。系统权限弹窗、摄像头资源争用或设备从后台恢复时Promise 可能很久才有结果页面不能无限保持“开启中”functionwithTimeoutT(task:PromiseT,timeoutMs:number):PromiseT{returnPromise.race([task,newPromiseT((_,reject){setTimeout(()reject(newError(torch-timeout)),timeoutMs);}),]);}asyncfunctionswitchTorchSafely(enabled:boolean){try{awaitwithTimeout(Torch.switchState(enabled),2_000);return{status:okasconst};}catch(error){return{status:errorasconst,code:errorinstanceofError?error.message:torch-error,};}}超时只结束业务等待不一定取消底层调用所以超时后仍要执行一次关闭并在下一次获得焦点时读取或探测真实状态。setTimeout计时器应在控制器销毁时清理避免页面离开后回调再次修改状态。把权限和硬件能力分成两条状态。permission可以是unknown、granted、deniedhardware可以是available、unavailable、busy。权限已授予但设备没有闪光灯时不能提示用户重复授权硬件忙时可以稍后重试typeFieldToolStatus{permission:unknown|granted|denied;hardware:available|unavailable|busy;torch:off|on|error;volume:number|null;};应用进入后台时将desired设置为off返回前台时不自动打开必须由用户重新触发。这样可以避免后台误占用摄像头也能让系统隐私指示和页面状态保持一致。现场任务还需要为每次操作建立上下文避免上一次巡检的状态被下一次任务复用。上下文包括设备或工单 ID、开始时间、是否已经申请权限和手电筒开关尝试次数typeFieldOperation{operationId:string;taskId:string;startedAt:number;permission:unknown|granted|denied;torchAttempted:boolean;volume:number|null;};functioncreateFieldOperation(taskId:string):FieldOperation{return{operationId:${taskId}-${Date.now()},taskId,startedAt:Date.now(),permission:unknown,torchAttempted:false,volume:null,};}用户看到的提示应由状态决定权限拒绝提供授权入口没有闪光灯允许跳过硬件忙提示稍后重试音量服务失败则显示“音量不可读取”不能把失败值显示为0%。状态变化写入操作日志时只记录operationId、错误码和耗时不记录摄像头帧或现场照片。控制器的dispose需要在测试中验证幂等性。重复调用不应发出相互冲突的开关序列关闭失败也不应阻止后续一次重试it(makes dispose idempotent,async(){constswitchStatejest.spyOn(Torch,switchState).mockResolvedValue();constcontrollernewTorchController();awaitcontroller.dispose();awaitcontroller.dispose();expect(switchState).toHaveBeenCalledWith(false);expect(controller.getState()).toBe(off);});如果项目还支持扫码、相机预览或录像手电筒控制器必须与这些功能共享硬件占用协调器。单个库的switchState(false)不能假设整个应用没有其他功能正在使用摄像头协调器应按资源所有者维护引用计数或明确的互斥锁。照明检查最好把固定等待改成可观察条件。示例中的650ms只是为了让演示页面留出观察时间正式流程可以等待手电筒状态回调或独立探针确认亮度达到阈值如果库没有状态事件则将固定时长限制在很短的 UI 反馈范围并把硬件释放放在finally中。不要因为等待时间变长就把手电筒当成后台资源。如果现场任务还要播放提示音提示音的音量读取应在手电筒关闭后进行并在页面上说明当前音量只用于判断可听性。音量不是扬声器健康度的证明设备静音、蓝牙路由和系统勿扰模式都可能导致实际听感不同必要时增加一次用户确认而不是自动判定现场通过。现场页面可以将三个能力的结果分别展示避免一项失败覆盖其他成功结果function FieldToolSummary({result}: {result: FieldToolStatus}) { return ( View Text accessibilityLabel触感反馈触感已发送/Text Text accessibilityLabel手电筒状态 手电筒{result.torch on ? 开启 : result.torch off ? 关闭 : 异常} /Text Text accessibilityLabel摄像头权限 权限{result.permission granted ? 已授权 : 未授权} /Text Text accessibilityLabel媒体音量 音量{result.volume null ? 不可读取 : ${Math.round(result.volume * 100)}%} /Text /View ); }当权限被拒绝时照明行显示授权操作音量行仍可以独立读取当音量服务不可用时手电筒关闭结果仍然可以作为巡检结论。业务提交应携带每项状态而不是只携带一个全局success布尔值。故障矩阵至少包含无闪光灯、首次授权拒绝、授权后系统回收、手电筒打开超时、音量 Promise 拒绝、应用进入后台和用户快速点击关闭。每个用例都要记录“最终手电筒状态”这是硬件资源类功能比普通 Toast 更重要的断言。清理逻辑最好独立成无 UI 依赖的函数便于在页面卸载、后台切换和异常捕获中复用asyncfunctionreleaseFieldResources(controller:TorchController){constresultsawaitPromise.allSettled([controller.dispose(),readMediaVolume(),]);return{torch:results[0].statusfulfilled?off:unknown,volume:results[1].statusfulfilled?results[1].value:null,}asconst;}这里的音量读取只作为结束记录不修改音量如果读取本身失败仍然不能把手电筒状态改写成成功。真机日志中分别记录释放结果和读取结果问题定位时先确认硬件状态再分析页面提示。只有在资源释放结果确认后页面才将本次操作标记为完成任何清理失败都进入可重试状态并保留任务 ID 供现场人员继续处理。这条规则适用于取消、返回和进程恢复不应只在“检查成功”按钮的正常路径执行。真机验收表中同时保留开关调用日志、页面状态和硬件探针结果三者一致后才记录为通过。这比单独截图更能证明清理路径真的执行。日志、页面和硬件结果必须使用同一个操作 ID。错误提示和测试边界。权限拒绝是可操作的用户问题应提示重新授权设备无闪光灯是能力缺失应允许跳过照明继续巡检开关 Promise 拒绝是系统或资源错误应进入错误状态并尝试关闭。三类错误不能都显示“现场检查失败”。单元测试验证业务层的开关序列不假设测试环境真的有闪光灯it(turns the torch off when a later check fails,async(){constcalls:boolean[][];jest.spyOn(Torch,switchState).mockImplementation(asyncnext{calls.push(next);});jest.spyOn(VolumeControl,getVolume).mockRejectedValue(newError(volume service unavailable),);awaitexpect(runFieldCheck()).rejects.toThrow(volume service unavailable);expect(calls).toEqual([true,false]);});真机再确认开关结果、权限弹窗和页面退出后的硬件状态。自动化通过不等于设备真的发光截图也不能证明退出后已经关闭必须在关闭动作后用独立探针或下一次开启前的状态检查进行交叉核对。六、真机验证验证项实测结果结论HAP 安装与启动RN能力库 0.3.1可启动通过触感反馈返回“中等强度反馈已触发”通过手电筒开启/关闭开启成功流程结束后关闭通过音量读取返回媒体音量50%未改变原值通过退出清理页面退出后照明保持关闭通过受测设备为6UMBB26319007180系统OpenHarmony-7.0.0.105HAP SHA-256a0f079982142ef5eb836f439af5e71c8f31f33c4988e80ab2a7575bee64b1f03。触感、手电筒、音量截图均来自同一受测 HAP测试结束后恢复了原音量。图 2expo-haptics真机触感反馈结果。图 3react-native-torch真机开启结果。图 4流程结束后react-native-torch真机关闭结果。图 5react-native-volume-control读取媒体音量结果。本次未覆盖无闪光灯设备、权限永久拒绝、来电或其他应用同时占用摄像头、后台服务继续持有手电筒等场景。正式接入时应增加故障注入和多设备回归且不能把测试时为观察方便设置的设备常亮状态当成应用功能。七、参考链接expo-hapticsreact-native-torchreact-native-volume-controlRN能力库欢迎加入 RN for OpenHarmony 社区。
React Native for OpenHarmony 三方库集成实战现场工具验证日期2026-09-26受测宿主RN能力库0.3.1一、应用背景现场巡检常需要三类轻量能力开始操作时给出触感反馈短时间打开手电筒照亮设备铭牌读取媒体音量判断提示音是否可能被用户听见。这些能力的资源边界不同触感是一次性动作手电筒占用摄像头硬件音量读取只能观察状态不能偷偷修改用户设置。因此页面流程应当是“触感确认 - 请求照明权限 - 打开手电筒 - 完成检查后关闭 - 读取音量”。手电筒无论流程成功、异常还是页面退出都必须进入关闭路径。图 1到场检查完成后界面显示触感已确认、照明已关闭和当前媒体音量。二、应用目标使用触感反馈确认用户已经开始现场操作将摄像头权限拒绝、设备没有闪光灯和开关失败分别反馈关闭照明后再读取媒体音量读取过程不改变系统音量防止重复点击和页面退出留下手电筒常亮。三、三方库与版本三方库锁定版本适配 TAG职责expo-haptics57.0.357.0.3-ohos-1.0.0触感确认react-native-torch1.2.01.2.0-ohos-1.0.0摄像头权限和手电筒开关react-native-volume-control1.0.11.0.1-ohos-1.0.0读取归一化媒体音量三个包均为 MIT 许可证的 OpenHarmony 交付包版本、仓库和 TAG 截止2026-09-26核对。运行时为 React Native0.84.1、RNOH0.84.3、OpenHarmony7.0.0.105。固定版本安装后执行npminstall./node_modules/.bin/react-native link-harmonycdharmonyohpminstall--allcd..npmrun bundle:harmony四、应用方式现场检查函数用try/finally保证手电筒关闭getVolume()返回0..1的归一化值只在展示层转成百分比import * as Haptics from expo-haptics; import Torch from react-native-torch; import VolumeControl from react-native-volume-control; function wait(milliseconds: number) { return new Promise(resolve setTimeout(resolve, milliseconds)); } export async function runFieldCheck() { await Haptics.notificationAsync( Haptics.NotificationFeedbackType.Success, ); const permission await Torch.requestCameraPermission( 现场工具, 用于执行短时照明检查, ); if (!permission) { return {status: permission-denied as const}; } let torchAttempted false; try { torchAttempted true; await Torch.switchState(true); await wait(650); const volume await VolumeControl.getVolume(); return { status: ok as const, torchClosed: true, volumePercent: Math.round(volume * 100), }; } finally { if (torchAttempted) { await Torch.switchState(false).catch(() undefined); } } }如果requestCameraPermission的实现版本返回的不是布尔值应以实际类型定义为准并把“拒绝”和“设备不支持”映射成不同的业务状态。不要在finally外另外写一条正常分支关闭逻辑否则异常分支很容易漏掉。五、工程实现用控制器串行化硬件操作。手电筒是单一硬件资源。用户连续点击“打开”和“关闭”时后发的意图不应被先发的慢 Promise 覆盖。控制器保存desiredState每个操作结束后重新收敛到最后一次意图typeTorchStateoff|turningOn|on|turningOff|error;exportclassTorchController{privatestate:TorchStateoff;privatedesired:on|offoff;privatesequence0;getState(){returnthis.state;}asyncsetDesired(next:on|off){this.desirednext;constsequencethis.sequence;this.statenexton?turningOn:turningOff;try{awaitTorch.switchState(nexton);if(sequence!this.sequence)return;this.statenext;if(this.desired!next)awaitthis.setDesired(this.desired);}catch(error){if(sequencethis.sequence)this.stateerror;throwerror;}}asyncdispose(){this.desiredoff;this.sequence;try{awaitTorch.switchState(false);this.stateoff;}catch(error){this.stateerror;throwerror;}}}页面失焦、应用进入后台、用户取消任务和组件卸载都调用dispose()。它不是取消原生 Promise而是保证硬件最终收到关闭请求。只读音量并校验范围。音量值应在读取层保留浮点数显示层才转成整数百分比。系统服务异常或返回NaN时不能把它当成0%typeVolumeResult|{status:ok;value:number;percent:number}|{status:unavailable;reason:string};exportasyncfunctionreadMediaVolume():PromiseVolumeResult{try{constvalueawaitVolumeControl.getVolume();if(!Number.isFinite(value)||value0||value1){return{status:unavailable,reason:invalid-volume};}return{status:ok,value,percent:Math.round(value*100)};}catch{return{status:unavailable,reason:volume-service-unavailable};}}本场景不调用VolumeControl.change()。如果其他功能确实需要修改音量必须记录原值在流程结束或取消时恢复并再次调用getVolume()核对恢复结果。手电筒请求还要设置超时。系统权限弹窗、摄像头资源争用或设备从后台恢复时Promise 可能很久才有结果页面不能无限保持“开启中”functionwithTimeoutT(task:PromiseT,timeoutMs:number):PromiseT{returnPromise.race([task,newPromiseT((_,reject){setTimeout(()reject(newError(torch-timeout)),timeoutMs);}),]);}asyncfunctionswitchTorchSafely(enabled:boolean){try{awaitwithTimeout(Torch.switchState(enabled),2_000);return{status:okasconst};}catch(error){return{status:errorasconst,code:errorinstanceofError?error.message:torch-error,};}}超时只结束业务等待不一定取消底层调用所以超时后仍要执行一次关闭并在下一次获得焦点时读取或探测真实状态。setTimeout计时器应在控制器销毁时清理避免页面离开后回调再次修改状态。把权限和硬件能力分成两条状态。permission可以是unknown、granted、deniedhardware可以是available、unavailable、busy。权限已授予但设备没有闪光灯时不能提示用户重复授权硬件忙时可以稍后重试typeFieldToolStatus{permission:unknown|granted|denied;hardware:available|unavailable|busy;torch:off|on|error;volume:number|null;};应用进入后台时将desired设置为off返回前台时不自动打开必须由用户重新触发。这样可以避免后台误占用摄像头也能让系统隐私指示和页面状态保持一致。现场任务还需要为每次操作建立上下文避免上一次巡检的状态被下一次任务复用。上下文包括设备或工单 ID、开始时间、是否已经申请权限和手电筒开关尝试次数typeFieldOperation{operationId:string;taskId:string;startedAt:number;permission:unknown|granted|denied;torchAttempted:boolean;volume:number|null;};functioncreateFieldOperation(taskId:string):FieldOperation{return{operationId:${taskId}-${Date.now()},taskId,startedAt:Date.now(),permission:unknown,torchAttempted:false,volume:null,};}用户看到的提示应由状态决定权限拒绝提供授权入口没有闪光灯允许跳过硬件忙提示稍后重试音量服务失败则显示“音量不可读取”不能把失败值显示为0%。状态变化写入操作日志时只记录operationId、错误码和耗时不记录摄像头帧或现场照片。控制器的dispose需要在测试中验证幂等性。重复调用不应发出相互冲突的开关序列关闭失败也不应阻止后续一次重试it(makes dispose idempotent,async(){constswitchStatejest.spyOn(Torch,switchState).mockResolvedValue();constcontrollernewTorchController();awaitcontroller.dispose();awaitcontroller.dispose();expect(switchState).toHaveBeenCalledWith(false);expect(controller.getState()).toBe(off);});如果项目还支持扫码、相机预览或录像手电筒控制器必须与这些功能共享硬件占用协调器。单个库的switchState(false)不能假设整个应用没有其他功能正在使用摄像头协调器应按资源所有者维护引用计数或明确的互斥锁。照明检查最好把固定等待改成可观察条件。示例中的650ms只是为了让演示页面留出观察时间正式流程可以等待手电筒状态回调或独立探针确认亮度达到阈值如果库没有状态事件则将固定时长限制在很短的 UI 反馈范围并把硬件释放放在finally中。不要因为等待时间变长就把手电筒当成后台资源。如果现场任务还要播放提示音提示音的音量读取应在手电筒关闭后进行并在页面上说明当前音量只用于判断可听性。音量不是扬声器健康度的证明设备静音、蓝牙路由和系统勿扰模式都可能导致实际听感不同必要时增加一次用户确认而不是自动判定现场通过。现场页面可以将三个能力的结果分别展示避免一项失败覆盖其他成功结果function FieldToolSummary({result}: {result: FieldToolStatus}) { return ( View Text accessibilityLabel触感反馈触感已发送/Text Text accessibilityLabel手电筒状态 手电筒{result.torch on ? 开启 : result.torch off ? 关闭 : 异常} /Text Text accessibilityLabel摄像头权限 权限{result.permission granted ? 已授权 : 未授权} /Text Text accessibilityLabel媒体音量 音量{result.volume null ? 不可读取 : ${Math.round(result.volume * 100)}%} /Text /View ); }当权限被拒绝时照明行显示授权操作音量行仍可以独立读取当音量服务不可用时手电筒关闭结果仍然可以作为巡检结论。业务提交应携带每项状态而不是只携带一个全局success布尔值。故障矩阵至少包含无闪光灯、首次授权拒绝、授权后系统回收、手电筒打开超时、音量 Promise 拒绝、应用进入后台和用户快速点击关闭。每个用例都要记录“最终手电筒状态”这是硬件资源类功能比普通 Toast 更重要的断言。清理逻辑最好独立成无 UI 依赖的函数便于在页面卸载、后台切换和异常捕获中复用asyncfunctionreleaseFieldResources(controller:TorchController){constresultsawaitPromise.allSettled([controller.dispose(),readMediaVolume(),]);return{torch:results[0].statusfulfilled?off:unknown,volume:results[1].statusfulfilled?results[1].value:null,}asconst;}这里的音量读取只作为结束记录不修改音量如果读取本身失败仍然不能把手电筒状态改写成成功。真机日志中分别记录释放结果和读取结果问题定位时先确认硬件状态再分析页面提示。只有在资源释放结果确认后页面才将本次操作标记为完成任何清理失败都进入可重试状态并保留任务 ID 供现场人员继续处理。这条规则适用于取消、返回和进程恢复不应只在“检查成功”按钮的正常路径执行。真机验收表中同时保留开关调用日志、页面状态和硬件探针结果三者一致后才记录为通过。这比单独截图更能证明清理路径真的执行。日志、页面和硬件结果必须使用同一个操作 ID。错误提示和测试边界。权限拒绝是可操作的用户问题应提示重新授权设备无闪光灯是能力缺失应允许跳过照明继续巡检开关 Promise 拒绝是系统或资源错误应进入错误状态并尝试关闭。三类错误不能都显示“现场检查失败”。单元测试验证业务层的开关序列不假设测试环境真的有闪光灯it(turns the torch off when a later check fails,async(){constcalls:boolean[][];jest.spyOn(Torch,switchState).mockImplementation(asyncnext{calls.push(next);});jest.spyOn(VolumeControl,getVolume).mockRejectedValue(newError(volume service unavailable),);awaitexpect(runFieldCheck()).rejects.toThrow(volume service unavailable);expect(calls).toEqual([true,false]);});真机再确认开关结果、权限弹窗和页面退出后的硬件状态。自动化通过不等于设备真的发光截图也不能证明退出后已经关闭必须在关闭动作后用独立探针或下一次开启前的状态检查进行交叉核对。六、真机验证验证项实测结果结论HAP 安装与启动RN能力库 0.3.1可启动通过触感反馈返回“中等强度反馈已触发”通过手电筒开启/关闭开启成功流程结束后关闭通过音量读取返回媒体音量50%未改变原值通过退出清理页面退出后照明保持关闭通过受测设备为6UMBB26319007180系统OpenHarmony-7.0.0.105HAP SHA-256a0f079982142ef5eb836f439af5e71c8f31f33c4988e80ab2a7575bee64b1f03。触感、手电筒、音量截图均来自同一受测 HAP测试结束后恢复了原音量。图 2expo-haptics真机触感反馈结果。图 3react-native-torch真机开启结果。图 4流程结束后react-native-torch真机关闭结果。图 5react-native-volume-control读取媒体音量结果。本次未覆盖无闪光灯设备、权限永久拒绝、来电或其他应用同时占用摄像头、后台服务继续持有手电筒等场景。正式接入时应增加故障注入和多设备回归且不能把测试时为观察方便设置的设备常亮状态当成应用功能。七、参考链接expo-hapticsreact-native-torchreact-native-volume-controlRN能力库欢迎加入 RN for OpenHarmony 社区。
方法的正确使用技巧)
![[特殊字符] 小橡皮 AI｜新媒体文案工具，一键去除 AI 痕迹 + 稿件风控检测](http://pic.xiahunao.cn/yaotu/[特殊字符] 小橡皮 AI｜新媒体文案工具，一键去除 AI 痕迹 + 稿件风控检测)
