更新记录

0.1.0（2026-04-30）

首次发布，适配uni.getBackgroundAudioManager()

平台兼容性

uni-app(5.0)

uni-app x(5.0)

ct-media-player

Android 端系统媒体通知 UTS 插件，用于给 uni-app 项目提供通知栏播放器控制能力。

功能说明

• 基于 Android 前台服务显示系统媒体通知
• 支持歌曲标题、副标题、封面图展示
• 支持上一曲、播放、暂停、下一曲、关闭按钮
• 支持 MediaSession，可响应系统媒体控制
• 支持同步当前播放进度与总时长

支持平台

• App-Android

当前插件未实现 App-iOS、H5、各类小程序平台。

导入方式

在 uni-app JS 文件中直接从 uni_modules 导入：

import {
  showMediaNotification,
  updateMediaNotification,
  hideMediaNotification,
  areNotificationsEnabled,
  openNotificationSettings
} from '@/uni_modules/ct-media-player'

API

showMediaNotification(options)

显示媒体通知，首次展示时调用。

updateMediaNotification(options)

更新媒体通知，用于同步播放状态、进度、封面和当前歌曲信息。

hideMediaNotification()

关闭媒体通知。

areNotificationsEnabled()

返回当前应用通知权限是否开启。

openNotificationSettings()

跳转到当前应用的系统通知设置页。

options 参数

{
  title: '歌曲标题',
  content: '专辑或描述',
  subText: '作者或歌手',
  coverImagePath: '/storage/emulated/0/xxx.jpg',
  playing: true,
  currentTime: 12,
  duration: 260,
  showPrev: true,
  showNext: true,
  showClose: true,
  onClick: () => {},
  onPrev: () => {},
  onPlay: () => {},
  onPause: () => {},
  onNext: () => {},
  onClose: () => {}
}

字段说明

• title: 通知标题，一般传歌曲名
• content: 通知正文，一般传专辑名、分类名或描述
• subText: 通知副标题，一般传作者、歌手
• coverImagePath: 封面图路径，建议传本地绝对路径或 file:// 路径
• playing: 当前是否播放中
• currentTime: 当前播放进度，单位秒
• duration: 总时长，单位秒
• showPrev: 是否显示上一曲按钮
• showNext: 是否显示下一曲按钮
• showClose: 是否显示关闭按钮
• onClick: 点击通知主体回调
• onPrev: 点击上一曲回调
• onPlay: 点击播放回调
• onPause: 点击暂停回调
• onNext: 点击下一曲回调
• onClose: 点击关闭回调

使用示例

import {
  updateMediaNotification,
  hideMediaNotification,
  areNotificationsEnabled,
  openNotificationSettings
} from '@/uni_modules/ct-media-player'

function syncNotification(player, track, playing) {
  if (!areNotificationsEnabled()) {
    openNotificationSettings()
    return
  }

  updateMediaNotification({
    title: track.title || track.Title || '音频播放',
    content: track.album || track.Album || '',
    subText: track.author || track.Author || '',
    coverImagePath: track.localCoverPath || '',
    playing: !!playing,
    currentTime: Number(player.currentTime || 0),
    duration: Number(player.duration || 0),
    showPrev: true,
    showNext: true,
    showClose: true,
    onPrev: () => {
      // 上一曲逻辑
    },
    onPlay: () => {
      // 播放逻辑
    },
    onPause: () => {
      // 暂停逻辑
    },
    onNext: () => {
      // 下一曲逻辑
    },
    onClose: () => {
      hideMediaNotification()
    }
  })
}

接入建议

• 在播放器 onPlay 时立即调用一次通知更新
• 在播放器 onPause 时立即同步暂停状态
• 在 onTimeUpdate 中低频同步 currentTime 与 duration
• 在切歌后立即更新标题、封面、进度和回调
• 在播放器销毁、停止播放、切到非音乐播放源时调用 hideMediaNotification()

封面图注意事项

• Android 系统媒体通知更稳定的方案是传本地图片路径
• 如果业务里拿到的是远程封面 URL，建议先下载到本地再传给插件
• 同一首歌播放过程中，建议复用已下载的本地封面，避免重复下载

注意事项

• 本插件依赖 Android 前台服务与通知权限
• Android 13 及以上如果未授权通知权限，通知不会显示
• 媒体通知样式由 Android 系统和 ROM 决定，背景、布局、圆角等无法完全自定义
• 如果修改了插件内 AndroidManifest.xml、Service、Receiver 等原生配置，通常需要重新制作自定义基座

排查建议

如果通知没有显示，可按下面顺序排查：

1. 确认当前运行平台是 App-Android
2. 确认已开启系统通知权限
3. 确认项目使用的是包含本插件原生配置的自定义基座
4. 确认播放器已经实际调用 updateMediaNotification()
5. 查看运行日志里是否有 ct-media-player 相关输出

如果通知显示但封面不显示，可优先检查：

1. coverImagePath 是否为空
2. 传入的是不是本地绝对路径或 file:// 路径
3. 本地图片文件是否真实存在
4. 日志里 loadLargeIcon result 是否为 true