本项目展示了如何在 HarmonyOS Next 中实现音乐服务卡片，集成歌曲播放、歌词展示、歌单推荐等功能。通过使用服务卡片，用户无需进入完整的音乐应用即可通过简洁的界面进行播放控制和内容浏览，从而提高了操作的便捷性与效率。本文将详细介绍项目的实现过程，包括核心功能的实现、代码结构以及最终效果的展示，帮助开发者快速掌握如何在 HarmonyOS Next 中创建高效的音乐服务卡片应用。
一、项目背景与目标
1. 框架介绍
音乐服务卡片是 HarmonyOS Next 中 服务卡片 的一种具体应用形式，它将音乐APP的核心功能（如歌曲播放、歌单推荐、歌词展示等）以简洁的卡片形式呈现给用户。用户无需打开完整应用，就能够在卡片上完成基本操作（如播放、暂停、切换歌曲、查看歌词等），大大提高了使用的便捷性和用户体验。本示例旨在通过音乐服务卡片的实现，展示如何利用 HarmonyOS Next 的服务卡片功能快速集成音乐相关的操作和展示，提升用户与设备的交互体验。
2. 项目目标
本项目的目标是创建一个功能完备的音乐服务卡片，支持以下功能：
- 歌曲播放控制：提供播放、暂停、上一曲、下一曲等控制操作。
- 歌词展示：实时显示当前播放歌曲的歌词。
- 歌单推荐：基于用户的历史偏好，推荐个性化的歌曲列表。
- 简洁交互：通过卡片展示核心功能，提升用户体验，减少切换应用的频率。
二、项目结构
以下是项目的目录结构，展示了各个功能模块的分布：
├──entry/src/main/ets // 代码区
│ ├──components // 自定义组件
│ │ ├──CustomTabBar.ets // 首页自定义导航Tabbar
│ │ ├──PlayController.ets // 首页底部音乐播控组件
│ │ ├──PlayerView.ets // 音乐播放界面
│ │ ├──PlayList.ets // 歌曲播放列表
│ │ ...
│ │ └──SongListItem.ets // 音乐列表列表项目
│ ├──database // 数据库工具类
│ │ ├──FormRdbHelper.ets // 卡片数据库工具类
│ │ ├──PreferencesUtil.ets // 首选项工具类
│ │ ├──RdbUtils.ets // 关系型数据工具类
│ │ └──SongRdbHelper.ets // 歌曲数据库工具类
│ ├──entryability
│ │ └──EntryAbility.ets // 程序入口类
│ ├──entrybackupability
│ │ └──EntryBackupAbility.ets // 应用数据备份和恢复类
│ ├──entryformability
│ │ └──EntryFormAbility.ets // 卡片生命周期类
│ ├──lyric // 歌曲歌词实现模块
│ ├──pages
│ │ └──MainPage.ets // 应用主界面
│ ├──utils // 工具类
│ │ ├──BackgroundUtil.ets // 后台任务管理类
│ │ ├──FormUtils.ets // 卡片管理类
│ │ ├──ImageUtils.ets // 图片工具类
│ │ ├──MediaService.ets // 音频播控管理类
│ │ ...
│ │ └──WindowUtils.ets // 窗口工具类
│ ├──view
│ │ ├──CollectedMusic.ets // 收藏歌曲视图
│ │ ├──HotPlaylist.ets // 热门歌单视图
│ │ └──RecommendedMusic.ets // 推荐歌曲视图
│ ├──viewmodel // 数据model
│ └──widget
│ ├──model
│ │ ├──ActionUtils.ets // 卡片事件交互方法封装类
│ │ └──FormCardConstant.ets // 卡片常量封装类
│ └──pages
│ ├──LyricsCard.ets // 歌词卡片
│ ├──PlayControlCard2x2.ets // 2x2音乐播控卡片
│ ├──PlayControlCard2x4.ets // 2x4音乐播控卡片
│ ├──RecommendedMusic1x2.ets // 1x2歌单推荐卡片
│ └──RecommendedMusic2x4.ets // 2x4歌单推荐卡片
└──entry/src/main/resources // 应用静态资源目录
本示例仅支持标准系统上运行，支持设备：华为手机。
HarmonyOS系统：HarmonyOS Next及以上。
DevEco Studio版本：DevEco Studio Next及以上。
HarmonyOS SDK版本：HarmonyOS Next SDK及以上。
三、项目实现
整体项目代码量过多，此处以核心代码为例：
1. 播放控制操作
在 ActionUtils.ets 中，playByAction 方法用于控制音乐播放的动作（播放、暂停、上一曲、下一曲）。通过接收 type 参数，playByAction 方法能够根据传入的动作类型发送相应的控制请求，操作音乐卡片的播放状态。
public playByAction(component: Object, type: PlayActionType, formId: string) {
postCardAction(component, {
action: FormCarAction.CALL,
abilityName: ENTRY_ABILITY,
params: {
method: CallMethod.PLAY_BY_ACTION,
playActionType: type,
formId: formId
}
});
}
2. 更新卡片状态
当用户对音乐控制卡片进行操作时，可能需要更新卡片的显示状态。updateControlCardAction 方法通过 postCardAction 请求更新卡片的显示内容（如歌曲封面、播放进度条等），确保卡片内容与当前播放状态一致。
public updateControlCardAction(component: Object, formId: string) {
postCardAction(component, {
action: FormCarAction.CALL,
abilityName: ENTRY_ABILITY,
params: {
method: CallMethod.REQUEST_UPDATE_CARD,
formId: formId
}
});
}
3. 表单信息管理
在 EntryFormAbility.ets 中，onAddForm 方法处理了音乐卡片表单的添加。它通过从 want.parameters 中提取 formId、formDimension 和 formName，创建并保存 FormInfo 对象，并根据 formName 进行相应的操作。
onAddForm(want: Want) {
Logger.info(TAG, 'onAddForm');
if (want.parameters) {
let formId = want.parameters['ohos.extra.param.key.form_identity'] as string;
let formDimension = want.parameters['ohos.extra.param.key.form_dimension'] as string;
let formName = want.parameters['ohos.extra.param.key.form_name'] as string;
let formInfo = new FormInfo();
formInfo.formId = formId;
formInfo.formDimension = formDimension;
formInfo.formName = formName;
Logger.info(TAG, `onAddForm formInfo: ${JSON.stringify(formInfo)}`);
FormRdbHelper.getInstance(this.context).insertForm(formInfo);
if (formName.includes('PlayControlCard')) {
// 音乐控制卡片的初始化或操作逻辑
}
}
}
四、效果预览
1. 播放界面
展示当前播放的歌曲信息、封面图、播放进度条以及播放/暂停按钮。
2. 播控卡片
提供基础的音乐播放控制功能，包括播放、暂停、上一曲、下一曲等按钮，用户可随时进行音乐控制。
3. 歌词卡片
显示当前播放歌曲的实时歌词，用户可以一边听歌一边跟随歌词。
4. 推荐卡片
基于用户的听歌习惯和历史记录，推荐个性化的歌单或歌曲，帮助用户发现新音乐。
五、总结
通过本项目实现的音乐服务卡片，展示了如何将常用的音乐功能通过卡片的形式高效集成到 HarmonyOS Next 应用中。通过简洁的交互界面，用户无需进入完整的应用即可完成常见操作，如播放、暂停、切换歌曲和查看歌词。此项目不仅提升了用户体验，也充分发挥了 HarmonyOS Next 服务卡片的优势，为开发者提供了更加便捷的音乐控制方案。
此外，项目中的核心代码展示了如何通过 ActionUtils.ets 和 EntryFormAbility.ets 实现音乐卡片的动态控制和数据管理，帮助开发者快速实现类似功能，并灵活地扩展和定制更多交互体验。
