输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
指南与API参考API参考应用服务Preview Kit（文件预览服务）ArkTS APIfilePreview（文件预览）

filePreview（文件预览）

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
更新时间: 2026-08-29 09:41
复制页面
本文导读
展开章节

本模块为应用提供便捷的文件快速预览能力。应用可以通过文件预览提供的系统级预览API，可快速启动预览界面，实现对各类文件的预览。通过预览服务，用户可以对文件（包括图片，视频，音频，文本、html等）进行操作。

本模块提供接入文件快速预览的能力，可通过传递文件信息快速打开预览窗口。

支持的预览文件类型如下：

展开
类型 文件后缀 mimeType类型
文本 txt、cpp、c、h、java、xhtml、xml text/plain、text/x-c++src、text/x-csrc、text/x-chdr、text/x-java、application/xhtml+xml、text/xml
网页 html、htm text/html
图片 jpg、png、gif、webp、bmp、svg image/jpeg、image/png、image/gif、image/webp、image/bmp、image/svg+xml
音频 m4a、aac、mp3、ogg、wav audio/mp4a-latm、audio/aac、audio/mpeg、audio/ogg、audio/x-wav
视频 mp4、mkv、ts video/mp4、video/x-matroska、video/mp2ts
文件夹 无 无
文档 pdf

application/pdf

起始版本： 5.0.0(12)
Office文档 doc、docx、xls、xlsx、ppt、pptx、csv、ofd

application/msword、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.ms-excel、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.ms-powerpoint、application/vnd.openxmlformats-officedocument.presentationml.presentation、text/csv、general.ofd

起始版本： 5.0.0(12)

起始版本： 4.1.0(11)

导入模块

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';

PreviewInfo

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

文件预览信息，包含了文件标题名、uri以及文件类型（mimeType）。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

展开
名称 类型 只读 可选 说明
title string 否 是 文件的标题名称
uri string 否 否 文件的uri
mimeType string 否 否

文件的媒体资源类型，如text/plain。

说明：

若无法确定文件格式，该项可直接赋值空字符串（""），系统会通过uri后缀进行文件格式判断。

DisplayInfo

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

悬浮窗口的属性值，包含了悬浮窗大小以及位置信息。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

展开
名称 类型 只读 可选 说明
x number 否 否 预览窗口的起始X轴，单位px
y number 否 否 预览窗口的起始Y轴，单位px
width number 否 是 预览窗口的宽度，单位px
height number 否 是 预览窗口的高度，单位px

openPreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

openPreview(context: Context, file: PreviewInfo, info?: DisplayInfo): Promise<void>

通过传入文件预览信息以及悬浮窗口属性信息，打开预览窗口。1秒内重复调用无效。使用Promise方式异步回调。

该接口需要调用方确认传入的uri可进行转授权。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
file PreviewInfo 是 文件的预览信息，title为可选，不填会通过uri解析，无法解析则显示未知文件。
info DisplayInfo 否 模态窗口的窗口展示信息，PC/2in1端不填写则展示默认大小窗口，Phone、Tablet填写无效。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4. let uiContext = this.getUIContext().getHostContext() as Context;
  5. // 设置窗口展示信息
  6. let displayInfo: filePreview.DisplayInfo = {
  7.   x: 100,
  8.   y: 100,
  9.   width: 800,
  10.   height: 800
  11. };
  12. // 设置文件预览信息
  13. let fileInfo: filePreview.PreviewInfo = {
  14.   title: '1.txt',
  15.   uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
  16.   mimeType: 'text/plain'
  17. };
  18. filePreview.openPreview(uiContext, fileInfo, displayInfo).then(() => {
  19.   console.info('Succeeded in opening preview');
  20. }).catch((err: BusinessError) => {
  21.   console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
  22. });

openPreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

openPreview(context: Context, file: PreviewInfo, info: DisplayInfo, callback: AsyncCallback<void>): void

通过传入文件预览信息以及悬浮窗口属性信息，打开预览窗口。1秒内重复调用无效。使用Callback回调异步返回结果。

该接口需要调用方确认传入的uri可进行转授权。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
file PreviewInfo 是 文件的预览信息，title为可选，不填写时会通过uri解析，无法解析则显示未知文件。
info DisplayInfo 是 模态窗口的窗口展示信息，手机和平板设备填写无效。
callback AsyncCallback<void> 是 回调函数。当预览窗口成功打开时，err为undefined或err.code为0，否则为错误对象。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. let uiContext = this.getUIContext().getHostContext() as Context;
  4. // 设置窗口展示信息
  5. let displayInfo: filePreview.DisplayInfo = {
  6.   x: 100,
  7.   y: 100,
  8.   width: 800,
  9.   height: 800
  10. };
  11. // 设置文件预览信息
  12. let fileInfo: filePreview.PreviewInfo = {
  13.   title: '1.txt',
  14.   uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
  15.   mimeType: 'text/plain'
  16. };
  17. filePreview.openPreview(uiContext, fileInfo, displayInfo, (err) => {
  18.   if (err && err.code) {
  19.     console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
  20.     return;
  21.   }
  22.   console.info('Succeeded in opening preview');
  23. });

openPreview

Phone5.0.0(12)+Tablet5.0.0(12)+

openPreview(context: Context, files: Array<PreviewInfo>, index?: number): Promise<void>

通过传入多个文件预览信息以及选择展示的文件信息下标，打开预览窗口。1秒内重复调用无效。使用Promise方式异步回调。

该接口需要调用方确认传入的uri可进行转授权。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

设备行为差异： 此接口在PC/2in1中调用返回801错误码，在其他设备类型中可正常调用。

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
files Array<PreviewInfo> 是 文件预览信息列表。
index number 否 预览窗口打开时展示的文件预览信息下标，不填默认为0。取值范围大于等于0，小于files长度。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.
801 Capability not supported.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4. let uiContext = this.getUIContext().getHostContext() as Context;
  5. // 创建单个文件的预览信息
  6. let fileInfo: filePreview.PreviewInfo = {
  7.   title: '1.txt',
  8.   uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
  9.   mimeType: 'text/plain'
  10. };
  11. // 创建多文件查看数组
  12. let files: Array<filePreview.PreviewInfo> = new Array();
  13. files.push(fileInfo);
  14. filePreview.openPreview(uiContext, files, 0).then(() => {
  15.   console.info('Succeeded in opening preview');
  16. }).catch((err: BusinessError) => {
  17.   console.error(`Failed to open preview, err.code = ${err.code}, err.message = ${err.message}`);
  18. });

canPreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

canPreview(context: Context, uri: string): Promise<boolean>

根据文件的uri判断文件是否可预览，当传入支持的文件uri时，会返回true；传入不可预览的文件uri时，返回false。使用Promise方式异步回调。

当前接口仅针对文件是否存在以及文件格式是否为支持的文件类型进行检验，后续openPreview进行文件查看时需要调用方保证文件可以被转授权。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
uri string 是 文件uri

返回值：

展开
类型 说明
Promise<boolean> Promise对象，当传入支持的文件uri时，会返回true；传入不可预览的文件uri时，返回false。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4.  // e.g 文件存在且类型符合时
  5. let uri = 'file://docs/storage/Users/currentUser/Documents/1.txt';
  6. let uiContext = this.getUIContext().getHostContext() as Context;
  7. filePreview.canPreview(uiContext, uri).then((result) => { // 此处返回true
  8.   console.info(`Succeeded in obtaining the result of whether it can be previewed. result = ${result}`);
  9. }).catch((err: BusinessError) => {
  10.   console.error(`Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
  11. })
收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4. // e.g 文件不存在或文件类型不符合时
  5. let uri = 'file://docs/storage/Users/currentUser/Documents/1.txt';
  6. let uiContext = this.getUIContext().getHostContext() as Context;
  7. filePreview.canPreview(uiContext, uri).then((result) => { // 此处返回false
  8.   console.info(`Succeeded in obtaining the result of whether it can be previewed. result = ${result}`);
  9. }).catch((err: BusinessError) => {
  10.   console.error(`Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
  11. });

canPreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

canPreview(context: Context, uri: string, callback: AsyncCallback<boolean>): void

根据文件的uri判断文件是否可预览，当传入支持的文件uri时，会返回true；传入不可预览的文件uri时，返回false。使用Callback回调异步返回结果。

当前接口仅针对文件是否存在以及文件格式是否为支持的文件类型进行检验，后续openPreview进行文件查看时需要调用方保证文件可以被转授权。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
uri string 是 文件uri
callback AsyncCallback<boolean> 是 回调函数。当传入支持的文件uri时，会返回true；传入不可预览的文件uri时，返回false。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. // e.g 文件存在且类型符合时
  4. let uri = 'file://docs/storage/Users/currentUser/Documents/1.txt';
  5. let uiContext = this.getUIContext().getHostContext() as Context;
  6. filePreview.canPreview(uiContext, uri, (err, result) => {
  7.   if (err && err.code) {
  8.     console.error(`Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
  9.     return;
  10.   }
  11.   console.info(`Succeeded in obtaining the result of whether it can be previewed. result = ${result}`); // 此处返回true
  12. });
收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. // e.g 文件不存在或文件类型不符合时
  4. let uri = 'file://docs/storage/Users/currentUser/Documents/9.txt';
  5. let uiContext = this.getUIContext().getHostContext() as Context;
  6. filePreview.canPreview(uiContext, uri, (err, result) => {
  7.   if (err && err.code) {
  8.     console.error(`Failed to obtain the result of whether it can be previewed, err.code = ${err.code}, err.message = ${err.message}`);
  9.     return;
  10.   }
  11.   console.info(`Succeeded in obtaining the result of whether it can be previewed. result = ${result}`); // 此处返回false
  12. });

hasDisplayed

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

hasDisplayed(context: Context): Promise<boolean>

判断预览窗口是否已经存在。预览窗口是单例的形式，如果预览窗口已经打开过并且没关闭，那会返回true。如果没打开或者打开后已关闭，那将返回false。使用Promise方式异步回调。判断是否已打开预览需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用hasDisplayed接口会导致结果返回false。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。

返回值：

展开
类型 说明
Promise<boolean> Promise对象，预览窗口是单例的形式，当预览窗口已经打开过并且没关闭，那会返回true。如果没打开或者打开后已关闭，那将返回false。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4. // e.g 预览窗口已存在
  5. let uiContext = this.getUIContext().getHostContext() as Context;
  6. filePreview.hasDisplayed(uiContext).then((result) => { // 此处返回true
  7.   console.info(`Succeeded in obtaining the result of whether the preview has displayed. result = ${result}`);
  8. }).catch((err: BusinessError) => {
  9.   console.error(`Failed to obtain the result of whether the preview has displayed, err.code = ${err.code}, err.message = ${err.message}`);
  10. });
收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4.  // e.g 预览窗口不存在
  5. let uiContext = this.getUIContext().getHostContext() as Context;
  6. filePreview.hasDisplayed(uiContext).then((result) => { // 此处返回false
  7.   console.info(`Succeeded in obtaining the result of whether the preview has displayed. result = ${result}`);
  8. }).catch((err: BusinessError) => {
  9.   console.error(`Failed to obtain the result of whether the preview has displayed, err.code = ${err.code}, err.message = ${err.message}`);
  10. });

hasDisplayed

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

hasDisplayed(context: Context, callback: AsyncCallback<boolean>): void

判断预览窗口是否已经存在。预览窗口是单例的形式，如果预览窗口已经打开过并且没关闭，那会返回true。如果没打开或者打开后已关闭，那将返回false。使用Callback回调异步返回结果。判断是否已打开预览需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用hasDisplayed接口会导致结果返回false。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
callback AsyncCallback<boolean> 是 回调函数。预览窗口是单例的形式，当预览窗口已经打开过并且没关闭，那会返回true。如果没打开或者打开后已关闭，那将返回false。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. // e.g 预览窗口已存在
  4. let uiContext = this.getUIContext().getHostContext() as Context;
  5. filePreview.hasDisplayed(uiContext, (err, result) => {
  6.   if (err && err.code) {
  7.     console.error(`Failed to obtain the result of whether the preview has displayed, err.code = ${err.code}, err.message = ${err.message}`);
  8.     return;
  9.   }
  10.   console.info(`Succeeded in obtaining the result of whether the preview has displayed. result = ${result}`); // 此处返回true
  11. });
收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. // e.g 预览窗口不存在
  4. let uiContext = this.getUIContext().getHostContext() as Context;
  5. filePreview.hasDisplayed(uiContext, (err, result) => {
  6.   if (err && err.code) {
  7.     console.error(`Failed to obtain the result of whether the preview has displayed, err.code = ${err.code}, err.message = ${err.message}`);
  8.     return;
  9.   }
  10.   console.info(`Succeeded in obtaining the result of whether the preview has displayed. result = ${result}`); // 此处返回false
  11. });

closePreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

closePreview(context: Context): Promise<void>

关闭预览窗口，仅当预览窗口存在时起效。使用Promise方式异步回调。关闭预览窗口需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用closePreview接口会无效。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

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

closePreview

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

closePreview(context: Context, callback: AsyncCallback<void>): void

关闭预览窗口，仅当预览窗口存在时起效。使用Callback回调异步返回结果。关闭预览窗口需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用closePreview接口会无效。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
callback AsyncCallback<void> 是 回调函数。当预览窗口成功关闭时，err为undefined或err.code为0，否则为错误对象。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. let uiContext = this.getUIContext().getHostContext() as Context;
  4. filePreview.closePreview(uiContext, (err) => { // 仅当预览窗口存在时起效
  5.   if (err && err.code) {
  6.     console.error(`Failed to close preview, err.code = ${err.code}, err.message = ${err.message}`);
  7.     return;
  8.   }
  9.   console.info('Succeeded in closing preview');
  10. });

loadData

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

loadData(context: Context, file: PreviewInfo): Promise<void>

加载预览文件信息。仅当预览窗口存在时起效。传入可预览文件时展示对应预览界面，传入不可预览文件显示不支持预览界面。100毫秒内重复调用无效。使用Promise方式异步回调。加载预览文件需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用loadData接口会无效。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
file PreviewInfo 是 文件的预览信息，title为可选，不填会通过uri解析，无法解析则显示未知文件。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

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

loadData

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+

loadData(context: Context, file: PreviewInfo, callback: AsyncCallback<void>): void

加载预览文件信息。仅当预览窗口存在时起效。传入可预览文件时展示对应预览界面，传入不可预览文件显示不支持预览界面。100毫秒内重复调用无效。使用Callback回调异步返回结果。加载预览文件需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用loadData接口会无效。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

起始版本： 4.1.0(11)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
file PreviewInfo 是 文件的预览信息，title为可选，不填会通过uri解析，无法解析则显示未知文件。
callback AsyncCallback<void> 是 回调函数。当预览文件加载成功时，err为undefined或err.code为0，否则为错误对象。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.

示例：

收起
自动换行
深色代码主题
复制
  1. import { filePreview } from '@kit.PreviewKit';
  2. 

  3. let uiContext = this.getUIContext().getHostContext() as Context;
  4. let fileInfo: filePreview.PreviewInfo = {
  5.   title: '1.txt',
  6.   uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
  7.   mimeType: 'text/plain'
  8. };
  9. filePreview.loadData(uiContext, fileInfo, (err) => { // 仅当预览窗口存在时起效
  10.   if (err && err.code) {
  11.     console.error(`Failed to load data, err.code = ${err.code}, err.message = ${err.message}`);
  12.     return;
  13.   }
  14.   console.info('Succeeded in loading data.');
  15. });

loadData

Phone5.0.0(12)+Tablet5.0.0(12)+

loadData(context: Context, files: Array<PreviewInfo>, index?: number): Promise<void>

加载预览文件信息。仅当预览窗口存在时起效。可传入多个文件预览信息以及对应展示的列表下标进行选择预览。使用Promise方式异步回调。

加载预览文件需要等待窗口创建完成才能产生效果，窗口还没创建完成就调用loadData接口会无效。该接口在PC/2in1端无效。100毫秒内重复调用无效。

模型约束： 此接口仅可在Stage模型下使用。

元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.FileManagement.FilePreview.Core

设备行为差异： 此接口在PC/2in1中调用返回801错误码，在其他设备类型中可正常调用。

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
context Context 是

上下文common.UIAbilityContext。

注意：

当前context仅支持传入UIAbilityContext。
files Array<PreviewInfo> 是 文件预览信息列表。
index number 否 预览窗口打开时展示的文件预览信息下标，不填默认为0。取值范围大于等于0，小于files长度。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码： 以下错误码的详细介绍请参见通用错误码

展开
错误码ID 错误信息
401 invalid input parameter.
801 Capability not supported.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { filePreview } from '@kit.PreviewKit';
  3. 

  4. let uiContext = this.getUIContext().getHostContext() as Context;
  5. let fileInfo: filePreview.PreviewInfo = {
  6.   title: '1.txt',
  7.   uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
  8.   mimeType: 'text/plain'
  9. };
  10. let files: Array<filePreview.PreviewInfo> = new Array();
  11. files.push(fileInfo);
  12. filePreview.loadData(uiContext, files, 0).then(() => { // 仅当预览窗口存在时起效
  13.   console.info('Succeeded in loading data.');
  14. }).catch((err: BusinessError) => {
  15.   console.error(`Failed to load data, err.code = ${err.code}, err.message = ${err.message}`);
  16. });
ArkTS API
openFileBoost（文件打开加速）（已废弃）
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明