更新记录

1.0.0（2026-07-26）

• 首次发布 hero-inline-player
• 支持 uni-app Android App 原生内嵌播放器
• 基于 AndroidX Media3 / ExoPlayer 封装
• 支持 m3u8、mp4 在线播放
• 支持播放、暂停、停止、倍速、循环、静音、画面模式切换
• 支持 seek(position) 秒级定位与毫秒级定位
• 支持进度、缓冲、播放状态、控制栏显隐等事件回调
• 支持音量、亮度调节与后台自动暂停
• 支持自定义功能挂载，可扩展业务控制层和页面交互
• 补充 README 文档，新增自定义扩展能力说明
• 补充增值功能说明，投屏功能插件和电池状态展示功能插件可联系作者单独购买

平台兼容性

uni-app(3.7.11)

其他

hero-inline-player

hero-inline-player 是一个面向 uni-app Android App 的 UTS 原生视频播放器组件，基于 AndroidX Media3 / ExoPlayer 封装，适合在页面内嵌播放 m3u8、mp4 等在线视频流。

当前版本重点解决了以下场景：

• 页面内嵌原生播放器
• seek(position) 秒级定位
• 自定义与原生控制栏协同显隐
• 支持自定义功能挂载，可围绕播放器自由扩展业务按钮、控制层、选集、线路切换和全屏交互
• 支持基于倍速能力扩展长按临时倍速播放场景，例如长按进入 3x 播放、松开恢复原倍速
• 全屏锁屏与全屏临时隐藏态
• 左右滑动快进快退
• 左右侧纵向手势调节亮度与音量
• 切换视频源时保留当前剧集与播放进度
• App 进入后台自动暂停

平台支持

• App-Android

当前未提供 App-iOS、小程序、H5 的原生实现。

依赖说明

组件内置以下 Android 依赖：

• androidx.media3:media3-exoplayer:1.4.1
• androidx.media3:media3-exoplayer-hls:1.4.1
• androidx.media3:media3-datasource:1.4.1
• androidx.media3:media3-ui:1.4.1

最低 minSdkVersion 为 21。

基础用法

<template>
    <hero-inline-player
        ref="playerRef"
        :src="src"
        :autoplay="true"
        :muted="false"
        :volume="-1"
        :brightness="-1"
        :loop="false"
        :playbackRate="1"
        :resizeMode="'contain'"
        :controllerLocked="false"
        :commandAction="playerCommandAction"
        :commandVersion="playerCommandVersion"
        :startPosition="0"
        @ready="handleReady"
        @timeupdate="handleTimeupdate"
        @ended="handleEnded"
        @error="handleError"
    />
</template>

<script>
    export default {
        data() {
            return {
                src: 'https://example.com/demo.m3u8',
                playerCommandAction: '',
                playerCommandVersion: 0
            }
        },
        methods: {
            handleReady() {},
            handleTimeupdate(e) {},
            handleEnded() {},
            handleError(e) {},
            issueCommand(action) {
                this.playerCommandAction = action
                this.$nextTick(() => {
                    if (this.playerCommandAction === action) {
                        this.playerCommandVersion += 1
                    }
                })
            },
            seekTo60s() {
                if (this.$refs.playerRef && typeof this.$refs.playerRef.seek === 'function') {
                    this.$refs.playerRef.seek(60)
                }
            }
        }
    }
</script>

Props

事件

常用事件字段包括：

• status
• message
• position
• bufferedPosition
• duration
• playerState
• isPlaying
• visible
• controllerVisible
• systemVolume
• systemVolumePercent

Ref 方法

通过 ref 可调用以下方法：

命令下发建议

commandAction 和 commandVersion 适合在模板绑定场景下驱动播放器命令。

建议始终使用下面这种顺序：

this.playerCommandAction = action
this.$nextTick(() => {
    if (this.playerCommandAction === action) {
        this.playerCommandVersion += 1
    }
})

这样可以避免原生侧在监听 commandVersion 时读取到上一条旧命令。

注意事项

1. 本组件当前仅支持 Android App。
2. volume = -1 用于避免页面初始化时主动拉起系统音量浮层。
3. 亮度调节会优先尝试系统亮度，若没有写设置权限，会回退到窗口亮度。
4. 组件支持锁屏与全屏隐藏态；若页面自己做一层自定义控制栏，建议把“原生控制栏显隐”和“页面控制栏显隐”统一管理。
5. 若页面需要拖动进度，优先调用 seek(position)，其行为更接近 uni-app videoContext.seek()。
6. 当前内置的地址类型识别已覆盖 m3u8 与 mp4；其他格式是否可用取决于 ExoPlayer 对源地址和容器格式的实际支持情况。

适用场景

• 剧集播放页
• 短剧/短视频详情页
• 需要自定义全屏交互的播放器页面
• 需要原生 m3u8 / mp4 播放能力的 uni-app Android 项目

自定义扩展能力

本插件不只是一个固定样式的播放器组件，也可以作为业务播放器内核使用。

开发者可围绕播放器自由接入自定义功能，例如：

• 自定义顶部栏、底部栏
• 自定义播放控制按钮
• 自定义全屏/小窗交互
• 自定义选集面板
• 自定义线路切换
• 自定义长按临时倍速播放交互
• 自定义手势交互联动
• 自定义业务状态展示
• 自定义页面层控制栏显隐逻辑

适合需要保留原生播放能力，同时接入自有业务功能的项目场景。

增值功能

• 投屏功能插件可联系作者单独购买
• 电池状态展示功能插件可联系作者单独购买