文件打开加速状态感知（已废弃）
===============

从5.0.5(17)版本开始，如浏览器等支持下载文件的应用，可以接入文件预加载状态感知接口，动态感知文件预加载状态，通过UI（user interface）标识对加速文件进行显性化提示，进一步提升用户体验。

从26.0.0版本开始，文件打开加速状态感知能力已废弃。

#### 接口说明

具体API说明详见[预加载状态感知接口文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/preview-arkts-openfileboost-api)。

**表1** 文件预加载状态感知接口介绍（ArkTS API）

| 接口名 | 描述 |
| :-- | :-- |
| on(type: 'filePreloadStateChanged', callback: Callback<FilePreloadStatusInfo>): void | 文件预加载状态回调，应用通过注册回调函数获取文件预加载的状态变化。 |
| off(type: 'filePreloadStateChanged', callback?: Callback<FilePreloadStatusInfo>): void | 文件预加载状态注销回调，通过注销回调函数取消获取文件预加载的状态变化。 |
| addFile(file: string): void | 
监听一个文件的预加载状态，传入文件路径开始监听该文件的预加载状态。后续该文件状态有变化通过'filePreloadStateChanged'事件回调应用。

注意需要先调用openFileBoost.on('filePreloadStateChanged')接口后再调用该接口添加文件。

当前支持加速的文件类型见[文件打开加速支持的文件类型](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/preview-introduction#文件打开加速支持的文件类型)， 不支持的文件类型默认为未预加载状态，不需要调用该接口监听文件预加载状态变更。

 |
| removeFile(file: string): void | 取消监听一个文件的预加载状态，取消后文件的预加载状态变化不会通过回调再通知业务。 |
| queryFilePreloadStatusInfo(file: string): FilePreloadStatusInfo | 查询文件预加载状态，传入文件路径，通过返回值返回该文件当前的预加载状态。 |

#### 开发准备

需要先通过[Syscap](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/syscap#使用caniuse判断syscap是否可调用)查询您的目标设备是否支持SystemCapability.PCService.OpenFileBoost系统能力，当前仅在PC/2in1设备上支持该能力。

#### 开发步骤

1.  导入相关模块。
    
    import { openFileBoost } from '@kit.PreviewKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
2.  注册文件预加载状态感知回调函数。
    
    // 文件预加载状态变更的回调函数定义，若有文件预加载状态变更，则通过该回调函数通知
    function callback(filePreloadStatusInfo: openFileBoost.FilePreloadStatusInfo): void {
      if (filePreloadStatusInfo.state === openFileBoost.FilePreloadState.PRELOADING) {
        // 预加载过程中，应用可以根据自己设计对应UX
        hilog.info(0x0000, 'testTag', \`file is PRELOADING, suggest to show loading animation\`);
      }
      if (filePreloadStatusInfo.state === openFileBoost.FilePreloadState.PRELOADED) {
        // 预加载完成，应用可以通过UX显示提示用户加速完成
        hilog.info(0x0000, 'testTag', \`file is PRELOADED, suggest to show loaded animation\`);
      }
      if (filePreloadStatusInfo.state === openFileBoost.FilePreloadState.NOT\_PRELOADED) {
        // 没有预加载，应用可以不显示任何额外UX
        hilog.info(0x0000, 'testTag', \`file is UNPRELOADED, suggest do not show animation \`);
      }
    }
    // 调用register函数可以注册预加载状态感知回调
    function register(): void {
      try {
        openFileBoost.on('filePreloadStateChanged', callback);
      } catch(error) {
        let code = (error as BusinessError).code;
        let message = (error as BusinessError).message;
        hilog.error(0x0000, 'testTag', \`register filePreloadStateChanged failed, error code: ${code}, message: ${message}.\`);
      }
    }
    
3.  调用addFile接口传入想要监听的文件的沙箱路径。典型场景比如应用下载某个文件完成，可将该文件路径注册进来，若文件后续状态变更，系统会通过2中的回调函数通知应用。
    
    // 为10MB\_file.docx文件添加文件预加载状态监听
    function testAddFile(): void {
      try {
        const file:string = "/storage/Users/currentUser/Desktop/10MB\_file.docx";
        openFileBoost.addFile(file);
      } catch(error) {
        let code = (error as BusinessError).code;
        let message = (error as BusinessError).message;
        hilog.error(0x0000, 'testTag', \`addFile failed, error code: ${code}, message: ${message}.\`);
      }
    }
    
4.  通过addFile接口监听的文件个数有上限（50个文件），不再需要监听的文件可以通过removeFile接口取消监听。
    
    const file:string = "/storage/Users/currentUser/Desktop/10MB\_file.docx";
    try {
      openFileBoost.removeFile(file);
    } catch(error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      hilog.error(0x0000, 'testTag', \`removeFile failed, error code: ${code}, message: ${message}.\`);
    }
    
5.  如果不需要再监听任何文件的预加载状态变更，可注销预加载状态感知回调函数。如果传入具体的回调函数，则只取消该函数； 如果不传入具体的回调函数，则取消该进程的所有回调。
    
    // 假设之前在进程的不同业务逻辑中已经注册了callback1、callback2、callback3总共3个回调函数
    openFileBoost.on('filePreloadStateChanged', callback1);
    openFileBoost.on('filePreloadStateChanged', callback2);
    openFileBoost.on('filePreloadStateChanged', callback3);
    
    function testUnregister(): void {
      try {
        // 单独取消callback1的监听，传入callback1作为参数，后续不会再调用callback1的回调做通知
        openFileBoost.off('filePreloadStateChanged', callback1);
        // 取消所有callback的监听，不传第二个可选参数，后续不会再调用callback2和callback3做通知
        openFileBoost.off('filePreloadStateChanged');
      } catch(error) {
        let code = (error as BusinessError).code;
        let message = (error as BusinessError).message;
        hilog.error(0x0000, 'testTag', \`off filePreloadStateChanged failed, error code: ${code}, message: ${message}.\`);
      }
    }
    
6.  应用还可通过查询接口查询某个文件的实时的预加载状态，一般在应用刚启动时可以查询一遍相关文件的预加载状态。每次调用接口传入一个文件的沙箱路径。
    
    function testQuery(): void {
    try {
      const file:string = "/storage/Users/currentUser/Desktop/10MB\_file.docx";
      let statusInfo : openFileBoost.FilePreloadStatusInfo = openFileBoost.queryFilePreloadStatusInfo(file);
      hilog.info(0x0000, 'testTag', 'file, %{public}s, progress:%{public}d  preloadState:%{public}d',
        statusInfo.sandboxPath, statusInfo.progress, statusInfo.state);
    } catch(error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      hilog.error(0x0000, 'testTag', \`query failed, error code: ${code}, message: ${message}.\`);
    }
    }