在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，系统才能跨进程读取并渲染预览。

失败本质：在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. 效果对比：从“盲存”到“可视”

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

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. 避坑指南：预览空白的“三必须”

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

1. 沙箱路径是“黑盒”：应用沙箱内的文件路径（/data/storage/...），系统预览服务无法直接读取。

2. 预览需“URI”：必须通过fileUri.getUriFromPath将路径转换为文件URI（file://...），系统才能跨进程渲染预览。

3. 路径不等于URI：直接传入字符串路径，永远不会显示预览图。

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

©著作权归作者所有，如需转载，请注明出处，否则将追究法律责任。