企业官网建设流程全解析

做鸿蒙应用的人，迟早都会遇到一个看起来平平无奇的需求：把应用里的图片、二维码、截图保存到系统相册。早期版本里这事真的不难，申请一个写媒体库的权限，应用就能往相册里放东西。但从API 10开始，鸿蒙媒体库的权限模型改了，官方不再鼓励开发者直拿写权限，而是推荐用系统弹窗让用户看到要保存的资源、点一下“允许”，应用才能把文件真正写进相册。这个能力对应的核心API就是photoAccessHelper.showAssetsCreationDialog。我第一次用这个接口时，光是把参数猜明白、把URI格式调对就折腾了大半个晚上。这篇文章把弹窗授权保存媒体库资源的原理、代码、坑和替代方案一次讲透，适合正在做鸿蒙媒体库保存功能、以及刚接触API 10以上权限模型的开发者。

1. 为什么鸿蒙要把“保存到相册”做成一次弹窗授权

1.1 权限模型变化：从“长期授权”到“一次一授权”

在API 9及之前的鸿蒙版本里，保存媒体库资源的正统做法是：在module.json5里声明ohos.permission.WRITE_IMAGEVIDEO，运行时调用requestPermissionsFromUser弹一个系统权限框，用户点“允许”后，应用就拿到了向媒体库写入图片和视频的长期授权。此后只要应用愿意，它可以随时往相册里塞内容。用户对这个授权其实没有什么感知——他不知道这个应用这次保存了什么、存了多少张。

体验上方便，安全上不放心。相册是全系统隐私密度最高的数据之一，一次授权长期有效的模式，和平台正在推进的“隐私最小化”路线冲突。所以从API 10开始，媒体库模块整体从mediaLibrary迁移到photoAccessHelper，保存路径被有意收紧了：系统不再把“写入媒体库”作为一个独立的、可以长期持有的权限开放给普通应用，而是把每次保存都绑定到一次具体的用户操作上。

这个转变很关键。showAssetsCreationDialog这个接口的设计初衷，就是把“允许应用写相册”这个二元决策，拆成“这一次保存，你同意吗”的单次决策。用户每一次看到弹窗、点一次允许，应用才能保存这一批资源。等保存完成，授权即结束，系统不会因为你允许过一次，就默认你以后的所有写入都合法。对用户来说，这个模式理解成本很低，对开发者来说，代码路径也变得更清晰——你不再需要维护一个“权限是否已申请”的状态，每次保存都是独立事务。

1.2 三种保存姿势的对比与选型坐标

我梳理一下目前鸿蒙里往媒体库保存资源的三条路线，方便后面展开对比。

先看老式路线。如果你的项目还跑在API 9，那没得选，只能走mediaLibrary.createAsset。但如果target已经到API 10以上，不建议再为这个接口去申请WRITE_IMAGEVIDEO权限。API 12之后的权限体系里，这个权限的申请通道已经很不顺畅，很多设备上根本拿不到，就算拿到，应用市场上架审核时也大概率会被追问用途。

再看弹窗授权路线。它是API 10到API 12之间最主流的保存方式，优点是弹窗内容可定制，能展示缩略图，用户能明确知道即将被保存的是一张什么图、一段什么视频；缺点是用户多了一步操作。对于需要“让用户确认保存内容”的场景，比如保存一张自定义海报、保存用户自己生成的头像，弹窗授权反而是加分项，它把“告知与同意”做进了交互流程里。

安全控件是更彻底的方向。保存按钮本身被系统认定为“用户授权动作”，用户点击控件的那一刻，系统就认为授权成立了，应用在回调里调用createAsset直接落库，全程没有权限弹窗也没有保存弹窗。代价是按钮样式受系统约束，自定义空间有限。这个我在第5章细说。

理解这三条路线的区别，后面选型才不会懵。下面把弹窗授权这条主线的内部逻辑拆开看。

2. showAssetsCreationDialog内部做了什么：校验、预览、授权、落库

2.1 一次API调用背后的四个步骤

很多人看这个接口的签名只有两参一返回，觉得就是个简单封装。其实它内部是一条四阶段链路：参数校验、预览生成、弹窗交互、写入媒体库。

第一阶段是参数校验。系统会检查传入的URI数组是否为file://协议开头的合法URI，每个URI指向的文件是否存在、可读，dialogType是否与资源类型匹配，配置对象里有没有非法字段。只要有一项不过关，调用会直接抛参数错误。这一年多来我在社区里看到的新手报错，大半是卡在这一步——最典型的就是把沙箱路径当成URI传进去，这个在第3章专门讲。

第二阶段是资源预览生成。系统逐个解析URI，为每个文件生成缩略图，同时获取文件大小、类型等元数据，为弹窗内容做准备。如果你的资源是临时文件且保存成功前恰好被清理掉了，这个阶段预览就会是空白，甚至直接判定资源不可用。所以临时文件的生命周期必须覆盖到弹窗回调返回之后。

第三阶段是弹窗交互。这里才是“授权”真正发生的地方。系统展示一个带标题、副标题、缩略图预览和“取消/允许”按钮的弹窗，等待用户做出选择。注意，这个弹窗是系统级弹窗，不是应用自己搭的UI，应用没有办法通过布局技巧绕过或隐藏其中任何元素。

第四阶段是写入媒体库。用户点允许后，系统把资源写入相册目录，建立媒体库索引，并为每条资源生成新的媒体URI，最终以SaveResult[]的形式把结果返回给应用。应用拿到的是相册中的正式资源URI，而不是原来的沙箱路径。复制、转码、建索引这些脏活系统自己完成，不需要开发者处理。

还有一个值得理解的设计点：为什么接口收的是URI而不是Bitmap或PixelMap对象？因为保存是系统进程异步完成的，系统需要在稍后的时间点重新读取文件内容，而不是引用一块应用内存里随时可能被回收的图片数据。URI本质上是一个稳定的、可重新寻址的引用，天然支持批量、支持预览、支持应用与系统进程之间的安全传递。所以哪怕你手里已经有一个PixelMap，也必须先把它打包成JPEG/PNG写入沙箱文件，再用fileUri转成URI去唤起弹窗。

2.2 PhotoCreationConfig和SaveResult字段逐个过

PhotoCreationConfig是弹窗的“装修方案”，字段不少，但常用的就这几个。

• title：弹窗标题，建议简短，一屏内读完。默认值一般是类似“允许保存至相册”的文案。别放太长，单行截断后反而显得不专业。
• subTitle：副标题或说明文字，最多两行位置，适合写“本次保存的内容是XXX，保存后可随时删除”这类解释。
• contentDescription：无障碍语义描述，读屏软件会朗读这段文本。很多人会忽略，但审核和用户体验评测里这是会被点名的项，顺手填上。
• dialogType：资源类型，枚举值有PHOTO、VIDEO、PHOTO_AND_VIDEO。这个字段要和你传入的URI实际类型匹配，传错会导致预览不显示或保存校验失败。如果这批资源里图片和视频都有，就选PHOTO_AND_VIDEO。
• creationExtraParams：可选扩展参数，个别场景下用于指定保存到某个具体相册目录，普通应用基本用不到，真需要时以当前SDK文档为准。

返回结果SaveResult[]，数组长度和传入的URI数组一一对应。每个元素两个字段：uri是保存成功后系统生成的媒体资源URI，success是布尔值，表示这条资源是否保存成功。批量保存时，其中某几张失败是常态，遍历数组时不要只看第一个元素就下结论。

3. 最小可运行工程：从配置到第一次保存成功

3.1 工程配置：module.json5权限到底加不加

先说结论：如果工程target是API 12及以上，调用showAssetsCreationDialog不需要在module.json5里声明媒体库权限，也不需要运行时动态申请。这个接口的定位是“用户主动授权型”，权限模型上已经绕开了WRITE_IMAGEVIDEO。

但如果你要兼容API 10/11，情况会复杂。这两个版本上不同机型行为不完全一致，我在部分真机上遇到过不声明ohos.permission.WRITE_IMAGEVIDEO直接调用会报权限拒绝的情况。所以兼容做法的建议是：在module.json5中声明ohos.permission.WRITE_IMAGEVIDEO作为兜底；运行时只在检测到SDK版本小于12时才调用requestPermissionsFromUser申请一次；target高于12时不声明，不给用户添无谓的权限弹窗。

有人会困惑：声明了权限岂不是又要弹权限框？其实只要你不主动调用requestPermissionsFromUser，系统不会自动弹。声明权限只是把能力注册在包配置里，真正触发弹窗的是代码里的主动请求。所以兼容方案的底线是：低版本才请求，高版本不请求。

顺带提一下版本判断的写法，后面章节会用到：

import { deviceInfo } from '@kit.BasicServicesKit'; const targetVersion = 12; if (deviceInfo.sdkApiVersion < targetVersion) { // 低版本兼容路径：先申请WRITE_IMAGEVIDEO，再调用保存弹窗 }

deviceInfo.sdkApiVersion在API 10/11上就能用，拿到的主版本号按整数比较即可。这个判断尽量放在页面初始化时执行，不要把权限申请拖到保存按钮弹窗之后再临时处理，否则用户体验会很割裂。

3.2 沙箱路径到file URI：新手最容易卡死的转换

这是我在社区答疑里见过最多的一类问题。很多人会直接把context.filesDir + '/test.jpg'这样的字符串作为第一个参数传给showAssetsCreationDialog，然后收到一个报错，报错内容通常是参数校验失败。

原因是这个接口要求的是URI，不是普通路径。鸿蒙文件URI的标准形式是file://协议加上应用包名和完整路径，例如file://com.example.demo/data/storage/el2/base/haps/entry/files/test.jpg。从绝对路径转成这个URI要用的模块是fileUri，一行代码：

import { fileUri } from '@kit.CoreFileKit'; let uri = fileUri.getUriFromPath('/data/storage/el2/base/haps/entry/files/test.jpg');

反过来，如果你拿到一个URI想知道它指向哪个本地路径，用fileUri.getPathFromUri(uri)。这两个方法在调试打印时非常有用。

还有一个隐蔽问题：context.filesDir在不同API版本下返回的路径前缀有差异。API 10/11时代是/data/storage/el2/base/files，API 12之后可能是/data/storage/el2/base/haps/entry/files，多了一层haps/entry。自己拼路径很容易拼错，所以最好永远用context.filesDir动态拼接，别写死绝对路径。

3.3 核心代码实现与运行结果

下面给一份可以直接跑的最小实现。这个示例做的事情是：从rawfile里取一张测试图片，复制到应用沙箱，转成URI，拉起保存弹窗，打印结果。测试前记得在resources/rawfile/下放一张demo_share.jpg。

import { fs, fileUri } from '@kit.CoreFileKit'; import { photoAccessHelper } from '@kit.MediaLibraryKit'; import { common } from '@kit.AbilityKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { BusinessError } from '@kit.BasicServicesKit'; async function ensureDemoFile(context: common.UIAbilityContext): Promise<string> { const targetPath = context.filesDir + '/demo_share.jpg'; let exists = true; try { fs.accessSync(targetPath); } catch (e) { exists = false; } if (!exists) { const rawData = await context.resourceManager.getRawFileContent('demo_share.jpg'); const file = fs.openSync(targetPath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); fs.writeSync(file.fd, rawData.buffer.slice(rawData.byteOffset, rawData.byteOffset + rawData.byteLength)); fs.closeSync(file); } return fileUri.getUriFromPath(targetPath); } async function saveToAlbum() { const context = getContext(this) as common.UIAbilityContext; try { const srcUri = await ensureDemoFile(context); const helper = photoAccessHelper.getPhotoAccessHelper(context); const config: photoAccessHelper.PhotoCreationConfig = { title: '保存图片到相册', subTitle: '允许后图片将被保存到系统相册，之后可在相册中随时查看或删除', contentDescription: '图片保存授权弹窗', dialogType: photoAccessHelper.PhotoCreationType.PHOTO, }; const results = await helper.showAssetsCreationDialog([srcUri], config); if (results.length > 0) { const first = results[0]; if (first.success) { hilog.info(0x0000, 'SaveDemo', '保存成功，媒体库URI: %{public}s', first.uri); } else { hilog.warn(0x0000, 'SaveDemo', '用户未允许本次保存'); } } } catch (err) { const e = err as BusinessError; hilog.error(0x0000, 'SaveDemo', '调用失败: code=%{public}d msg=%{public}s', e.code, e.message); } }

在页面里给按钮绑定saveToAlbum即可。真机上运行后，弹窗会显示这张图片的预览，点允许后系统相册里多出这张图，控制台打印出以file://media/Photo/开头的媒体库URI。我这里用rawfile演示的是“应用自带静态资源”场景；真实业务里，如果手里拿的是PixelMap，就用image.createImagePacker()打包成JPEG再写入沙箱，思路完全一致，只多一个打包步骤。

提示：在预览器里运行这段代码大概率是失败的，因为系统级弹窗无法在Previewer中渲染。请务必用真机或模拟器验证。

4. 真机验证中的版本差异与失败路径

4.1 用户拒绝时不reject：success=false藏在成功分支里

这是弹窗授权最让我印象深刻的坑。我最初写的时候，把showAssetsCreationDialog当作普通Promise处理，觉得用户拒绝时Promise应该会reject，所以只在try-catch里打了日志。结果真机测试时，点击弹窗的“取消”按钮，代码居然走进了try分支的后续逻辑，一切表现得很正常，只是返回结果里的success字段是false。

也就是说，用户拒绝不一定会触发异常。这个接口把“拒绝”编码成了正常的业务结果，Promise照样resolve。如果代码里只判断“有没有进catch”，很可能会把拒绝当成成功继续往下走——比如给用户提示“保存成功”，这显然是个功能bug。

正确的处理方式是双保险：外层保留try-catch兜底异常路径；内层必须逐条检查SaveResult.success。而且要注意，数组里可能部分成功部分失败，不能只判断第一项。保存多张图时，用户点一次允许，不代表每一张都能成功，个别资源可能因编码问题或系统空间不足而保存失败。

4.2 API 10到API 12的行为差异与兼容处理

我的测试结论是：API 10/11的底层实现和API 12存在差异，官方文档在showAssetsCreationDialog的“无需权限”描述上，是冲着API 12之后的状态写的。低版本上可能需要兜底权限，已如前述；另外低版本的弹窗样式和预览行为也不完全一致。

给一个可操作的兼容判断写法：

import { deviceInfo } from '@kit.BasicServicesKit'; const compatibleVersion = 12; if (deviceInfo.sdkApiVersion < compatibleVersion) { // 走低版本兼容路径：先申请WRITE_IMAGEVIDEO，再调用保存弹窗 }

这里的deviceInfo.sdkApiVersion在API 10/11上是可用字段，拿到的主版本号用整数比较就行。如果你项目里已经在用@ohos.deviceInfo的旧写法，也可以通过deviceInfo.sdkApiVersion读取，只是导入包路径换成了@kit.BasicServicesKit。注意这个判断尽量放在页面初始化时执行，不要把权限申请放到保存按钮已经弹窗之后再临时处理，用户体验会很割裂。

4.3 批量保存、临时文件生命周期与调试建议

批量保存是另一个高频率问题。我建议遵循两个原则：一是分批，二是保活。

分批指不要一次性塞几十个URI。弹窗要把每个资源都生成预览图，资源一多，预览加载时间明显变长，用户看到的可能是长时间的空白加载，甚至直接判定为卡死。我自己的习惯是每批不超过10个，如果业务资源总量更大，就在界面里加进度条分批处理。

保活指临时文件不要提前清理。常见错误是把资源写入沙箱后，立刻调用fs.unlink释放空间，然后才拉起保存弹窗——结果弹窗预览空白或者保存报错。正确时序应该是：先保存成功（success为true）或用户明确取消后，再进入清理分支。而且清理要放在结果处理里，不要在弹窗调用前后随手做。

调试阶段还有两个小建议。第一，善用fileUri.getPathFromUri反解结果URI，确认系统返回的file://media/Photo/...对应真实文件确实存在。第二，真机上出问题时，用hdc shell进沙箱目录检查临时文件是否还在、权限位是否正确。很多时候问题不是出在媒体库，而是出在沙箱文件本身。

为了排查方便，我把常见问题整理成一个速查表：

5. 再进一步：SaveButton安全控件与其他方案怎么选

5.1 SaveButton免弹窗免权限的接入思路

弹窗授权虽然好用，但终究多了一次交互。如果你的产品觉得这步太冗余，可以换安全控件方案。saveButton是系统提供的安全控件，在API 11之后的ArkUI里创建。它的关键性质是：用户点击控件这个行为本身就是系统认可的一次授权操作，应用不需要申请媒体库写权限，也不需要再弹窗确认。

接入思路大致是：在build()里声明保存控件，控件上挂onClick，回调里直接调用photoAccessHelper的createAsset把文件写入媒体库。因为是用户主动点击控件触发的，系统会放行。运行时会发现，这个方案全程没有任何系统弹窗，保存动作干净利落。

代价也有：按钮的文案、图标、样式受系统约束，可以设置的组合有限，不像普通Button那样随意改配色和圆角。如果你的页面风格很独特，安全控件可能会显得格格不入。另外它要求SDK版本较高，API 10的老项目接起来不划算。

5.2 我的选择依据：什么时候用弹窗授权，什么时候用安全控件

我把自己做选择时的判断条件整理成三条，供参考。

第一看产品诉求。如果产品希望用户对“图片要被放进相册”这件事有明确感知，弹窗授权更合适，因为弹窗里有标题、说明和缩略图，天然就是一次告知。反之，如果保存只是后台动作，希望用户无感知完成，安全控件体验更顺。

第二看SDK版本下限。如果应用要兼容API 10设备，安全控件基本用不了，弹窗授权是唯一有跨版本兼容能力的现代方案。如果只跑API 12以上，我倾向安全控件，因为它省了弹窗这一步，干预更少。

第三看审核与合规。从我接触过的上架经验看，安全控件因为“用户主动操作即授权”的模型，审核时被质疑的概率低很多。弹窗授权虽然不是老式的长期写权限，但仍属于敏感能力调用，部分市场可能要求补充说明。如果应用会大量保存相册资源，能上安全控件就上安全控件，省去解释成本。

另外还有一个实操细节：安全控件回调里调用createAsset时，如果保存资源数量较大，建议把createAsset包在任务队列里逐条执行，避免在控件回调里做大量同步I/O导致卡顿。弹窗授权方案类似，资源多时也按批处理，保持体验平稳。

在我自己负责的一个工具类Demo项目里，最终选了弹窗授权方案，原因是产品需要把“保存后可在相册删除”的解释文案展示给用户，而安全控件给不了这种自定义文案空间。后来每次有同事问保存相册怎么做，我都是先把三条路线摆出来，让他们根据产品决策，而不是直接甩代码。媒体库保存这件事，API只是入口，真正的取舍永远在产品和体验层面。