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

鸿蒙卡片开发实战：音乐播放器卡片构建指南 | 极客日志

import { postCardAction } from '@kit.FormKit';
let storage = new LocalStorage();

@Entry(storage)
@Component
struct MusicWidget {
  // 从 EntryFormAbility 接收的数据
  @LocalStorageProp('formId') formId: string;
  @LocalStorageProp('songName') songName: string = '未播放';
  @LocalStorageProp('isLiked') isLiked: boolean = false;
  @LocalStorageProp('playStatus') playStatus: string = '暂停';

  build() {
    Column({ space: 15 })
      .width('100%')
      .height('100%')
      .padding(15)
      .justifyContent(FlexAlign.Center) {
      Text('音乐卡片')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 10 });
      Text(`🎵 ${this.songName}`)
        .fontSize(16)
        .fontWeight(FontWeight.Normal);
      Text(`▶️ 状态：${this.playStatus}`)
        .fontSize(14)
        .fontColor(Color.Grey)
        .margin({ bottom: 20 });

      // --- 事件按钮区域 ---
      // 1. message 事件：喜欢/取消喜欢
      Button(this.isLiked ? '❤️ 已喜欢' : '🤍 喜欢')
        .width('80%')
        .height(40)
        .backgroundColor(this.isLiked ? Color.Pink : Color.White)
        .fontColor(this.isLiked ? Color.White : Color.Black)
        .border({ width: 1, color: Color.Pink })
        .onClick(() => { this.triggerMessageEvent(); });

      // 2. router 事件：打开应用播放列表
      Button('📱 打开播放列表')
        .width('80%')
        .height(40)
        .backgroundColor(Color.Blue)
        .fontColor(Color.White)
        .onClick(() => { this.triggerRouterEvent(); });

      // 3. call 事件：播放/暂停
      Button(`${this.playStatus === '播放' ? '⏸️ 暂停' : '▶️ 播放'}`)
        .width('80%')
        .height(40)
        .backgroundColor(Color.Green)
        .fontColor(Color.White)
        .onClick(() => { this.triggerCallEvent(this.playStatus === '播放' ? 'pause' : 'play'); });
    }
  }

  // 触发 message 事件
  private triggerMessageEvent(): void {
    postCardAction(this, {
      action: 'message',
      params: {
        formId: this.formId,
        command: 'toggleLike',
        isLiked: !this.isLiked
      }
    });
  }

  // 触发 router 事件
  private triggerRouterEvent(): void {
    postCardAction(this, {
      action: 'router',
      abilityName: 'EntryAbility',
      params: {
        targetPage: 'PlayListPage',
        currentSong: this.songName
      }
    });
  }

  // 触发 call 事件
  private triggerCallEvent(method: string): void {
    postCardAction(this, {
      action: 'call',
      abilityName: 'MusicBackgroundAbility',
      params: {
        formId: this.formId,
        method: method,
        songId: 'song_001'
      }
    });
  }
}

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}`);
  }
}

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}`);
      }
    });
  }
}

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');
  }
}

{
  "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"
        }
      }
    ]
  }
}

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

{
  "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
    }
  ]
}

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

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

项目结构

第 1 步：项目初始化

第 2 步：代码实现

1. 卡片 UI 页面 (`src/main/ets/widget/pages/MusicWidget.ets`)

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

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

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

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

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

第 3 步：运行指南

更多推荐文章

相关免费在线工具

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

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

项目结构

第 1 步：项目初始化

第 2 步：代码实现

1. 卡片 UI 页面 (src/main/ets/widget/pages/MusicWidget.ets)

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

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

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

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

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

第 3 步：运行指南

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

1. 卡片 UI 页面 (`src/main/ets/widget/pages/MusicWidget.ets`)

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

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

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

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

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