目录

File Preview

The file preview function of Preview Kit is implemented by launching a new window. The file to be previewed is displayed in this window using a standardized UI design. If you intend to use this feature, take note of the following considerations:

API Description

The APIs use either a callback or promise to return the result. They two return values in different ways, but provide the same functions. For details about the APIs, please refer to the API reference.

Table 1 Preview Kit APIs

API Description
openPreview(context: Context, file: PreviewInfo, info?: DisplayInfo): Promise<void> Enables the preview function. This API displays the preview window based on the preview information of a single file and floating window attributes. Calling this API repeatedly within 1 second will not take effect. This API uses a promise to return the result.
openPreview(context: Context, file: PreviewInfo, info: DisplayInfo, callback: AsyncCallback<void>): void Enables the preview function. This API displays the preview window based on the preview information of a single file and floating window attributes. Calling this API repeatedly within 1 second will not take effect. This API uses an asynchronous callback to return the result.
openPreview(context: Context, files: Array<PreviewInfo>, index?: number): Promise<void> Enables the preview function. This API displays the preview window based on the preview information of multiple files and selected file information subscripts. Calling this API repeatedly within 1 second will not take effect. This API uses a promise to return the result. It is available only on mobile devices.
canPreview(context: Context, uri: string): Promise<boolean>

Checks whether a file or folder can be previewed based on the URI.

- If the URI of a file that supports preview and exists is passed, true will be returned. (Supported file types include images, videos, audio, text, and HTML.)

- If the URI of a file that cannot be previewed is passed, false will be returned.
hasDisplayed(context: Context): Promise<boolean>

Checks whether a preview window already exists. The preview window is implemented as a singleton.

- If the preview window has been opened and is not closed, true will be returned.

- If the preview window has not been opened or has been closed after being opened, false will be returned.
closePreview(context: Context): Promise<void> Closes the preview window and takes effect only when a preview window exists.
loadData(context: Context, file: PreviewInfo): Promise<void>

Loads information about the file to be previewed. This API can take effect only when a preview window exists. Calling this API repeatedly within 100 milliseconds will not take effect.

- If a file that can be previewed is passed, the preview page will be displayed.

- If a file that cannot be previewed is passed, a message will be displayed, indicating that file preview is not supported.

Development Procedure

  1. Import required modules.

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

  2. Check whether a file can be previewed.

    let uiContext = this.getUIContext().getHostContext() as Context;
let uri = fileUri.getUriFromPath(uiContext.filesDir + '/1.txt');
filePreview.canPreview(uiContext, uri).then((result) => { // If the file supports preview and it exists, true will be returned.
  hilog.info(0x0000, 'FilePreview',
    `Succeeded in obtaining the result of whether it can be previewed. result = ${result}`);
  // ...
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'FilePreview',
    `Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
});

  3. Call openPreview to enable the file preview function.

    • Open a file using a 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: fileUri.getUriFromPath(uiContext.filesDir + '/1.txt'),
  mimeType: 'text/plain'
};
filePreview.openPreview(uiContext, fileInfo, displayInfo).then(() => {
  hilog.info(0x0000, 'FilePreview', 'Succeeded in opening preview');
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'FilePreview',
    `Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
});
    • Open a file using a 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: fileUri.getUriFromPath(uiContext.filesDir + '/1.txt'),
  mimeType: 'text/plain'
};
filePreview.openPreview(uiContext, fileInfo, displayInfo, (err) => {
  if (err && err.code) {
    hilog.error(0x0000, 'FilePreview',
      `Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
    return;
  }
  hilog.info(0x0000, 'FilePreview', 'Succeeded in opening preview');
});
    • Pass multiple files for preview. Only available on mobile devices.
    let uiContext = this.getUIContext().getHostContext() as Context;
// ...
let fileInfo: filePreview.PreviewInfo = {
  title: '1.txt',
  uri: fileUri.getUriFromPath(uiContext.filesDir + '/1.txt'),
  mimeType: 'text/plain'
};
let fileInfo1: filePreview.PreviewInfo = {
  title: '2.txt',
  uri: fileUri.getUriFromPath(uiContext.filesDir + '/2.txt'),
  mimeType: 'text/plain'
};
let files: filePreview.PreviewInfo[] = [];
files.push(fileInfo);
files.push(fileInfo1);
// Preview multiple files. Currently, this function is available only on mobile devices and is unavailable on PCs and 2-in-1 devices (error code 801 is returned).
filePreview.openPreview(uiContext, files, 0).then(() => {
  hilog.info(0x0000, 'FilePreview', 'Succeeded in opening preview');
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'FilePreview',
    `Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
});

  4. (Optional) If the preview window has been opened and the page needs to be reloaded, call the loadData API for file loading.

    let uiContext = this.getUIContext().getHostContext() as Context;
let fileInfo: filePreview.PreviewInfo = {
  title: '2.txt',
  uri: fileUri.getUriFromPath(uiContext.filesDir + '/2.txt'),
  mimeType: 'text/plain'
};
filePreview.loadData(uiContext, fileInfo).then(() => { // Take effect only when a preview window exists.
  hilog.info(0x0000, 'FilePreview', 'Succeeded in loading data.');
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'FilePreview', `Failed to load data, err.code = ${err.code}, err.message = ${err.message}`);
});

  5. (Optional) To close the preview window, call closePreview.

    let uiContext = this.getUIContext().getHostContext() as Context;
filePreview.closePreview(uiContext).then(() => { // Take effect only when a preview window exists.
  hilog.info(0x0000, 'FilePreview', 'Succeeded in closing preview');
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'FilePreview',
    `Failed to close preview, err.code = ${err.code}, err.message = ${err.message}`);
});