HarmonyOS 文件预览服务避坑指南：从入门到实战

一、背景介绍

Preview Kit（文件预览服务）用于在应用中预览文件内容。相比自行编写解析器或集成第三方 SDK，使用系统自带服务具有无需额外付费、支持格式广泛、用户体验流畅等优势。

支持的文件类型

类型	后缀	备注
图片	jpg, png, gif, webp, bmp, svg	基础支持
视频	mp4, mkv, ts	常见格式
音频	m4a, aac, mp3, ogg, wav	播放支持
文本	txt, cpp, c, h, java, xml	代码查看
网页	html, htm	内嵌预览
PDF	pdf	常用格式
Office	doc, docx, xls, xlsx, ppt, pptx, csv, ofd	依赖 WPS 能力

注意：Office 文档预览借助 WPS 能力，界面可能显示技术支持标识。

二、架构概述

Preview Kit 架构分为三层：应用层调用接口、Preview Kit 服务层解析渲染、系统/WPS 底层能力。 工作流程：调用 openPreview 传入文件 URI -> 检查类型 -> 渲染模态窗 -> 用户操作。

三、核心功能实现

3.1 基础预览

import { preview } from '@kit.PreviewKit';
const fileUri = 'file://com.example.app/files/test.docx';
preview.openPreview({ uri: fileUri }).then(() => {
  console.info('预览打开成功');
}).catch((err) => {
  console.error('预览打开失败', err);
});

3.2 预览能力判断

import { preview } from '@kit.PreviewKit';
preview.canPreview({ : fileUri }).( {
   (result) {
    preview.({ : fileUri });
  }  {
    
  }
});