文件预览

当前Preview Kit的文件预览能力采用拉起新窗口的方式来实现，在新的窗口中展示需要预览的文件，并按照统一设计的界面进行展示，如果开发者需要使用Preview Kit的文件预览能力，需要注意以下事项：

• 当前Preview Kit仅支持跳出应用进行文件的预览，暂不支持应用内预览。
• Office类型文档预览借助WPS提供的能力来实现，在预览文档类型文件时会存在“WPS提供技术支持”、“使用WPS Office打开”等相关字样。
• 当前Preview Kit暂不支持安全定制能力，包括禁止截录屏、屏蔽其他应用打开入口、屏蔽分享入口等安全预览能力。
• 当前Preview Kit需要调用方存在对应uri的转授权能力，从而让预览获得该文件的访问权限来正常读取文件，具体问题可以参考Preview Kit常见问题2。

接口说明

接口返回值有两种返回形式：callback和promise，promise和callback只是返回值方式不一样，功能相同。具体API说明详见接口文档。

表1 Preview Kit的接口介绍

接口名	描述
openPreview(context: Context, file: PreviewInfo, info?: DisplayInfo): Promise<void>	打开预览功能。通过传入单个文件预览信息以及悬浮窗口属性信息，打开预览窗口。1秒内重复调用无效。使用Promise方式异步返回结果。
openPreview(context: Context, file: PreviewInfo, info: DisplayInfo, callback: AsyncCallback<void>): void	打开预览功能。通过传入单个文件预览信息以及悬浮窗口属性信息，打开预览窗口。1秒内重复调用无效。传入callback进行异步回调。
openPreview(context: Context, files: Array<PreviewInfo>, index?: number): Promise<void>	打开预览功能。通过传入多个文件预览信息以及选择展示的文件信息下标，打开预览窗口。1秒内重复调用无效。使用Promise方式异步返回结果。仅移动端可用。
canPreview(context: Context, uri: string): Promise<boolean>	根据文件的uri判断文件是否可预览。 - 当传入支持的文件类型（图片、视频、音频、文本、html）并且文件存在时，会返回true。 - 当传入不可预览的文件uri时，返回false。
hasDisplayed(context: Context): Promise<boolean>	判断预览窗口是否已经存在。预览窗口是单例的形式。 - 如果预览窗口已经打开过并且没关闭，那会返回true。 - 如果没打开或者打开后已关闭，那将返回false。
closePreview(context: Context): Promise<void>	关闭预览窗口，仅当预览窗口存在时起效。
loadData(context: Context, file: PreviewInfo): Promise<void>	加载预览文件信息。仅当预览窗口存在时生效。100毫秒内重复调用无效。 - 传入可预览文件时展示对应预览界面。 - 传入不可预览文件显示不支持预览界面。

开发步骤

1. 导入相关模块。

   import { filePreview } from '@kit.PreviewKit';
   import { BusinessError } from '@kit.BasicServicesKit';

2. 判断是否可以预览。

   let uri = 'file://docs/storage/Users/currentUser/Documents/1.txt';
   let uiContext = this.getUIContext().getHostContext() as Context;
   filePreview.canPreview(uiContext, uri).then((result) => {    // 传入支持的文件类型且文件存在时会返回true
     console.info(`Succeeded in obtaining the result of whether it can be previewed. result = ${result}`);
   }).catch((err: BusinessError) => {
     console.error(`Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
   });

3. 调用openPreview，实现打开文件预览的功能。

   • 通过Promise方式打开文件

     let uiContext = this.getUIContext().getHostContext() as Context;
     let displayInfo: filePreview.DisplayInfo = {
       x: 100,
       y: 100,
       width: 800,
       height: 800
     };
     let fileInfo: filePreview.PreviewInfo = {
       title: '1.txt',
       uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
       mimeType: 'text/plain'
     };
     filePreview.openPreview(uiContext, fileInfo, displayInfo).then(() => {
       console.info('Succeeded in opening preview');
     }).catch((err: BusinessError) => {
       console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
     });

   • 通过CallBack回调函数方式打开文件

     let uiContext = this.getUIContext().getHostContext() as Context;
     let displayInfo: filePreview.DisplayInfo = {
       x: 100,
       y: 100,
       width: 800,
       height: 800
     };
     let fileInfo: filePreview.PreviewInfo = {
       title: '1.txt',
       uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
       mimeType: 'text/plain'
     };
     filePreview.openPreview(uiContext, fileInfo, displayInfo, (err) => {
       if (err && err.code) {
         console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
         return;
       }
       console.info('Succeeded in opening preview');
     });

   • 传入多个文件打开预览，仅移动端可用。

     let uiContext = this.getUIContext().getHostContext() as Context;
     let fileInfo: filePreview.PreviewInfo = {
       title: '1.txt',
       uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
       mimeType: 'text/plain'
     };
     let fileInfo1: filePreview.PreviewInfo = {
       title: '2.txt',
       uri: 'file://docs/storage/Users/currentUser/Documents/2.txt',
       mimeType: 'text/plain'
     };
     let files: Array<filePreview.PreviewInfo> = new Array();
     files.push(fileInfo);
     files.push(fileInfo1);
     filePreview.openPreview(uiContext, files, 0).then(() => {
       console.info('Succeeded in opening preview');
     }).catch((err: BusinessError) => {
       console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
     });

4. （可选）如果已经打开过预览窗口，需要重新加载页面，需要调用loadData接口，加载文件。

   let uiContext = this.getUIContext().getHostContext() as Context;
   let fileInfo: filePreview.PreviewInfo = {
     title: '2.txt',
     uri: 'file://docs/storage/Users/currentUser/Documents/2.txt',
     mimeType: 'text/plain'
   };
   filePreview.loadData(uiContext, fileInfo).then(() => {   // 仅当预览窗口存在时起效
     console.info('Succeeded in loading data.');
   }).catch((err: BusinessError) => {
     console.error(`Failed to load data, err.code = ${err.code}, err.message = ${err.message}`);
   });

5. （可选）如果想要关闭预览窗口，需要调用closePreview。

   let uiContext = this.getUIContext().getHostContext() as Context;
   filePreview.closePreview(uiContext).then(() => {   // 仅当预览窗口存在时起效
     console.info('Succeeded in closing preview');
   }).catch((err: BusinessError) => {
     console.error(`Failed to close preview, err.code = ${err.code}, err.message = ${err.message}`);
   });