相机预览黑屏经常发生在“重新进入页面”而不是首次启动。上一会话没有按顺序释放新的输入流已经创建旧Surface仍被引用最终所有对象看起来都存在预览却没有帧。恢复逻辑必须由资源栈驱动。方案面向HarmonyOS 6.1.1 Release SDKAPI 24系统Kit调用进入适配层命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。把相机对象画成资源栈资源栈从CameraManager开始依次包含CameraInput、PreviewOutput、PhotoOutput和CaptureSession。只有输入输出全部添加并完成commitConfig才允许start。页面退出按Session、输出流、输入流的逆序释放每一步都幂等。状态数量不是越多越好。每个状态必须回答三个问题当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId新的操作开始后旧操作回调会被拒绝。export enum CameraSessionState { NO_PERMISSION no_permission, DISCOVERING discovering, CONFIGURING configuring, PREVIEWING previewing, CAPTURING capturing, RELEASING releasing } export interface CameraSessionSnapshot { state: CameraSessionState; progress: number; message: string; operationId: number; updatedAt: number; } export type CameraSessionEvent | { type: START; operationId: number } | { type: PROGRESS; operationId: number; progress: number } | { type: SUCCESS; operationId: number } | { type: FAIL; operationId: number; message: string }; export function acceptEvent( snapshot: CameraSessionSnapshot, event: CameraSessionEvent ): boolean { return event.type START || event.operationId snapshot.operationId; }设计对象保存内容不应该保存的内容页面状态可展示阶段、进度、错误摘要系统对象和页面Context适配器Kit实例、监听注册、资源句柄ArkUI组件引用业务记录operationId、版本、恢复点未脱敏的敏感原始数据诊断信息阶段耗时、错误码、能力检测Token、图片原始内容创建顺序和释放顺序正好相反XComponent生成新的surfaceId时递增surfaceVersion任何针对旧版本创建的PreviewOutput都必须关闭。相机被占用进入WAITING不使用零间隔循环重试用户点击重试或收到设备可用事件后再重新建栈。没有权限时展示授权解释和相册导入入口。这套分层把系统事实和产品行为分开Kit适配器负责获得事实领域对象决定是否接受事件页面只渲染快照。更换API版本或加入真机能力时只需要替换适配器状态归并和异常策略仍可在模拟器中重复验证。Surface变化必须让旧输出失效下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑因为高频故障往往出现在成功调用之外。import { camera } from kit.CameraKit; import { common } from kit.AbilityKit; export class CameraResourceStack { private manager?: camera.CameraManager; private input?: camera.CameraInput; private session?: camera.PhotoSession; private preview?: camera.PreviewOutput; async open(context: common.BaseContext, surfaceId: string): Promisevoid { this.manager camera.getCameraManager(context); const devices this.manager.getSupportedCameras(); if (devices.length 0) throw new Error(NO_CAMERA); this.input this.manager.createCameraInput(devices[0]); await this.input.open(); const capability this.manager.getSupportedOutputCapability(devices[0], camera.SceneMode.NORMAL_PHOTO); const profile capability.previewProfiles[0]; this.preview this.manager.createPreviewOutput(profile, surfaceId); this.session this.manager.createSession(camera.SceneMode.NORMAL_PHOTO) as camera.PhotoSession; this.session.beginConfig(); this.session.addInput(this.input); this.session.addOutput(this.preview); await this.session.commitConfig(); await this.session.start(); } async close(): Promisevoid { await this.session?.stop(); this.session?.release(); this.preview?.release(); await this.input?.close(); } }代码迁入业务工程时应把错误码转换为稳定的领域错误不让页面直接判断系统错误字符串。对于异步回调还要在写入状态前比较operationId或资源版本仅检查组件是否存在无法阻止旧任务污染新页面。相机被占用时不要循环重试故障输入状态变化恢复动作没有相机权限停在NO_PERMISSION保留相册入口设备被占用进入WAITING用户触发重试Surface已变化释放旧PreviewOutput按新版本重建页面快速返回close幂等不重复释放抛错异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时诊断记录同时保存错误码、权限结果、设备能力和用户可见状态敏感原始数据不进入日志截图只呈现与问题直接相关的结果。权限拒绝后的页面仍要可用页面层不直接调用Kit而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。Component struct CameraSessionPanel { State stateText: string NO_PERMISSION; State progress: number 0; State logs: string[] []; private append(message: string): void { const time new Date().toLocaleTimeString(); this.logs [${time} ${message}, ...this.logs].slice(0, 8); } private startDemo(): void { this.stateText DISCOVERING; this.progress 20; this.append(开始Camera Kit拍摄会话恢复); } private injectFailure(): void { this.stateText RELEASING; this.append(已注入可恢复故障); } build() { Column({ space: 12 }) { Text(Camera Kit拍摄会话恢复).fontSize(24).fontWeight(FontWeight.Bold) Text(this.stateText).fontSize(18).fontColor(#2563EB) Progress({ value: this.progress, total: 100 }).width(100%) Row({ space: 12 }) { Button(开始实验).onClick(() this.startDemo()) Button(注入故障).onClick(() this.injectFailure()) } ForEach(this.logs, (item: string) Text(item).fontSize(13)) }.padding(20).width(100%) } }在模拟器有虚拟相机时执行预览、拍摄、返回和再次进入没有虚拟相机时验证权限、资源栈和NO_CAMERA降级不声称预览已通过。连续进出三次后资源审计面板中的活动Session和Input都应回到零。相机恢复不能把所有异常都处理成重新open。权限撤回需要回到授权说明设备断开需要重新发现摄像头Surface销毁只需要重建输出链相机服务异常才考虑重建完整资源栈。每次恢复前先等待上一轮close完成并给资源栈分配sessionVersion。照片回调到达时还要核对版本防止上一会话拍摄结果插入当前预览。资源审计显示创建和释放次数能够快速发现只退出一次就累积一个Input的泄漏。切换前后摄像头时先冻结交互按钮直到新会话首帧出现避免用户在两个资源栈交替阶段再次触发拍摄。连续拍摄测试还要覆盖锁屏、横竖屏切换和系统相机抢占分别核对预览恢复时间及资源计数是否回到基线。验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项涉及资源的主题还要显示活动对象计数涉及异步任务的主题要验证迟到结果不会改变当前页面。三次进出页面的资源审计这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象适配器不直接操作页面异常路径有明确的恢复动作后续SDK升级时可以分别回归每一层。官方资料CameraKit相关开发文档
