如何在卡片中刷新展示网络图片

问题现象

在卡片上展示网络图片时，由于卡片环境的限制，无法直接使用网络图片URL。需要先将网络图片下载到本地沙箱，然后通过Image组件显示。

常见的场景包括：

• 创建卡片时直接展示网络图片。
• 主应用中主动刷新卡片中网络图片。
• 卡片主动刷新网络图片。
• 定时/定点被动刷新卡片中网络图片。

背景知识

• Form Kit（卡片开发框架）提供了一种在桌面、锁屏等系统应用上嵌入显示应用信息的开发框架和API，可以将应用内用户关注的重要信息或常用操作抽取到服务卡片（简称“卡片”）上，通过将卡片添加到桌面、锁屏等系统应用上，以达到信息展示、服务直达的便捷体验效果。
• 在卡片上通常需要展示本地图片或从网络上下载的图片，获取本地图片和网络图片需要通过FormExtensionAbility来实现，参考刷新本地图片和网络图片。
• Image为图片组件，常用于在应用中显示图片。从API version 9开始，该接口支持在ArkTS卡片中使用。ArkTS卡片上不支持https等网络相关路径前缀和file路径前缀的字符串。

解决方案

由于ArkTS卡片不支持直接使用网络相关路径，如果需要在卡片上展示网络图片，则需要先将网络图片下载至本地沙箱，然后Image组件通过入参(memory://fileName)中的(memory://)标识来进行远端内存图片显示。

下载网络图片需要使用网络能力，申请ohos.permission.INTERNET权限，配置方式为在module.json5配置文件的requestPermissions标签中声明权限：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

不同场景均需要通过httpRequest.request方法下载网络资源，在下载完成的回调中调用updateForm接口更新图片数据。

class FormDataClass {
  // 卡片需要显示图片场景，必须和下列字段formImages中的key相同
  imgName: string = '';
  // 卡片需要显示图片场景，必填字段(formImages不可缺省或改名)，fileName对应fd
  formImages: Record<string, number> = {};
}

// 下载文件
download(context:
Context, formId:
string
)
{
  let netFile = 'https://XXXX'; // 网络图片地址
  let httpRequest = http.createHttp()
  let tempDir = context.getApplicationContext().tempDir;
  let fileName = 'file' + Date.now();
  let tmpFile = tempDir + '/' + fileName;
  let imgFile = undefined
  let imgMap: Record<string, number> = {};

  // 下载网络资源
  httpRequest.request(netFile).then((data) => {
    if (data?.responseCode === http.ResponseCode.OK) {
      try {
        let imgFile = fileIo.openSync(tmpFile, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
        imgMap[fileName] = imgFile.fd;
        try {
          fileIo.write(imgFile.fd, data.result as ArrayBuffer).then((writeLen) => {
            console.info('write data to file succeed and size is:' + writeLen);
            try {
              let formData: FormDataClass = {
                imgName: fileName,
                formImages: imgMap
              }
              const formInfo = formBindingData.createFormBindingData(formData)
              formProvider.updateForm(formId, formInfo).then(() => {
                console.info('FormAbility updateForm success.');
              }).catch((e: BusinessError) => {
                console.error(`FormAbility updateForm failed: 63 ${JSON.stringify(e)}`);
              });
            } catch (error) {
              console.error(`FormAbility updateForm failed: ${JSON.stringify(error)}`);
            }
          })
        } catch (err) {
          console.error('write data to file failed with error message: ' + err.message + ', error code: ' + err.code);
        }
      } catch (e) {
        console.error(`openSync failed: ${JSON.stringify(e as BusinessError)}`);
      } finally {
        // 在fileIo.closeSync执行之前，确保formProvider.updateForm已执行完毕。
        fileIo.closeSync(imgFile);
      }
    } else {
      console.error(`ArkTSCard download task failed`);
      let param: Record<string, string> = {
        'text': '刷新失败'
      };
      const formInfo = (formBindingData.createFormBindingData(param))
      formProvider.updateForm(formId, formInfo);
    }
    httpRequest.destroy();
  })
}

在WidgetCard卡片页面中使用LocalStorageProp装饰需要刷新的卡片数据，使用Image组件加载远端内存图片。

@Entry
@Component
struct WidgetCard {
  @LocalStorageProp('imgName') imgName: string = '';

  build() {
    Column() {
      Image('memory://' + this.imgName)
        .width(100)
    }
    .width('100%')
    .height('100%')
  }
}

不同场景的区别在于下载网络图片的时机，具体区分为以下四种场景。

• 场景一：创建卡片时直接展示网络图片。

  

  创建卡片时，onAddForm是卡片提供方接收创建卡片的通知接口。网络图片下载涉及异步场景，在onAddForm回调返回的卡片数据中暂时无法立即拿到图片资源的信息，需要在图片下载完成的回调中调用updateForm接口，主动刷新网络图片信息。

  onAddForm(want: Want): formBindingData.FormBindingData {
    let formId = want?.parameters?.[formInfo.FormParam.IDENTITY_KEY] as string;
    // 执行download下载网络图片
    this.download(this.context, formId)
    let formData = new FormDataClass();
    return formBindingData.createFormBindingData(formData);
  }

  效果预览：

  

• 场景二：主应用内主动刷新卡片中网络图片。

  

  已上桌的卡片，在主应用内可通过formProvider.getPublishedRunningFormInfos接口获取所有已加桌的卡片信息。接着，通过卡片名称可以过滤出需要更新的目标卡片信息。最后下载网络图片到本地，通过updateForm接口更新卡片的图片。

  Button('更新桌面网络图片').onClick(async (event: ClickEvent) => {
    const context = this.getUIContext().getHostContext() as common.UIAbilityContext
    // 获取上已上桌的卡片
    try {
      formProvider.getPublishedRunningFormInfos().then((data: formInfo.RunningFormInfo[]) => {
        console.info(`formProvider getPublishedRunningFormInfos, data: ${JSON.stringify(data)}`);
  
        data.forEach((form) => {
          let formId = form.formId
          let formName = form.formName
          // 可根据名称作为条件进行过滤
          this.download(context, formId)
        })
      }).catch((error: BusinessError) => {
        console.error(`promise error, code: ${error.code}, message: ${error.message})`);
      });
    } catch (error) {
      console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
    }
  })

  效果预览：

  

• 场景三：卡片主动刷新网络图片。

  

  已上桌的卡片，在卡片可以通过postCardAction接口触发message事件拉起FormExtensionAbility，通过onFormEvent接口回调通知，以完成点击卡片控件后刷新卡片中图片的功能。步骤参考如下：

  1. 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用postCardAction接口触发message事件。

     Button('更新图片').onClick((event: ClickEvent) => {
       postCardAction(this, {
         action: 'message',
         params: { msgTest: 'messageEvent' }
       });
     })

  2. 在FormExtensionAbility的onFormEvent生命周期中下载网络资源。

     onFormEvent(formId: string, message: string) {
       this.download(this.context,formId)
     }

  效果预览：

  

• 场景四：定时/定点被动刷新网络图片。

  

  已上桌的卡片，可以在form_config.json配置文件的updateDuration字段中配置定时刷新间隔，也可以配置scheduledUpdateTime字段设置卡片定点刷新时间。在触发定点刷新后，系统会调用FormExtensionAbility的onUpdateForm生命周期回调，在回调中，通过updateForm接口更新卡片的图片。以卡片定点刷新为例，步骤参考如下：

  1. 在form_config.json配置文件设置scheduledUpdateTime卡片定点刷新时间。

     "updateEnabled": true,
     "scheduledUpdateTime": "14:21",
     "updateDuration": 0,

  2. 在FormExtensionAbility的onUpdateForm生命周期中下载网络资源。

     onUpdateForm(formId: string, message: string) {
       this.download(this.context,formId)
     }

  效果预览：

  

常见FAQ

Q：下载网络图片至沙箱，卡片加载图片失败可能是什么原因导致？

A：卡片中Image组件通过入参(memory://fileName)中的(memory://)标识来进行远端内存图片显示。网络资源在下载过程中，仍可通过openSync打开并获取文件fd。因此，显示卡片时需要确保网络图片已经在沙箱下载完成，避免网络图片下载过程中将fd传递至卡片，造成卡片图片加载失败。

Q：为什么修改传递给卡片formImages中imgName对应的文件fd，卡片中的图片没有更新？

A：Image组件通过传入的参数是否有变化来决定是否刷新图片，因此EntryFormAbility每次传递过来的imgName都需要不同，连续传递两个相同的imgName时，图片不会刷新。

Q：在卡片上展示的图片有什么限制？

A：在卡片刷新过程中，卡片UI通过@LocalStorageProp接收卡片数据时，FormBindingData对象会序列化，即卡片数据会转换成string类型。从API version 20开始，图片文件数量上限为20张，所有图片总内存大小不超过10MB，超出限制的图片会显示异常，API version 19及之前的版本，图片文件数量上限为5张，每张限制内存2MB。

总结