MediaNotification 媒体通知扩展

下载

.aix拓展文件：

de.ullisroboterseite.ursai2medianotification.aix

.aia示例文件：

UrsMediaNotification_3_1.aia

版本历史

⚠️ 注意：媒体通知的显示取决于制造商。并非每个制造商都以相同的方式实现此通知的显示。也不能保证所有功能都可用。

测试结果

非常感谢 Anke (Body Mind Power) 提供了许多宝贵的提示并花费大量时间广泛测试扩展！

设备	测试结果	视图	紧凑视图
智能手机 Redmi 5 Plus Android 8.1	Companion版本2.6.1导致错误。Companion中并非所有必要的类都可用。 编译的APK工作完美（没有进度条，这仅从Android 10开始可用）。		没有紧凑视图
智能手机 Google Pixel 2 XL Android 11	Companion和APK都按预期工作。
智能手机 Samsung A02s Android 12	Companion和APK都按预期工作。
平板 Yestel T13_EEA Android 13	Companion和APK都按预期工作。
智能手机 ZTE Blade A73 Android 13	Companion和APK中都没有显示进度条。应用图标始终显示为SmallIcon（任务栏中的图标）。 其他功能按预期工作。
智能手机 Motorola g15 Android 15	Companion和APK都按预期工作。		没有紧凑视图

使用方法

自API级别21（LolliPop 5.0）以来，有一种特殊类型的通知专门开发用于控制媒体播放器。外部播放设备如耳机也可以通过此通知控制媒体播放器。

此扩展仅用于管理媒体通知。如果要创建常规通知，应使用 UrsAI2Notifier 扩展。

版本依赖性

显示和功能随着时间多次改变。

配置通知所需的 MediaSession 类自Android 5.0（Android Lollipop，SDK 21）开始可用。

Android 10（SDK 29）添加了显示进度条（ProgressBar）的选项。

Android 13（SDK 33）再次完全修订了外观和感觉。紧凑视图被废除。

并非所有制造商都实现了所有更改。

关于通知通道

自API级别26（版本Oreo 8.0）以来，Android引入了通知通道概念，在某些设备上也称为通知类别。从API级别26开始，所有通知必须分配给此类通道。直到API Level 25，所有与通知通道相关的信息和功能都被忽略。

通知概念相当复杂。Android允许在设备级别、通道级别以及通知本身进行设置。

通知的许多属性，例如重要性（参见Importance、IMPORTANCE_DEFAULT等），都在通道级别定义。这些属性由应用程序在创建通道时设置。借助Android应用程序设置，用户对大多数通道属性拥有完全访问权限，可以根据需要修改它们。用户进行的修改不应被覆盖。这就是为什么通道属性以后不能通过程序更改的原因。即使删除通道然后再次创建，它也是使用最后的设置创建的。”擦除”实际上只是”隐藏”。只有属性 Name 和 Description 以后可以更改。否则无法消除拼写错误。

因此应仔细考虑将哪些属性分配给通道。

扩展提供 ChannelID、ChannelName、ChannelDescription 和 ChannelImportance 作为通道属性。ChannelImportence定义了显示通知的条件等。通道在首次调用 ShowNotification 时自动创建。

如果要更改其他属性，必须使用新通道（新的ChannelID）。启动应用程序时应使用 HideChannel 隐藏现有通道。

保持设备活动

许多媒体播放器组件使用WakeLock在播放声音文件时保持设备活动。这在旧版本中就足够了。自Android 8.0（Oreo，API level 26）以来，Android政策已更改为阻止设备切换到待机模式（doze mode）的应用程序必须向用户明显指示这一点。从那时起，除了WakeLock外，还必须启动ForegroundService。此服务意味着通知用户电池优化正在被阻止。

KeepAppAlive 属性可用于设置扩展在显示通知时启动前台服务并设置WakeLock。这可以防止设备切换到睡眠模式。

如果通知启动前台服务，DeleteAble 属性通常没有效果。通知无法删除。

配置

⚠️ 注意：所有更改都没有立即效果。它们在下次调用 ShowNotification 时应用。

媒体通知内的按钮

在较新的Android版本中，通知通常以紧凑模式显示。在紧凑模式下，最多可以显示三个按钮。在扩展模式下，有五个（参见测试结果部分的截图）

带有播放（▶）或暂停（⏸）符号的按钮始终显示。显示哪个按钮可以使用 SetStatePaused（显示▶）和 SetStatePlaying（显示⏸）方法设置。

根据应用程序想要支持的功能，其他按钮可以通过 Support... 函数打开和关闭。

在紧凑模式下，暂停或播放按钮始终可见。ShowNavigtionButtonsInCompactView 属性可用于指定如果激活，倒带和快进按钮对也会显示。ShowSkipButtonsInCompactView 导致显示SkipToNext和SkipToPrevious。

可以使用 SetActionIcon 方法自定义通知按钮上显示的图标。可以指定系统图标的名称或上传图形文件的名称。例如，Previous 和 Next 的图标可以替换为 Like 和 Dislike。总共，通知最多可以显示五个操作按钮。

激活事件

如果设置了 DeleteAble，用户可以通过例如滑动删除通知。如果通知被用户删除，则触发 UserCanceled 事件。

元数据和外观

背景颜色无法通过编程调整。它由Android自动从专辑图像颜色确定。

SetMetaData 和 SetMetaDataEx 函数可用于指定将在通知上显示的标题、艺术家和图像（AlbumImage）。

AlbumImage

可以按如下方式指定AlbumImage：

指定URL时，请注意图像是同步加载的。对于大文件或慢速连接，这可能需要一些时间。另一个选择是使用支持文件异步（并发）下载的扩展（例如ImageLoader扩展）。

为简化文件访问，可以使用：

• GetVolumes：获取卷根目录的列表
• GetAppDataDir：获取应用程序特定数据目录的路径
• GetDownloadDir：获取下载目录的路径

Small Icon

从API Level 23（Android 6，Marshmallow）开始，可以使用为SmallIcon（SmallIconImage 属性）包含自定义图形的选项。SmallSystemIcon 属性允许为旧版本选择系统图标（可能的选项参见：系统通知图标）。选择规则如下：

图标的显示因设备和Android版本而异。最好使用单色图像（颜色深度1位）和大小256 x256像素²的JPEG或PNG格式。GIF格式的图形也可以，只要不是动画的。

ProgressBar（自Android 10，API Level 29）

自Android 10以来，媒体通知可以显示进度条和搜索条。为此，必须知道媒体对象的持续时间和播放器的当前位置。

SetMetaDataEx 允许指定播放时间，这是显示进度条所必需的。一些媒体播放器，如TaifunPlayer（在示例中使用）提供此信息。要获取必要信息，播放器必须相应地初始化。

ShowWithProgressBar 函数显示进度条。它从 CurrentPosition 参数指定的位置开始。然后它继续独立运行。如果以编程方式更改播放位置，必须使用 ShowWithProgressBar 同步进度条。

对于早于Android 10的版本，SetMetaDataEx 和 ShowWithProgressBar 也可以工作，但不显示进度条。

操作方法

设置组件的初始属性，传输媒体元数据（SetMetaData 或 SetMetaDataEx），然后调用 ShowNotification 或 ShowWithProgressBar。从现在开始，您实际上需要对事件做出反应。根据事件，适当地设置媒体播放器，调整组件的属性并再次调用 ShowNotification。

通常媒体播放器不仅由媒体通知控制。应用程序还包含应该控制播放器的控件。为了使项目中的块简单，有 Play、Pause、Rewind 等函数，它们触发与通知相同的事件。因此用户界面控件不需要双倍的代码。您只需调用适当的函数。

错误处理

错误通过 Screen.ErrorOccurred 事件报告。

参考

属性 Properties

通道描述 ChannelDescription

用户可见的NotificationChannel的描述。此属性以后可以更改。

通道ID ChannelID

NotificationChannel的ID（以后不能更改）。

通道重要性 ChannelImportance

NotificationChannel的重要性级别（1-5）。定义显示通知的条件等。

通道名称 ChannelName

用户可见的NotificationChannel的名称。此属性以后可以更改。

当前位置 CurrentPosition

当前播放位置（毫秒）。用于进度条显示。

可删除 DeleteAble

如果设置为true，用户可以删除通知，例如通过滑动。

保持应用活跃 KeepAppAlive

设置此属性为true时，扩展在显示通知时启动前台服务并设置WakeLock。

紧凑视图显示导航按钮 ShowNavigationButtonsInCompactView

如果设置为true，在紧凑视图中显示倒带和快进按钮。

紧凑视图显示跳转按钮 ShowSkipButtonsInCompactView

如果设置为true，在紧凑视图中显示SkipToNext和SkipToPrevious按钮。

小图标图片 SmallIconImage

指定用作SmallIcon的上传图像文件的名称。从API Level 23开始可用。

小系统图标 SmallSystemIcon

指定用作SmallIcon的系统图标资源名称。

事件 Events

快进 FastForward()

当用户按下快进按钮时触发。

下一个 Next()

当用户按下下一个按钮时触发。

暂停 Pause()

当用户按下暂停按钮时触发。

播放 Play()

当用户按下播放按钮时触发。

上一个 Previous()

当用户按下上一个按钮时触发。

倒带 Rewind()

当用户按下倒带按钮时触发。

跳转到 SeekTo(位置)

当用户在进度条上拖动时触发。参数表示新的位置（毫秒）。

停止 Stop()

当用户按下停止按钮时触发。

用户取消 UserCanceled()

当用户删除通知时触发。

方法 Methods

获取应用数据目录 GetAppDataDir()

获取应用程序特定数据目录的路径。

获取下载目录 GetDownloadDir()

获取下载目录的路径。

获取卷 GetVolumes()

获取卷根目录的列表。

隐藏通道 HideChannel()

隐藏通知通道。

初始化 Initialize()

初始化扩展。

通知是否活动 IsNotificationActive()

返回通知是否活动。

暂停 Pause()

暂停媒体播放器。触发Pause事件。

播放 Play()

开始媒体播放器。触发Play事件。

倒带 Rewind()

倒带媒体播放器。触发Rewind事件。

设置元数据 SetMetaData(标题,艺术家,专辑图像)

设置媒体元数据。

设置扩展元数据 SetMetaDataEx(标题,艺术家,专辑图像,持续时间)

设置扩展的媒体元数据，包括持续时间（用于进度条）。

从MediaHelper设置元数据 SetMetaDataFromMH(媒体助手组件)

从UrsMediaHelper组件获取并设置元数据。

设置暂停状态 SetStatePaused()

设置播放器状态为暂停。

设置播放状态 SetStatePlaying()

设置播放器状态为播放中。

显示通知 ShowNotification()

显示媒体通知。

显示带进度条的通知 ShowWithProgressBar(当前位置)

显示带进度条的媒体通知。

停止 Stop()

停止媒体播放器。触发Stop事件。

支持快进 SupportFastForward(启用)

启用或禁用快进按钮。

支持下一个 SupportNext(启用)

启用或禁用下一个按钮。

支持暂停 SupportPause(启用)

启用或禁用暂停按钮。

支持播放 SupportPlay(启用)

启用或禁用播放按钮。

支持上一个 SupportPrevious(启用)

启用或禁用上一个按钮。

支持倒带 SupportRewind(启用)

启用或禁用倒带按钮。

支持跳转到 SupportSeekTo(启用)

启用或禁用进度条拖动功能。

支持跳转到下一个 SupportSkipToNext(启用)

启用或禁用跳转到下一个按钮。

支持跳转到上一个 SupportSkipToPrevious(启用)

启用或禁用跳转到上一个按钮。

支持停止 SupportStop(启用)

启用或禁用停止按钮。

示例

用户界面

控件

选项

• 文件选择：可以选择本地音频文件
• 播放控制：完整的播放、暂停、停止、快进、倒带控制
• 进度控制：通过滑块控制播放位置
• 通知集成：与Android媒体通知完全集成
• 元数据显示：显示标题、艺术家和专辑图片

实现提示

1. 初始化：在Screen.Initialize中初始化MediaNotification组件
2. 元数据设置：使用SetMetaDataEx设置完整的元数据信息
3. 进度同步：定期更新CurrentPosition以保持进度条同步
4. 事件处理：处理所有MediaNotification事件以保持播放器状态一致
5. 清理：在Screen.Uninitialize中清理通知

原文链接

原版英文文档：Ullis Roboter Seite - AI2 MediaNotification

相关参考

• UrsMediaHelper 扩展
• TaifunPlayer 播放器
• 系统通知图标