tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
892
3.5m

x-musicnotify-s 通知栏音乐播放器 ​

系统媒体控件。把正在播放的封面、标题、副标题和时间线同步到通知栏、锁屏、控制中心或鸿蒙播控中心，并回传播放、暂停、停止、上一首、下一首、拖进度。

本插件不解码音频。真正播放请用业务播放器或 x-mediaplay-s，再把进度喂给本插件。

兼容性 ​

HarmonyiOSAndroidWEB微信小程序
支持支持支持部分支持部分支持

调用 ​

ts
import {
  show,
  update,
  setProgress,
  setPlaying,
  hide,
  onAction,
  offAction,
  getState,
  XMusicNotifyShowOptions
} from "@/uni_modules/x-musicnotify-s"

onAction((res) => {
  if (res.action == "pause") {
    setPlaying({ playing: false })
  }
})

show({
  title: "晴天",
  subtitle: "周杰伦",
  album: "叶惠美",
  cover: "/static/x-musicnotify/default-cover.png",
  durationMs: 269000,
  positionMs: 0,
  playing: true,
  success: (res) => {
    console.log(res.errMsg)
  }
} as XMusicNotifyShowOptions)

方法 ​

名称说明
show展示或重建媒体通知，title 必填
update更新标题、副标题、专辑、封面、时长、进度、倍速、强调色
setProgress只更新时间线，适合跟播放器 onInfo
setPlaying只切换播放/暂停外观
hide关闭通知并释放系统会话
onAction监听系统控件操作，后注册覆盖前一次
offAction取消监听
getState当前展示快照
isShowing通知是否仍在

参数 ​

XMusicNotifyShowOptions

字段说明默认
title歌名必填
subtitle歌手空
album专辑空
cover本地绝对路径 / file:// / http(s) / /static内置默认封面
durationMs总时长 ms，大于 0 才画时间线0
positionMs当前进度 ms0
playing是否显示为播放中true
speed倍速1
showPrev / showNext / showStop按钮显隐true
canSeek是否允许拖时间线true
color强调色 #RRGGBB，主要影响 Android#31C27C

XMusicNotifyAction.action：play / pause / stop / prev / next / seek / close / click。seek 时 positionMs 为目标进度。

错误码：1001 系统错误，1002 参数错误，1003 通知服务不可用，1004 通知权限被拒绝，1007 当前环境无法显示控件，1008 平台不支持，1009 尚未 show。

平台差异 ​

Android

  • MediaSessionCompat + NotificationCompat.MediaStyle + mediaPlayback 前台服务。
  • Android 13+ 需运行时授予 POST_NOTIFICATIONS，插件会先申请再展示。
  • Android 13+ 系统媒体通知的进度条来自 session 的 duration / position，不必自己画 RemoteViews。
  • 修改 config.json 后需重新打自定义基座。

iOS

  • MPNowPlayingInfoCenter + MPRemoteCommandCenter。
  • 插件会把 AVAudioSession 设为 playback。锁屏控件在有真实音频在播时最稳定，建议同时用 x-mediaplay-s。
  • 宿主需允许后台音频：插件已声明 UIBackgroundModes: audio。

HarmonyOS

  • AVSession，类型 audio。至少注册一条控制命令后播控中心才会出现。
  • 进度按官方建议节流，后台播放保活仍取决于你的播放器长时任务。
  • 宿主 entry/module.json5 建议声明 backgroundModes: ["audio"]。

Web

  • navigator.mediaSession。Chrome 等通常要页面里有真实媒体在播，通知栏才会出现。
  • Safari 支持有限，不支持时 fail 1008。

微信小程序

  • 只更新 BackgroundAudioManager 的 title / singer / coverImgUrl / epname，并转发 onPlay / onPause / onStop / onPrev / onNext。
  • 封面建议用 https。没有后台音频在播时，系统通知栏可能不出现。

资源 ​

插件内置默认封面（黑胶 + 音符，QQ 绿强调）和播放 / 暂停 / 停止 / 上一首 / 下一首 / 关闭矢量图标。

  • 演示页封面：/static/x-musicnotify/default-cover.png
  • 原生回退封面：Android assets/x_musicnotify_cover.png、iOS Resources/x_musicnotify_cover.png、鸿蒙 rawfile/x_musicnotify_cover.png

业务封面传 cover 即可覆盖。HTTP 封面建议用 https。

更新日志 ​

1.0.0（2026-08-17） ​

  • 新增通知栏音乐播放器 API 插件：封面、标题、副标题、时间线、播放/暂停/停止/上一首/下一首。
  • Android MediaSession + MediaStyle 前台服务；iOS Now Playing；鸿蒙 AVSession；Web Media Session；微信后台音频元数据。
最近更新