图片增强完成后，最先冒出来的按钮通常是“保存到相册”。但按钮后面还有一个需要设计的边界：用户正在看的是哪一张原图、哪些增强文件属于这次编辑、当前的保存动作准备覆盖原图还是另存为新图。如果这几个关系没有锁住，一次回调迟到就可能把上一张图片的增强结果提交到新一张图片的上下文。
本文使用AlbumSafeExport做一个明确标注为演示的导出流程。输入IMG_0924.JPG是用户在 PhotoPicker 中选择的来源，增强样本enhanced_0924.jpg已由演示程序放入应用沙箱；原图尺寸1280×960，增强样本2560×1920。这里不运行超分模型，也不宣称模型质量。我们只讨论完成编辑后的预览绑定、保存意图与失败恢复。任务固定为SAVE-1010-10。
一、从失败分支入手，而不是先展示一张成功照片
假设用户已经在 PhotoPicker 上看见增强图，点下“另存为新图”后，保存回调却报错。此时产品能证明的是什么？它只能说发起了保存操作，不能说图库里一定没有同名文件，更不能说源图片已被覆盖或图库已经增加一项。没有可信回执前，界面应保留原始URI与临时增强文件，并给出可解释的重试入口。
设计测试向量很克制：previewBound=1表示本地流程认定一份增强预览与一份源选择关系已经配对；saveAttempts=1表示演示夹具触发一次保存请求；savedCount=0表示尚未得到成功确认；SAVE_FAILED_RETRYABLE表示这次模拟错误后允许用户重新检查并选择重试。错误名MOCK_SAVE_ERROR是我们自己定义的夹具标签，不是华为公开的系统错误码。
这个切入点能够避开一个常见误判：把 API 调用“没有同步抛异常”直接解释为“保存成功”。图片业务中存在沙箱文件、系统Picker预览、图库资产几个不同层次；某一层看起来完成，不意味着其他层也完成。只有把每一阶段独立列出，才能知道应该在什么时候清理临时文件。
二、先确认官方提供的能力边界
华为官方于2026-03-09更新的《使用PickerController将编辑后的图片替换原图》明确描述两段流程：应用可以把编辑后的沙箱文件发送给 PhotoPicker，让 Picker 的预览显示替换内容；随后可以将 Picker 上成功替换显示范围内的资源保存到图库。官方示例使用PickerController.replacePhotoPickerPreview()和saveTrustedPhotoAssets()，其中保存模式区分SaveMode.SAVE_AS与SaveMode.OVERWRITE。
文档同样强调保存调用的前置条件：应先完成replacePhotoPickerPreview，所传保存文件应处于替换显示范围内，并确保保存内容与显示内容一致。它没有说“更换预览意味着已修改原始图库文件”。因此本例把预览绑定与保存动作拆开，也不把 PhotoPicker 当成一个可随意写入任意 URI 的开放文件通道。
这篇所用的能力属于系统Picker与媒体图库交互。开发者仍须在目标SDK、UIAbility以及Picker组件真实上下文中检查API可用性，不应从某个示例函数名推导出所有设备或元服务均支持。本文只围绕已查到的接口形态写演示代码，避免杜撰一个不存在的“超分完成自动保存SDK”。
三、把任务的身份、模式和对象固定下来
项目叫AlbumSafeExport，主页面SaveReviewPage，诊断页面ExportAuditPage，业务闸门ExportTicketGate。来源文件是IMG_0924.JPG，应用沙箱内待保存的增强文件名是enhanced_0924.jpg，任务号SAVE-1010-10。两者不是同一个 URI，输入1280×960与输出2560×1920也不能因为“都显示同一画面”就混用。
用户在本次任务明确选择的模式是SAVE_AS。另存为意味着我们的产品意图是创建新结果，不是替换原始媒体资产，因此UI持续显示“原图保持不变”。这是应用设计中的意图与保护策略，不是提前证明系统保存已经成功。若以后增加覆盖模式，必须让用户再次确认，并将两种模式的审核证据分开保存。
本次故障演示的初始状态是PREVIEW_BOUND，前置变量previewBound=1；用户点保存后状态临时成为SAVE_IN_FLIGHT，saveAttempts=1。夹具返回错误MOCK_SAVE_ERROR，于是进入SAVE_FAILED_RETRYABLE，savedCount=0，同时源资产不被触碰。诊断日志仅表示一次模拟场景，不代表调用过图库或产生过新文件。
四、先做纯应用层凭证，别让回调直接改页面
第一段代码只是为系统调用加一个可测试的应用层状态机。ExportTicketGate并非系统 API，它负责让某个回调必须同时匹配任务、源文件和预览代次。所有内容都先落在一个独立会话中，避免页面变量被另一个用户操作覆盖。
exporttypeExportState='PREVIEW_PENDING'|'PREVIEW_BOUND'|'SAVE_IN_FLIGHT'|'SAVE_FAILED_RETRYABLE'|'SAVED_AS_NEW';exportclassExportTicketGate{readonlytaskId:string='SAVE-1010-10';readonlysourceName:string='IMG_0924.JPG';readonlyeditedName:string='enhanced_0924.jpg';readonlymode:string='SAVE_AS';state:ExportState='PREVIEW_PENDING';previewEpoch:number=1;previewBound:number=0;saveAttempts:number=0;savedCount:number=0;lastError:string='';bindPreview(taskId:string,epoch:number,ok:boolean):void{if(taskId!==this.taskId||epoch!==this.previewEpoch){return;}if(!ok){this.lastError='PREVIEW_BIND_FAILED';return;}this.previewBound=1;this.state='PREVIEW_BOUND';}requestSave():boolean{if(this.state!=='PREVIEW_BOUND'&&this.state!=='SAVE_FAILED_RETRYABLE'){returnfalse;}if(this.previewBound!==1){returnfalse;}this.saveAttempts+=1;this.state='SAVE_IN_FLIGHT';returntrue;}completeSave(ok:boolean,code:string):void{if(this.state!=='SAVE_IN_FLIGHT'){return;}if(ok){this.savedCount+=1;this.state='SAVED_AS_NEW';return;}this.lastError=code;this.state='SAVE_FAILED_RETRYABLE';}}设计时特别要考虑重复保存：requestSave()不允许并发执行第二次，防止用户在回调尚未返回时连续点击两次。即使 UI 防抖，也必须在模型层拒绝重复提交，否则窗口重建、双击和辅助设备输入都可能绕过按钮禁用态。这里的“可重试”还只是应用策略，下一次调用前应查询或确认图库是否已生成资产，避免超时但实际上保存成功时重复写入。
previewEpoch控制的是“这张增强预览还属于当前任务吗”，并非全局图片版本号。如果用户重新选择其他照片，必须递增代次并使旧回调失效；否则上一张照片的预览替换成功消息仍可能到达，错绑到当前界面。状态机会拒绝旧回调，但临时文件释放仍需要外层资源管理器在安全时机执行。
五、正式调用前，务必拥有一份真正可用的沙箱文件
很多演示喜欢直接在代码里写两个硬编码 URI 然后调用保存，结果忽略了Picker选择上下文和沙箱内容是否真实存在。本例把IMG_0924.JPG作为逻辑显示名，真实originUri必须来自当前用户选择的 PhotoPicker 结果；editedUri必须是这个任务在应用沙箱中实际生成的文件 URI，而不是一个随手拼接的字符串。
因此，准备阶段应执行文件存在性、非空长度、媒体格式和尺寸等检查：来源与增强文件不能指向同一个可写位置；增强文件必须可读取；文件扩展名与编码类型应相符；如果显示1920×1440但文件实际仍是原图，必须拦截保存。这里所谓“增强2×”只是一份由夹具提供的图像尺寸信息，不等同于任何真实AI模型推理结果。
当文件大到需要并行编码时，编码任务可以并发，保存闸门却仍必须保证当前用户会话只持有一个有效预览绑定。不要通过临时文件名称中的日期推断身份，而应把真实URI、任务ID、代次和校验摘要组合成一份受控的应用层记录。离线缓存被清理后，应明确标为“预览源失效”，而不是继续启用保存按钮。
六、把官方预览替换动作关进绑定阶段
第二段代码展示PickerController接口所在的位置。使用官方导出名；回调做异常检查，只有任务与代次仍然匹配时才确认绑定。此示例假设页面已经正确构建 PhotoPicker 组件、Controller 连接就绪，并且拥有可访问的真实originUri与editedUri。这些前置条件不能在普通静态页面里凭空成立。
import{PickerController}from'@kit.MediaLibraryKit';exportclassPickerPreviewBridge{privatecontroller:PickerController=newPickerController();privategate:ExportTicketGate=newExportTicketGate();bindSelectedImage(originUri:string,editedUri:string):void{constepoch=this.gate.previewEpoch;consttask=this.gate.taskId;this.controller.replacePhotoPickerPreview(originUri,editedUri,(err,_result)=>{constok=err===undefined||err===null||err.code===0;this.gate.bindPreview(task,epoch,ok);});}}这段代码的目的不是让读者把PickerController当作一个无上下文的全局服务，而是强调它的回调不应该直接改 UI 状态。生产项目还需要通过真实 PhotoPicker 组件绑定 Controller；当组件销毁时，失效当前会话并回收暂存引用。若replacePhotoPickerPreview返回错误，必须保持previewBound=0，避免未经显示绑定的临时结果进入保存动作。
replacePhotoPickerPreview名字容易造成错觉，好像它修改的是图库原始照片。根据官方说明，动作针对的是 Picker 中显示的预览关系。应用有义务在文案里区分“预览已替换”与“文件已另存到图库”；如果点击“继续保存”前连这两个概念都混淆，之后出现覆盖争议就很难排查。
七、保存调用与产品意图是一对必须一致的参数
第三段代码才涉及保存。模式写死为SaveMode.SAVE_AS，配置类型采用官方样例中的PhotoCreationConfig；本地闸门通过以后才发起调用。示例中的错误处理只保存可解释的状态，不假设回调错误码的具体数值是什么。真实应用应按官方参考文档记录BusinessError.code，并区分可重试与用户取消两种情况。
import{PickerController,SaveMode,photoAccessHelper}from'@kit.MediaLibraryKit';exportclassSafeGallerySubmitter{constructor(privatecontroller:PickerController,privategate:ExportTicketGate){}saveAsNew(editedUri:string):void{if(!this.gate.requestSave()){return;}constconfig:photoAccessHelper.PhotoCreationConfig={title:'enhanced_0924',fileNameExtension:'jpg',photoType:photoAccessHelper.PhotoType.IMAGE,subtype:photoAccessHelper.PhotoSubtype.DEFAULT};this.controller.saveTrustedPhotoAssets([editedUri],(err,_result)=>{if(err&&err.code!==0){this.gate.completeSave(false,`${err.code}`);return;}this.gate.completeSave(true,'');},[config],SaveMode.SAVE_AS);}}这里在requestSave()时就把按钮语义锁定：尚未有完成回执时状态是SAVE_IN_FLIGHT，而不是乐观地写成“已保存”。系统调用的异步顺序也很重要，必须是在同一批已替换的 Picker 预览范围内执行保存。实际运行还要验证对应 SDK 的类型声明和导出路径，异常分支可通过真实错误码进一步细化；本文没有实际调用图库，因此不会输出任何伪造的系统错误号。
如果 callback 因页面退出而晚到，页面层已经不再存在时不应继续更新可见控件。应用可以保留独立的任务审计记录，让下一次打开页面时查到上次动作的状态，但不能因为页面消失就假定底层保存已经取消。资源释放和存储副作用是两件事，需要分别设计。
图02为 DevEco Studio 风格生成式演示示意图，编译、图库保存及回调均未实际发生。
八、保存失败也要保证原图安全
本轮模拟在10:24:11完成预览绑定，10:24:12用户触发一次另存，10:24:13夹具返回MOCK_SAVE_ERROR。结果是saveAttempts=1、savedCount=0、previewBound=1，页面进入SAVE_FAILED_RETRYABLE。原始选择IMG_0924.JPG仍保留在任务证据中，增强文件enhanced_0924.jpg不立即删除，以便用户决定是否重试。
这里的savedCount=0指的是“演示闸门未收到成功确认”，并不能反证图库真的没有新增图片。某些真实失败情境可能属于网络延迟、后台切换、回调丢失、权限交互中断或相册服务超时。调用方必须先执行幂等核查或由用户确认，不能盲目把每一种失败都视为可立即重复写入。
我们故意不引入自动覆盖恢复。当前模式已经是SAVE_AS，用户从开始就希望保留原图；即使临时增强内容有误，也应让用户重新预览、明确选择后再提交，而不是为了“恢复”去覆盖原始文件。页面允许“重新检查并重试”，但不应该在失败后偷偷切换成OVERWRITE。
九、主界面应该显示哪些状态
面向用户的SaveReviewPage最重要的是把来源、编辑结果和操作意图摆在一起。顶部写清任务SAVE-1010-10、原图IMG_0924.JPG、增强文件enhanced_0924.jpg、2×尺寸关系，以及明确的“另存为新图”；中间展示左侧原图与右侧增强预览；状态区告知用户本轮演示的保存尝试失败、仍可复核后重试。
图03为预览与保存状态的演示示意，不是 PhotoPicker 或真实系统图库截图。
界面必须避免一种过度正面的叙述：明明状态为SAVE_FAILED_RETRYABLE，却在图片下方打绿色“保存成功”。即使曾经成功显示增强预览，也只是完成预览阶段。主界面能证明“用户看的是这张增强图片，并选择了另存模式”，不能证明保存已落库；这就是把凭证展示放在按钮上方的原因。
此外不应只让用户看到一个本地缓存路径。实际产品需要在任务表里保存摘要、来源标识与媒体访问权限上下文，出于隐私安全的考虑，完整沙箱路径最好仅存在于受控日志或本地数据库，不要默认暴露在截图与用户可分享的错误报告里。
十、诊断页承担“失败之后还能说清楚”的职责
ExportAuditPage不重复展示大幅照片，它关心事件与回执。诊断表将预览绑定记为一次、保存请求记为一次、成功确认记为零次；提供时间线，让研发能够看到PREVIEW_BOUND -> SAVE_IN_FLIGHT -> SAVE_FAILED_RETRYABLE的实际状态路径。错误标签MOCK_SAVE_ERROR前面必须写明“模拟故障”，避免被误读为真实API错误码。
图04是演示诊断屏，所有时间与错误标签都来自预先定义的夹具。
如果出现“保存回调成功但没有对应的任务ID”，系统不应仅凭err.code === 0就更新当前页面。回调要匹配当前任务和预览代次，成功回执也要与最终保存结果关联。用户切换了另一张照片后，旧回调可以入历史审计，但不能改写新任务的savedCount。
一条合理的恢复流程是：展示可识别的失败原因、保持原始照片的引用、检查本地增强文件是否仍存在，必要时让用户重新选择保存目标；待确认没有重复结果时允许重试。要特别避免把“重试次数”误做“保存数量”，否则管理后台很难解释一次失败两次重试与最终一个新资产之间的对应关系。
十一、什么时候才能释放临时增强文件
增强图片往往体积不小，保存完马上删除临时文件似乎最节省空间。但如果只是收到了预览替换成功回调，系统保存阶段还没有完成，提前删除会破坏下一步。另一个极端是永久保留所有失败临时文件，这同样会让应用沙箱持续膨胀。
可以为临时文件增加租约：PREVIEW_BOUND与SAVE_IN_FLIGHT时保持引用；成功回执并完成必要的目标核查后释放；失败可重试时保留一段有限时间并明确告诉用户；任务取消或凭证过期后进入后台清理队列。清理任务应按唯一任务ID和路径摘要校验，绝不能只按模糊的文件名批量删除。
如果用户强制结束应用，再次打开时任务数据库应能区分“写入中断”“等待回执”和“成功已确认”。单靠内存状态机无法完全提供崩溃恢复能力，所以正式实现必须加持久化证据与恢复扫描。本文只验证状态转移的工程合理性，没有编写操作图库的后台扫描器，也不作任何真实端侧运行承诺。
十二、权限和编辑范围是业务设计的一部分
用户通过Picker选择某张照片，与应用申请整个相册读写权限是不同路径。官方提倡受控的Picker访问方式，开发者应优先只访问用户主动提供的资产。演示中不把用户选择过一次理解成永久拥有全部图库内容的访问权，也不把应用自己的临时增强结果当作可替换所有原图的凭证。
系统可能根据设备能力、接口级别和用户交互决定保存或访问行为，因此产品端应在真正的Picker上下文测试用户取消、再次选择、授予与拒绝、应用被回收等分支。只凭模拟回调不能证明平台权限模型的每个细节。本例的权限原则是“先保持最小可访问范围、后按确认的意图提交”，而不是在后台主动扫描整套相册。
SaveMode.SAVE_AS和SaveMode.OVERWRITE的存在恰恰说明产品需要作明确选择。覆盖类动作还可能影响编辑历史、云同步以及原图保留政策，远超一个按钮参数。当前工程只实现另存方向的门禁，保留其他方向作为未来独立设计任务，不把二者混合成一个默认行为。
十三、单元测试可以先证明什么，还不能证明什么
在没有真实设备与图库环境时，纯逻辑单元测试仍有价值：匹配任务的预览成功回调使previewBound=1；旧代次回调不能错误确认新任务；同一时刻连续点击保存只有一次请求进入SAVE_IN_FLIGHT；模拟错误使状态变为SAVE_FAILED_RETRYABLE且savedCount=0；失败后保留原始选择和沙箱文件引用。每个断言都能以自定义回调夹具重放。
接下来的集成测试要在真实 PhotoPickerComponent、设备和应用签名环境里完成：校验预览替换范围，确认保存模式确实为另存、实际图库结果与展示一致，再测试用户取消、重试、应用切后台和大文件情境。集成测试还应把设备版本、SDK/DevEco配套、媒体格式、出错码和用户操作步骤记录完整。本文没有这些运行证据，因此不能把任何一条模拟断言改写成“实测成功”。
当保存成功后，也应核对与任务匹配的新资产，不要只统计回调被调用的次数。跨照片和跨任务的清理责任必须明确：旧任务的失败不影响新任务，旧任务的成功不能改变当前照片的显示状态，未确认的临时文件不能被随手删掉。
十四、结论留在可验证的地方
图像增强流程最容易被忽视的不是算法参数，而是结果离开算法后还是否保持正确身份。当前方案建立三条边界：源照片与增强文件必须明确绑定；预览已更新和图库已保存必须分开记账；失败之后必须保留足够证据，让用户能够安全决策是否重试。
对于正式应用，这套模型只是开始。实际replacePhotoPickerPreview与saveTrustedPhotoAssets的有效调用、回调语义、真实图库落库、崩溃恢复与权限变化，还需完整工程和设备验证。不能因为演示屏上写着一个状态标签，就把它说成系统已经完成动作。
与此前讨论过的图像双视图解码与资源交接不同，本篇从预览完成后的图库保存阶段切入；与超分对照尺的坐标映射也不是同一个问题。算法可以不断升级，但保存前的凭证与用户意图需要始终保持可解释，这才是面向产品的稳定边界。
十五、官方参考资料
华为官方《使用PickerController将编辑后的图片替换原图》，2026-03-09：https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/medialibrary-pickercontroller。华为《Picker API参考》：https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-file-picker。本文对replacePhotoPickerPreview、saveTrustedPhotoAssets与SaveMode.SAVE_AS的说明以官方文档为依据；ExportTicketGate、MOCK_SAVE_ERROR和所有示例状态均为应用层自定义。全部示意图为生成内容，非正式开发截图或实际审核结果。
