鸿蒙卡片开发实战：音乐播放器卡片构建指南

2. 卡片生命周期管理 (src/main/ets/entryformability/EntryFormAbility.ets)

这个文件是卡片的'大脑'，负责处理 message 事件并执行刷新。

import { formBindingData, FormExtensionAbility, formInfo, formProvider, } from '@kit.FormKit';
import { Want, BusinessError } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'EntryFormAbility';
const DOMAIN_NUMBER: number = 0xFF00;

export default class EntryFormAbility extends FormExtensionAbility {
  // 卡片创建时触发，提供初始数据
  onAddForm(want: Want): formBindingData.FormBindingData {
    hilog.info(DOMAIN_NUMBER, TAG, 'onAddForm');
    const formId = want.parameters?.[formInfo.FormParam.IDENTITY_KEY] as string;
    const initData = {
      formId: formId,
      songName: '七里香 - 周杰伦',
      isLiked: false,
      playStatus: '暂停'
    };
    return formBindingData.createFormBindingData(initData);
  }

  // 收到 message 事件时触发
  async onFormEvent(formId: string, message: string): Promise<void> {
    hilog.info(DOMAIN_NUMBER, TAG, `onFormEvent: ${message}`);
    const params = JSON.parse(message);
    if (params.command === 'toggleLike') {
      // 模拟更新喜欢状态并刷新卡片
      const newData = { isLiked: params.isLiked };
      try {
        await formProvider.updateForm(formId, formBindingData.createFormBindingData(newData));
        hilog.info(DOMAIN_NUMBER, TAG, `卡片刷新成功：${formId}`);
      } catch (error) {
        const err = error as BusinessError;
        hilog.error(DOMAIN_NUMBER, TAG, `卡片刷新失败：${err.message}`);
      }
    }
  }

  // 卡片删除时触发
  onRemoveForm(formId: string): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onRemoveForm: ${formId}`);
  }
}

3. 应用主 UIAbility (src/main/ets/entryability/EntryAbility.ets)

处理 router 事件，负责跳转到应用内的页面。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'EntryAbility';
const DOMAIN_NUMBER: number = 0xFF00;

export default class EntryAbility extends UIAbility {
  private currentWindowStage: window.WindowStage | null = null;

  // 首次启动或在后台被 router 事件唤醒时触发
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onCreate: ${JSON.stringify(want.parameters)}`);
    // 处理 router 事件传递的参数
    if (want.parameters.params) {
      const params = JSON.parse(want.parameters.params as string);
      if (params.targetPage === 'PlayListPage') {
        hilog.info(DOMAIN_NUMBER, TAG, `准备跳转到播放列表页，当前歌曲：${params.currentSong}`);
        // 在这里可以设置全局状态，让目标页面获取数据
      }
    }
  }

  // 应用已在前台，再次收到 router 事件时触发
  onNewWant(want: Want): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onNewWant: ${JSON.stringify(want.parameters)}`);
    // 逻辑与 onCreate 类似
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    this.currentWindowStage = windowStage;
    // 加载主页面
    this.loadPage('pages/Index');
  }

  private loadPage(pageName: string): void {
    this.currentWindowStage?.loadContent(pageName, (err) => {
      if (err.code) {
        hilog.error(DOMAIN_NUMBER, TAG, `页面加载失败：${err.message}`);
      }
    });
  }
}

4. 后台 UIAbility (src/main/ets/ability/MusicBackgroundAbility.ets)

注意： 这个文件需要手动创建。在 ets 目录下新建一个 ability 文件夹，然后创建此文件。

它在后台运行，处理 call 事件。

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { formBindingData, formProvider } from '@kit.FormKit';
import { rpc } from '@kit.IPCKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'MusicBackgroundAbility';
const DOMAIN_NUMBER: number = 0xFF00;

// 用于 RPC 通信的数据序列化
class CallResult implements rpc.Parcelable {
  result: string;
  constructor(result: string) {
    this.result = result;
  }
  marshalling(messageSequence: rpc.MessageSequence): boolean {
    messageSequence.writeString(this.result);
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence): boolean {
    this.result = messageSequence.readString();
    return true;
  }
}

export default class MusicBackgroundAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN_NUMBER, TAG, 'onCreate');
    // 监听'play'和'pause'方法调用
    try {
      this.callee.on('play', this.handlePlay.bind(this));
      this.callee.on('pause', this.handlePause.bind(this));
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(DOMAIN_NUMBER, TAG, `方法监听失败：${err.message}`);
    }
  }

  // 处理播放逻辑
  private handlePlay(data: rpc.MessageSequence): CallResult {
    const params = JSON.parse(data.readString());
    const formId = params.formId;
    hilog.info(DOMAIN_NUMBER, TAG, `后台执行播放：${params.songId}`);
    // 模拟播放并刷新卡片状态
    this.updateCardStatus(formId, '播放');
    return new CallResult('播放成功');
  }

  // 处理暂停逻辑
  private handlePause(data: rpc.MessageSequence): CallResult {
    const params = JSON.parse(data.readString());
    const formId = params.formId;
    hilog.info(DOMAIN_NUMBER, TAG, `后台执行暂停：${params.songId}`);
    // 模拟暂停并刷新卡片状态
    this.updateCardStatus(formId, '暂停');
    return new CallResult('暂停成功');
  }

  // 调用刷新接口更新卡片
  private async updateCardStatus(formId: string, status: string): Promise<void> {
    try {
      await formProvider.updateForm(formId, formBindingData.createFormBindingData({ playStatus: status }));
      hilog.info(DOMAIN_NUMBER, TAG, `卡片状态刷新成功：${status}`);
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(DOMAIN_NUMBER, TAG, `卡片状态刷新失败：${err.message}`);
    }
  }

  onDestroy(): void {
    hilog.info(DOMAIN_NUMBER, TAG, 'onDestroy');
    this.callee.off('play');
    this.callee.off('pause');
  }
}

5. 应用配置文件 (src/main/module.json5)

这是最重要的配置文件，必须正确注册所有组件和权限。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background"
      },
      {
        "name": "MusicBackgroundAbility",
        "srcEntry": "./ets/ability/MusicBackgroundAbility.ets",
        "description": "处理卡片 call 事件的后台服务"
      }
    ],
    "extensionAbilities": [
      {
        "name": "EntryFormAbility",
        "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
        "label": "$string:EntryFormAbility_label",
        "description": "$string:EntryFormAbility_desc",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:keep_background_running_reason",
        "usedScene": {
          "abilities": ["MusicBackgroundAbility"],
          "when": "always"
        }
      }
    ]
  }
}

注意： 您需要在 src/main/resources/base/element/string.json 中添加 keep_background_running_reason 的定义。

{
  "string": [
    {
      "name": "keep_background_running_reason",
      "value": "用于在后台处理卡片的播放/暂停指令"
    }
  ]
}

6. 卡片配置文件 (src/main/resources/base/profile/form_config.json)

确保卡片是动态的。

{
  "forms": [
    {
      "name": "MusicWidget",
      "description": "$string:MusicWidget_desc",
      "src": "./ets/widget/pages/MusicWidget.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"],
      "formConfigAbility": "",
      "dataProxyEnabled": false,
      "isDynamic": true
    }
  ]
}

第 3 步：运行指南

1. 环境准备：确保您的 DevEco Studio 版本支持 API 10，并且已经配置好了 HarmonyOS SDK 和模拟器/真实设备。
2. 创建项目：按照'项目初始化'的步骤创建一个新的 Application 项目。
3. 替换代码：将上面提供的代码片段，分别复制并替换到项目中对应的文件里。特别注意手动创建 MusicBackgroundAbility.ets 文件。
4. 配置 HAP 包：
   • 打开 entry > src > main > module.json5。
   • 在编辑器下方的 HAP 标签页中，点击 Add，新增一个 HAP，例如命名为 entry_feature。
   • 将 MusicBackgroundAbility 从 entry 模块移动到 entry_feature 模块中。这是因为包含后台运行权限的 Ability 需要放在一个独立的 feature HAP 中。
   • 确保 module.json5 中 requestPermissions 部分也在 entry_feature 模块中。
5. 编译运行：将项目编译并运行到您的 HarmonyOS 设备或模拟器上。
6. 添加卡片：
   • 在设备的桌面上，长按空白处，选择'添加卡片'。
   • 找到您的应用，选择刚刚创建的'MusicWidget'并添加到桌面。
7. 测试事件：
   • 点击卡片上的'喜欢'按钮，按钮文字和颜色会立即变化（message 事件）。
   • 点击'打开播放列表'按钮，应用会被启动并进入主界面（router 事件）。
   • 点击'播放/暂停'按钮，卡片上的状态文字会切换，同时后台会有日志输出（call 事件）。