HarmonyOS4.0系统性深入开发12 卡片数据交互说明

卡片数据交互说明

ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新。

HarmonyOS4.0系统性深入开发12 卡片数据交互说明_第1张图片

接口 是否系统能力 约束
updateForm 1. 提供方调用。2. 提供方仅允许刷新自己的卡片,其他提供方的卡片无法刷新。
requestForm 1. 使用方调用。2. 仅允许刷新添加到当前使用方的卡片,添加到其他使用方的卡片无法刷新。

下面介绍卡片页面刷新的典型场景。

定时刷新和定点刷新

当前卡片框架提供了如下几种按时间刷新卡片的方式:

  • 定时刷新:表示在一定时间间隔内调用

    onUpdateForm

    的生命周期回调函数自动刷新卡片内容。可以在form_config.json配置文件的

    updateDuration

    字段中进行设置。例如,可以将刷新时间设置为每小时一次。注意:updateDuration(定时刷新)优先级比scheduledUpdateTime(定点刷新)高,配置定时刷新后,定点刷新将失效。

    {
      "forms": [
        {
          "name": "widget",
          "description": "This is a service widget.",
          "src": "./ets/widget/pages/WidgetCard.ets",
          "uiSyntax": "arkts",
          "window": {
            "designWidth": 720,
            "autoDesignWidth": true
          },
          "colorMode": "auto",
          "isDefault": true,
          "updateEnabled": true, // 使能刷新功能
          "scheduledUpdateTime": "10:30",                               
          "updateDuration": 2, // 设置卡片定时刷新的更新周期(单位为30分钟,取值为自然数)
          "defaultDimension": "2*2",
          "supportDimensions": ["2*2"]
        }
      ]
    }
    
  • 定点刷新:表示每天在某个时间点刷新,在form_config.json文件中配置,详见

    scheduledUpdateTime

    字段。例如,每天在10:30更新卡片内容。

    说明

    当同时配置了定时刷新(updateDuration)和定点刷新(scheduledUpdateTime)时,定时刷新的优先级更高。如果想要配置定点刷新,则需要将updateDuration配置为0。

    {
      "forms": [
        {
          "name": "widget",
          "description": "This is a service widget.",
          "src": "./ets/widget/pages/WidgetCard.ets",
          "uiSyntax": "arkts",
          "window": {
            "designWidth": 720,
            "autoDesignWidth": true
          },
          "colorMode": "auto",
          "isDefault": true,
          "updateEnabled": true, // 使能刷新功能
          "scheduledUpdateTime": "10:30", // 设置卡片的定点刷新的时刻
          "updateDuration": 0,
          "defaultDimension": "2*2",
          "supportDimensions": ["2*2"]
        }
      ]
    }
    
  • 下次刷新:通过setFormNextRefreshTime接口指定卡片的下一次刷新时间(最短时间5分钟),例如,在接口调用的5分钟后刷新卡片内容。

    import formProvider from '@ohos.app.form.formProvider';
    
    let formId = '123456789'; // 实际业务场景需要使用正确的formId
    try {
      // 设置过5分钟后更新卡片内容
      formProvider.setFormNextRefreshTime(formId, 5, (err, data) => {
        if (err) {
          console.error(`Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
          return;
        } else {
          console.info('Succeeded in setFormNextRefreshTimeing.');
        }
      });
    } catch (err) {
      console.error(`Failed to setFormNextRefreshTime. Code: ${err.code}, message: ${err.message}`);
    }
    

在触发定时、定点或主动刷新后,系统会调用FormExtensionAbility的onUpdateForm生命周期回调,在回调中,可以使用updateForm进行提供方刷新卡片。onUpdateForm生命周期回调参考通过FormExtensionAbility刷新卡片内容。

说明

  1. 定时刷新有配额限制,每张卡片每天最多通过定时方式触发刷新50次,定时刷新包含卡片配置项updateDuration和调用setFormNextRefreshTime两种,当达到50次配额后,无法通过定时方式再次触发刷新,刷新次数会在每天的0点重置。
  2. 当前定时刷新使用同一个计时器进行计时,因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A(每隔半小时刷新一次)在3点20分添加成功,定时器启动并每隔半小时触发一次事件,第二张卡片B(每隔半小时刷新一次)在3点40分添加成功,在3点50分定时器事件触发时,卡片A触发定时刷新,卡片B会在下次事件(4点20分)中才会触发。
  3. 定时刷新和定点刷新仅在屏幕亮屏情况下才会触发,在灭屏场景下仅会将记录刷新动作,待亮屏时统一进行刷新。

刷新本地图片和网络图片

在卡片上通常需要展示本地图片或从网络上下载的图片,获取本地图片和网络图片需要通过FormExtensionAbility来实现,如下示例代码介绍了如何在卡片上显示本地图片和网络图片。

  1. 下载网络图片需要使用到网络能力,需要申请ohos.permission.INTERNET权限,配置方式请参见配置文件权限声明。

  2. 在EntryFormAbility中的onAddForm生命周期回调中实现本地文件的刷新。

    import formBindingData from '@ohos.app.form.formBindingData';
    import formProvider from '@ohos.app.form.formProvider';
    import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
    import request from '@ohos.request';
    import fs from '@ohos.file.fs';
    
    export default class EntryFormAbility extends FormExtensionAbility {
      ...
      // 在添加卡片时,打开一个本地图片并将图片内容传递给卡片页面显示
      onAddForm(want) {
        // 假设在当前卡片应用的tmp目录下有一个本地图片:head.PNG
        let tempDir = this.context.getApplicationContext().tempDir;
        // 打开本地图片并获取其打开后的fd
        let file;
        try {
          file = fs.openSync(tempDir + '/' + 'head.PNG');
        } catch (e) {
          console.error(`openSync failed: ${JSON.stringify(e)}`);
        }
        let formData = {
          'text': 'Image: Bear',
          'imgName': 'imgBear',
          'formImages': {
            'imgBear': file.fd
          },
          'loaded': true
        }
        // 将fd封装在formData中并返回至卡片页面
        return formBindingData.createFormBindingData(formData);
      }
    
      ...
    }
    
  3. 在EntryFormAbility中的onFormEvent生命周期回调中实现网络文件的刷新。

    import formBindingData from '@ohos.app.form.formBindingData';
    import formProvider from '@ohos.app.form.formProvider';
    import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
    import request from '@ohos.request';
    import fs from '@ohos.file.fs';
    
    export default class EntryFormAbility extends FormExtensionAbility {
      // 在卡片页面触发message事件时,下载一个网络图片,并将网络图片内容传递给卡片页面显示
      onFormEvent(formId, message) {
        let formInfo = formBindingData.createFormBindingData({
          'text': '刷新中...'
        })
        formProvider.updateForm(formId, formInfo)
        // 注意:FormExtensionAbility在触发生命周期回调时被拉起,仅能在后台存在5秒
        // 建议下载能快速下载完成的小文件,如在5秒内未下载完成,则此次网络图片无法刷新至卡片页面上
        let netFile = 'https://xxxx/xxxx.png'; // 需要在此处使用真实的网络图片下载链接
        let tempDir = this.context.getApplicationContext().tempDir;
        let tmpFile = tempDir + '/file' + Date.now();
        request.downloadFile(this.context, {
          url: netFile, filePath: tmpFile
        }).then((task) => {
          task.on('complete', function callback() {
            console.info('ArkTSCard download complete:' + tmpFile);
            let file;
            try {
              file = fs.openSync(tmpFile);
            } catch (e) {
              console.error(`openSync failed: ${JSON.stringify(e)}`);
            }
            let formData = {
              'text': 'Image: Https',
              'imgName': 'imgHttps',
              'formImages': {
                'imgHttps': file.fd
              },
              'loaded': true
            }
            let formInfo = formBindingData.createFormBindingData(formData)
            formProvider.updateForm(formId, formInfo).then((data) => {
              console.info('FormAbility updateForm success.' + JSON.stringify(data));
            }).catch((error) => {
              console.error('FormAbility updateForm failed: ' + JSON.stringify(error));
            })
          })
          task.on('fail', function callBack(err) {
            console.info('ArkTSCard download task failed. Cause:' + err);
            let formInfo = formBindingData.createFormBindingData({
              'text': '刷新失败'
            })
            formProvider.updateForm(formId, formInfo)
          });
        }).catch((err) => {
          console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
        });
      }
    
      ...
    };
    
  4. 在卡片页面通过Image组件展示EntryFormAbility传递过来的卡片内容。

    let storage = new LocalStorage();
    
    @Entry(storage)
    @Component
    struct WidgetCard {
      @LocalStorageProp('text') text: string = '加载中...';
      @LocalStorageProp('loaded') loaded: boolean = false;
      @LocalStorageProp('imgName') imgName: string = 'name';
    
      build() {
        Column() {
          Text(this.text)
            .fontSize('12vp')
            .textAlign(TextAlign.Center)
            .width('100%')
            .height('15%')
    
          Row() {
            if (this.loaded) {
              Image('memory://' + this.imgName)
                .width('50%')
                .height('50%')
                .margin('5%')
            } else {
              Image('common/start.PNG')
                .width('50%')
                .height('50%')
                .margin('5%')
            }
          }.alignItems(VerticalAlign.Center)
          .justifyContent(FlexAlign.Center)
    
          Button('刷新')
            .height('15%')
            .onClick(() => {
              postCardAction(this, {
                'action': 'message',
                'params': {
                  'info': 'refreshImage'
                }
              });
            })
        }
        .width('100%').height('100%')
        .alignItems(HorizontalAlign.Center)
        .padding('5%')
      }
    }
    

说明

  • Image组件通过入参(memory://fileName)中的memory://标识来进行远端内存图片显示,其中fileName需要和EntryFormAbility传递对象(‘formImages****’: {key****: fd})中的key相对应。
  • Image组件通过传入的参数是否有变化来决定是否刷新图片,因此EntryFormAbility每次传递过来的imgName都需要不同,连续传递两个相同的imgName时,图片不会刷新。

你可能感兴趣的:(交互,microsoft,harmonyos,开发语言,鸿蒙,鸿蒙系统,intellij,idea)