什么是文件预览服务你有没有遇到过这种情况在 App 里下载了一个文件想看看内容结果发现打不开或者需要用别的 App 来打开文件预览服务Preview Kit就是来解决这个问题的。文件预览服务是鸿蒙生态下的文件预览服务让你的应用可以直接预览各种文件不需要跳转到其他 App。它支持 5 种基本类型txt、html、图片、视频、音频覆盖 18 种详细文件格式。简单说就是让你的 App 变成一个万能文件查看器。你可能会问为什么不直接用系统的文件打开功能因为系统的文件打开功能需要跳转到别的 App用户体验不好。而且如果用户没有安装能打开该文件的 App就更尴尬了。用文件预览服务的话一切都在你的 App 里完成用户不用离开你的应用。核心功能文件预览服务提供以下功能文件预览直接在应用内预览文件不需要跳转格式支持支持 txt、html、图片、视频、音频等多种格式预览判断判断文件是否可以预览避免用户点了没反应交互体验支持缩放等交互操作用户体验好环境搭建硬件要求设备类型华为手机、平板、PC/2in1HarmonyOS 系统HarmonyOS NEXT Developer Beta1 及以上软件要求DevEco Studio 版本DevEco Studio NEXT Developer Beta1 及以上HarmonyOS SDK 版本HarmonyOS NEXT Developer Beta1 SDK 及以上搭建步骤安装 DevEco Studio去华为开发者官网下载安装配置开发环境确保网络环境正常设备调试使用真机进行调试项目结构└── entry/src/main/ets ├── entryability │ └── EntryAbility.ets // 本地启动 ability └── pages └── Index.ets // 基础预览界面项目结构非常简单核心逻辑都在Index.ets里。这个 Codelab 的重点就是教你调用预览服务的接口所以代码量不大。文件预览流程下面是文件预览服务的完整使用流程是否获取文件路径转换为 URI 格式调用 canPreview 判断文件是否可预览?创建 PreviewInfo 对象提示文件不可预览设置标题、URI、MIME 类型调用 openPreview打开预览界面支持的文件格式下面是文件预览服务支持的格式分类文件预览服务文本类图片类视频类音频类网页类.txt 纯文本.png.jpg/.jpeg.gif.mp4.mp3.html/.htm第一步导入模块import{filePreview}fromkit.PreviewKit;import{promptAction}fromkit.ArkUI;import{fileIoasfs,fileUri}fromkit.CoreFileKit;导入的模块有filePreview文件预览服务的核心接口我们用它来判断文件是否可预览、打开预览。这是整个文章最重要的模块promptAction弹出提示用的比如文件不可预览这种提示框fs文件操作用来创建和写入文件。在这个例子里我们需要先创建一个测试文件然后才能预览它fileUri文件 URI 转换把文件路径转成 URI 格式。预览服务需要的是 URI 格式的文件路径不是普通的文件路径第二步获取文件路径和 URIletcontextgetContext(this);letfileDircontext.filesDir;// 获取沙箱路径letfilePathfileDir/this.fileName;获取应用的沙箱路径。context.filesDir是应用的私有文件目录你的文件应该放在这个目录下。为什么要用沙箱路径因为鸿蒙系统的安全机制应用只能访问自己的私有目录。你不能直接访问其他应用的目录或者系统目录。沙箱路径就像你的应用的私人保险箱只有你的应用能打开。letfilefs.openSync(filePath,fs.OpenMode.READ_WRITE|fs.OpenMode.CREATE);leturifileUri.getUriFromPath(filePath);打开文件并获取 URIfs.openSync打开文件如果不存在就创建。READ_WRITE表示可读可写CREATE表示如果文件不存在就创建一个新的fileUri.getUriFromPath把文件路径转成 URI 格式file://docs/...。预览服务需要的是 URI 格式不是普通的文件路径。这个转换是必须的不转的话预览服务不认识第三步写入文件内容letstr:stringhello, world;letwriteLenfs.writeSync(file.fd,str);console.info(write data to file succeed and size is:writeLen);fs.closeSync(file);写入一些测试内容到文件里fs.writeSync写入字符串内容。file.fd是文件描述符可以理解为文件的代号fs.closeSync关闭文件。关闭之后就不能再读写了所以一定要在写完之后再关闭这一步是为了演示实际使用时你的文件可能已经存在了不需要写入。比如用户下载了一个 PDF 文件你想预览它直接用它的 URI 就行了。第四步判断文件是否可预览letresultawaitfilePreview.canPreview(context,uri);调用filePreview.canPreview判断文件是否可以预览。传入上下文和文件 URI返回true或false。这个步骤很重要因为不是所有文件格式都支持预览。先判断一下如果不支持预览可以给用户一个友好的提示比如该文件类型不支持预览。如果不判断就直接调用预览可能会报错或者显示空白。第五步打开预览if(result){letpreviewInfo:filePreview.PreviewInfo{title:this.fileName,uri:uri,mimeType:text/plain};filePreview.openPreview(getContext(this),previewInfo);}else{promptAction.showToast({message:文件不可预览});}如果文件可以预览就创建PreviewInfo对象并调用filePreview.openPreview打开预览。PreviewInfo包含三个字段title预览页面的标题会显示在预览界面的顶部。一般用文件名就行uri文件的 URI就是前面转换出来的那个mimeType文件的 MIME 类型告诉预览服务这个文件是什么类型的常见的 MIME 类型text/plain纯文本文件.txttext/htmlHTML 文件.html、.htmimage/pngPNG 图片image/jpegJPEG 图片.jpg、.jpegvideo/mp4MP4 视频audio/mpegMP3 音频MIME 类型一定要设置对否则预览服务可能不知道怎么处理这个文件。比如你把一个图片文件的 MIME 类型设成了text/plain预览服务就会把它当文本文件来处理显示出来的就是一堆乱码。如果文件不可预览弹出一个 Toast 提示用户。这样用户就知道为什么点了没反应而不是以为 App 卡了。完整代码把上面的步骤合在一起完整的代码是这样的import{filePreview}fromkit.PreviewKit;import{promptAction}fromkit.ArkUI;import{fileIoasfs,fileUri}fromkit.CoreFileKit;EntryComponentstruct Index{privatefileName:stringpreview_info.txt;build(){Row(){Column(){Button(openPreview).onClick(async(){letcontextgetContext(this);letfileDircontext.filesDir;letfilePathfileDir/this.fileName;letfilefs.openSync(filePath,fs.OpenMode.READ_WRITE|fs.OpenMode.CREATE);leturifileUri.getUriFromPath(filePath);letstr:stringhello, world;letwriteLenfs.writeSync(file.fd,str);console.info(write data to file succeed and size is:writeLen);fs.closeSync(file);letresultawaitfilePreview.canPreview(context,uri);if(result){letpreviewInfo:filePreview.PreviewInfo{title:this.fileName,uri:uri,mimeType:text/plain};filePreview.openPreview(getContext(this),previewInfo);}else{promptAction.showToast({message:文件不可预览});}})}.width(100%)}.height(100%)}}整个流程就是点击按钮 → 创建文件 → 获取 URI → 判断是否可预览 → 打开预览。看起来代码挺长的但其实大部分都是在做准备工作创建文件、获取 URI。真正和预览服务相关的就两行canPreview和openPreview。实际应用场景文件预览服务在实际开发中有很多用途文件管理器// 文件管理器中预览文件asyncfunctionpreviewFile(filePath:string,mimeType:string){letcontextgetContext(this);leturifileUri.getUriFromPath(filePath);letcanPreviewawaitfilePreview.canPreview(context,uri);if(canPreview){letpreviewInfo:filePreview.PreviewInfo{title:filePath.split(/).pop()||,uri:uri,mimeType:mimeType};filePreview.openPreview(context,previewInfo);}else{promptAction.showToast({message:该文件类型不支持预览});}}在文件管理器里用户点击文件时先判断是否支持预览支持的话直接打开预览页面。filePath.split(/).pop()是从文件路径里提取文件名比如从/data/files/document.pdf提取出document.pdf。下载管理器// 下载完成后预览文件asyncfunctiononDownloadComplete(filePath:string,fileName:string){letcontextgetContext(this);leturifileUri.getUriFromPath(filePath);letcanPreviewawaitfilePreview.canPreview(context,uri);if(canPreview){letpreviewInfo:filePreview.PreviewInfo{title:fileName,uri:uri,mimeType:getMimeType(fileName)};filePreview.openPreview(context,previewInfo);}}functiongetMimeType(fileName:string):string{letextfileName.split(.).pop()?.toLowerCase()||;letmimeMap:Recordstring,string{txt:text/plain,html:text/html,htm:text/html,png:image/png,jpg:image/jpeg,jpeg:image/jpeg,gif:image/gif,mp4:video/mp4,mp3:audio/mpeg};returnmimeMap[ext]||application/octet-stream;}在下载管理器里文件下载完成后可以直接调用预览服务让用户查看文件内容。getMimeType函数根据文件扩展名自动判断 MIME 类型这样你就不需要手动指定了。application/octet-stream是默认的 MIME 类型表示二进制文件。如果文件扩展名不在映射表里就用这个默认值。预览服务可能会根据文件内容自动判断类型。聊天应用// 聊天应用中预览收到的文件asyncfunctionpreviewReceivedFile(fileUri:string,fileName:string){letcontextgetContext(this);letcanPreviewawaitfilePreview.canPreview(context,fileUri);if(canPreview){letpreviewInfo:filePreview.PreviewInfo{title:fileName,uri:fileUri,mimeType:getMimeTypeFromName(fileName)};filePreview.openPreview(context,previewInfo);}else{promptAction.showToast({message:请下载后查看});}}在聊天应用里收到文件时可以直接预览不需要先下载到本地。这样用户可以快速查看文件内容决定是否需要下载。适用场景文件预览服务适合以下场景文件管理器文件内容预览下载管理器下载文件预览聊天应用聊天文件预览办公应用文档预览媒体应用图片、视频、音频预览注意事项文件格式不是所有文件格式都支持预览要先调用canPreview判断MIME 类型要正确设置文件的 MIME 类型否则可能无法正确预览文件路径文件要在应用的沙箱目录下或者有访问权限大文件预览大文件时可能会有加载时间要做好用户体验比如加个 loading 提示错误处理预览可能会失败文件损坏、格式不支持等要做好错误处理总结文件预览服务让你的应用轻松预览各种文件核心流程导入文件预览服务模块获取文件路径和 URI调用canPreview判断文件是否可预览创建PreviewInfo对象设置标题、URI、MIME 类型调用openPreview打开预览掌握了这些你就能让你的应用支持各种文件的预览功能提升用户体验。