HarmonyOS鸿蒙Next FormKit卡片开发如何实现数据刷新？桌面小组件开发指南

1. 卡片配置文件

在 form_config.json 中配置卡片：

{
  "forms": [
    {
      "name": "FishCard",
      "displayName": "$string:fish_card_name",
      "description": "$string:fish_card_desc",
      "src": "./ets/widget/pages/FishCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2", "2*4", "4*4"]
    }
  ]
}

2. 卡片UI实现

// widget/pages/FishCard.ets

@Entry
@Component
struct FishCard {
  @LocalStorageProp('fishCount') fishCount: number = 0
  @LocalStorageProp('lastFeedTime') lastFeedTime: string = '--'
  @LocalStorageProp('waterTemp') waterTemp: number = 0

  build() {
    Column({ space: 8 }) {
      // 标题
      Row() {
        Text('🐟')
          .fontSize(20)
        Text('我的鱼缸')
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
          .fontColor('#ffffff')
          .margin({ left: 8 })
      }
      .width('100%')
     
      // 数据展示
      Row({ space: 16 }) {
        // 鱼数量
        Column() {
          Text(this.fishCount.toString())
            .fontSize(24)
            .fontWeight(FontWeight.Bold)
            .fontColor('#36e27b')
          Text('鱼数量')
            .fontSize(10)
            .fontColor('#9eb7a8')
        }
       
        // 水温
        Column() {
          Text(`${this.waterTemp}°C`)
            .fontSize(24)
            .fontWeight(FontWeight.Bold)
            .fontColor('#3b82f6')
          Text('水温')
            .fontSize(10)
            .fontColor('#9eb7a8')
        }
      }
     
      // 上次喂食时间
      Text(`上次喂食: ${this.lastFeedTime}`)
        .fontSize(12)
        .fontColor('#9eb7a8')
    }
    .width('100%')
    .height('100%')
    .padding(12)
    .backgroundColor('#1C2E24')
    .borderRadius(16)
  }
}

3. 卡片EntryFormAbility

// entryformability/EntryFormAbility.ets

import { formBindingData, FormExtensionAbility, formInfo, formProvider } from '@kit.FormKit'
import { Want } from '@kit.AbilityKit'
import { preferences } from '@kit.ArkData'

export default class EntryFormAbility extends FormExtensionAbility {

  // 卡片创建时调用
  onAddForm(want: Want): formBindingData.FormBindingData {
    const formId = want.parameters?.['ohos.extra.param.key.form_identity'] as string
    
    // 获取初始数据
    const formData = this.getFormData()
    
    // 保存卡片ID用于后续更新
    this.saveFormId(formId)
    
    return formBindingData.createFormBindingData(formData)
  }

  // 卡片更新时调用
  onUpdateForm(formId: string): void {
    const formData = this.getFormData()
    const bindingData = formBindingData.createFormBindingData(formData)
    formProvider.updateForm(formId, bindingData)
  }

  // 卡片删除时调用
  onRemoveForm(formId: string): void {
    this.removeFormId(formId)
  }

  // 获取卡片数据
  private getFormData(): Record<string, Object> {
    // 从持久化存储获取数据
    const prefs = preferences.getPreferencesSync(this.context, { name: 'fish_data' })
    
    return {
      fishCount: prefs.getSync('fishCount', 0) as number,
      lastFeedTime: prefs.getSync('lastFeedTime', '--') as string,
      waterTemp: prefs.getSync('waterTemp', 25) as number
    }
  }

  // 保存卡片ID
  private saveFormId(formId: string): void {
    const prefs = preferences.getPreferencesSync(this.context, { name: 'form_ids' })
    const ids = prefs.getSync('ids', '[]') as string
    const idArray = JSON.parse(ids) as string[]
    if (!idArray.includes(formId)) {
      idArray.push(formId)
      prefs.putSync('ids', JSON.stringify(idArray))
      prefs.flush()
    }
  }

  // 移除卡片ID
  private removeFormId(formId: string): void {
    const prefs = preferences.getPreferencesSync(this.context, { name: 'form_ids' })
    const ids = prefs.getSync('ids', '[]') as string
    const idArray = JSON.parse(ids) as string[]
    const index = idArray.indexOf(formId)
    if (index > -1) {
      idArray.splice(index, 1)
      prefs.putSync('ids', JSON.stringify(idArray))
      prefs.flush()
    }
  }
}

4. 从应用主动更新卡片

// 在应用中更新卡片数据
import { formProvider, formBindingData } from '@kit.FormKit'
import { preferences } from '@kit.ArkData'

class FormUpdateService {

  // 更新所有卡片
  static async updateAllForms(context: Context): Promise<void> {
    try {
      // 获取所有卡片ID
      const prefs = await preferences.getPreferences(context, { name: 'form_ids' })
      const ids = await prefs.get('ids', '[]') as string
      const idArray = JSON.parse(ids) as string[]
      
      // 获取最新数据
      const dataPrefs = await preferences.getPreferences(context, { name: 'fish_data' })
      const formData = {
        fishCount: await dataPrefs.get('fishCount', 0),
        lastFeedTime: await dataPrefs.get('lastFeedTime', '--'),
        waterTemp: await dataPrefs.get('waterTemp', 25)
      }
      
      // 更新每个卡片
      const bindingData = formBindingData.createFormBindingData(formData)
      for (const formId of idArray) {
        await formProvider.updateForm(formId, bindingData)
      }
      
    } catch (err) {
      console.error('更新卡片失败:', err)
    }
  }

  // 更新单个数据并刷新卡片
  static async updateFishCount(context: Context, count: number): Promise<void> {
    const prefs = await preferences.getPreferences(context, { name: 'fish_data' })
    await prefs.put('fishCount', count)
    await prefs.flush()
    
    await this.updateAllForms(context)
  }
}

// 使用示例
Button('喂食完成')
  .onClick(async () => {
    const now = new Date()
    const timeStr = `${now.getHours()}:${now.getMinutes().toString().padStart(2, '0')}`
    
    const prefs = await preferences.getPreferences(getContext(this), { name: 'fish_data' })
    await prefs.put('lastFeedTime', timeStr)
    await prefs.flush()
    
    await FormUpdateService.updateAllForms(getContext(this))
  })

5. 卡片点击跳转应用

// 卡片中添加点击事件
Column() {
  // ... 卡片内容
}
.onClick(() => {
  postCardAction(this, {
    action: 'router',
    abilityName: 'EntryAbility',
    params: {
      page: 'FishDetail'
    }
  })
})