HarmonyOS 6学习：保存图片预览空白？沙箱路径转URI的“视觉修复”术

在HarmonyOS 6上开发图片保存功能时，你是否遇到过这种"诡异"现象：调用showAssetsCreationDialog弹窗，界面却显示一片空白方框，用户无法预览图片，但点击保存后文件却能正常写入相册？你反复检查了文件权限和路径，确认图片真实存在，但预览就是"加载失败"。

这并非图片损坏或权限问题，而是HarmonyOS 6星盾安全架构下，沙箱路径（Sandbox Path）与媒体库URI（Media URI）的"身份"隔离 。本文将彻底解析这一"预览空白"现象，并提供一套基于fileUri.getUriFromPath的完整修复方案。

一、现象：弹窗空白，保存却成功

1. 问题现场：看不见的预览，存得下的文件

场景复现 ：用户编辑完图片，点击"保存到相册"，应用调用photoAccessHelper.showAssetsCreationDialog弹窗，但预览区域显示空白（或灰色占位图）。用户盲点"保存"后，系统图库中却能找到该图片。

预期效果	实际效果	技术假象
弹窗显示图片预览 → 用户确认保存	❌ 弹窗显示空白 → 用户盲操作保存	文件写入成功，但预览无权限

错误代码示例（导致"空白"的元凶）：

复制代码

// ❌ 错误示例：直接传入沙箱路径（HarmonyOS 6 预览无法识别）
import photoAccessHelper from '@ohos.file.photoAccessHelper';

async function saveImage() {
  let context = getContext(this);
  let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
  
  // 沙箱内图片路径（如：/data/storage/.../files/image.jpg）
  let sandboxPath = context.filesDir + '/image.jpg'; 
  
  // 直接传入路径字符串（错误！）
  let srcFileUris = [sandboxPath]; 
  
  let photoCreationConfigs = [{
    title: '我的图片',
    fileNameExtension: 'jpg',
    photoType: photoAccessHelper.PhotoType.IMAGE
  }];
  
  // 弹窗预览空白！
  let desFileUris = await phAccessHelper.showAssetsCreationDialog(srcFileUris, photoCreationConfigs);
}

2. 根因揭秘：沙箱路径的"身份缺失"

核心机制 ：HarmonyOS 6 的showAssetsCreationDialog接口要求srcFileUris参数必须是文件URI（File URI） ，而非普通的文件路径（File Path）。沙箱路径（/data/storage/...）对系统预览组件是"不可读"的 ，必须通过fileUri.getUriFromPath转换为标准的file://URI，系统才能跨进程读取并渲染预览。

参数类型	格式示例	预览效果
沙箱路径（Path）	`/data/storage/.../image.jpg`	❌ 空白（无权限）
文件URI（URI）	`file://com.example/app_sandbox/files/image.jpg`	✅ 正常显示

失败本质 ：在HarmonyOS 6上，应用沙箱路径默认对系统UI组件是"隐身"的。直接传入路径字符串，系统预览服务无法解析该路径的真实位置，导致无法加载图片缩略图。

二、解决方案：fileUri.getUriFromPath 路径转换

1. 修复原理：路径转URI，解锁预览权限

核心思路 ：将沙箱内的文件路径，通过@ohos.file.fileuri模块的getUriFromPath方法，转换为系统可识别的文件URI，再传入showAssetsCreationDialog。

修复代码：

复制代码

import photoAccessHelper from '@ohos.file.photoAccessHelper';
import fileUri from '@ohos.file.fileuri'; // 关键：导入URI转换模块

async function saveImageWithPreview(): Promise<void> {
  try {
    let context = getContext(this);
    let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
    
    // 1. 沙箱内图片路径（确保文件已写入）
    let sandboxPath = context.filesDir + '/image.jpg';
    
    // 2. 关键修复：将路径转换为文件URI
    let srcFileUri = fileUri.getUriFromPath(sandboxPath);
    let srcFileUris = [srcFileUri];
    
    let photoCreationConfigs = [{
      title: '我的图片',
      fileNameExtension: 'jpg',
      photoType: photoAccessHelper.PhotoType.IMAGE
    }];
    
    // 3. 弹窗正常显示预览
    let desFileUris = await phAccessHelper.showAssetsCreationDialog(srcFileUris, photoCreationConfigs);
    
    if (desFileUris.length > 0) {
      console.log('✅ 图片已保存至相册:', desFileUris[0]);
    }
  } catch (err) {
    console.error('❌ 保存失败:', err.message);
  }
}

2. 效果对比：从"盲存"到"可视"

修复前（路径直接传入）	修复后（路径转URI）	用户体验
弹窗预览空白	✅ 弹窗显示图片缩略图	用户可确认保存内容
日志无报错，保存成功	✅ 日志输出文件URI	调试信息更清晰

三、进阶：多场景下的"防呆"策略

1. 网络图片的"双步"保存

常见问题：下载的网络图片直接传入，预览仍空白。需先写入沙箱，再转换URI。

复制代码

// 步骤1：下载图片到沙箱
let networkImagePath = context.filesDir + '/download.jpg';
// ...（网络下载逻辑，将图片写入networkImagePath）

// 步骤2：转换URI并弹窗
let srcFileUri = fileUri.getUriFromPath(networkImagePath);
let desFileUris = await phAccessHelper.showAssetsCreationDialog([srcFileUri], configs);

2. 避坑指南：预览空白的"三必须"

规则	原因	违反后果
必须导入fileUri模块	路径转换需依赖`@ohos.file.fileuri`	编译错误
必须使用getUriFromPath	沙箱路径需转换为`file://`协议	预览空白
必须确保文件已写入	转换前文件需真实存在	预览加载失败

四、总结：预览空白的"URI转换"法则

沙箱路径是"黑盒" ：应用沙箱内的文件路径（/data/storage/...），系统预览服务无法直接读取。
预览需"URI" ：必须通过fileUri.getUriFromPath将路径转换为文件URI（file://...），系统才能跨进程渲染预览。
路径不等于URI ：直接传入字符串路径，永远不会显示预览图。

通过这一招"路径转URI"，你的图片保存弹窗将彻底告别"预览空白"，实现真正的所见即所得。