更新记录

1.0.0（2026-10-30）

• VLC 视频播放器组件（Android / uvue，uni-app x 标准模式，支持蒸汽模式）
• 支持网络流（rtsp / rtmp / http-flv / hls）、本地文件、assets 资源播放
• 提供 play / playUrl / pause / resume / stop / setVolume / setTime / setRate / setVideoScale / getPlayerData / isPlaying / takeSnapShot / startRecording / stopRecording / changeScreenDirection / checkMediaValid / checkPermissions / requestPermissions / release / setConfig 等方法，并支持 success / fail 回调
• 提供 onPlayStatus / onError / onResult 事件
• 提供 url / sourceType / autoPlay / scaleType / useSurfaceView / fullScreenIsLandscape / decoderEnabled / decoderForce / startTime / imageDir / videoDir 等组件属性，url 变化自动重新播放
• 画面比例支持 SURFACE_BEST_FIT / SURFACE_FIT_SCREEN / SURFACE_FILL / SURFACE_16_9 / SURFACE_4_3 / SURFACE_ORIGINAL，旋转、全屏进出与布局变化时自动重新布局画面
• 支持全屏切换（可配置全屏强制横屏）、全屏底部操作条显隐与自动收起

平台兼容性

uni-app x(4.27)

其他

zy-vlc-play-x

基于VLC的 uni-app x 标准模式视频播放器组件，支持网络流（rtsp / rtmp / http-flv / hls）、本地文件、assets 资源，延迟低，提供播放控制、倍速、音量、进度、画面比例、截图、录制、全屏切换和播放源有效性检测。

平台支持

• uni-app x（app-android / uvue 页面）
• 组件只能在 uni-app x 页面中使用，支持蒸汽（Vapor）模式
• 需自定义基座或云打包验证制作自定义基座，标准基座不包含该库。

权限

android.permission.INTERNET
android.permission.ACCESS_NETWORK_STATE
android.permission.READ_EXTERNAL_STORAGE
android.permission.WRITE_EXTERNAL_STORAGE

截图、录像默认保存到应用外部私有目录（getExternalFilesDir()/zyVlcPlay/pictures|videos），不需要存储权限；只有显式指定 imageDir / videoDir 到公共目录时才需要存储权限。

插件 config.json / AndroidManifest.xml 已声明：

android.permission.INTERNET              // 安装时权限，网络播放自动授予，无需申请
android.permission.ACCESS_NETWORK_STATE  // 安装时权限
android.permission.READ_EXTERNAL_STORAGE // Android 6+ 危险权限，maxSdkVersion=32，按需申请
android.permission.WRITE_EXTERNAL_STORAGE// Android 6+ 危险权限，maxSdkVersion=29，按需申请

• 默认播放网络流、播放应用私有目录文件、默认目录（Android/data/<包名>/files/zyVlcPlay/...）截图录像，都不需要运行时权限。
• 只有把 imageDir / videoDir 指到公共目录（如 /storage/emulated/0/Pictures/...）时才需要存储权限；Android 13+ 这两个权限已失效，建议改用 MediaStore 或应用私有目录。
• checkPermissions / requestPermissions 不传 permissions 时按 targetSdkVersion 自动选择：<=29 申请读写存储、30~32 只申请读、>=33 不申请（直接返回已授予）。注意 targetSdk ≥ 33 时显式传 READ_EXTERNAL_STORAGE 会被系统框架拒绝（IllegalArgumentException），此时应改用 READ_MEDIA_IMAGES / READ_MEDIA_VIDEO 或继续使用应用私有目录。
• 需要时用组件方法申请，结果走 onResult 事件或 success / fail 回调：

// 检查（不传则默认检查存储权限）
playerRef.value?.checkPermissions()
// 申请（权限结果回调由框架托管，插件不接管 onRequestPermissionsResult）
playerRef.value?.requestPermissions({ permissions: ['android.permission.READ_EXTERNAL_STORAGE'] })

function onResult(action: string, code: number, msg: string, data: UTSJSONObject) {
    if (action == 'requestPermissions') {
        const granted = data['granted'] as boolean
        if (!granted) {
            // data['deniedPermissions'] 为被拒项；data['doNotAskAgain'] 为 true 时需引导去系统设置
        }
    }
}

基础用法

<template>
    <view style="flex: 1;">
        <zy-vlc-play-x ref="playerRef" :url="url" :autoPlay="true" :scaleType="scaleType"
            style="flex: 1; height: 400rpx;"
            @load="onload" @onPlayStatus="onPlayStatus" @onError="onError" @onResult="onResult"></zy-vlc-play-x>
    </view>
</template>

<script setup lang="uts">
    import { ref } from 'vue'

    const playerRef = ref<any | null>(null)
    const url = ref<string>('https://example.com/demo.mp4')
    const scaleType = ref<string>('SURFACE_BEST_FIT')

    function onload() {
        console.log('组件已就绪')
    }

    function onPlayStatus(data: UTSJSONObject) {
        console.log('播放状态', data['status'], data['time'], data['length'])
    }

    function onError(data: UTSJSONObject) {
        console.log('播放器错误', data['code'], data['msg'])
    }

    function onResult(action: string, code: number, msg: string, data: UTSJSONObject) {
        console.log('方法结果', action, code, msg, data)
    }
</script>

调用组件方法：

playerRef.value?.playUrl('rtsp://127.0.0.1/live/test')
playerRef.value?.pause()
playerRef.value?.setVideoScale('SURFACE_16_9')

配置项（props / setConfig 参数 / play 参数）

scaleType 取值：SURFACE_BEST_FIT（默认，等比适应）、SURFACE_FIT_SCREEN（等比撑满并缩放）、SURFACE_FILL（拉伸铺满）、SURFACE_16_9、SURFACE_4_3、SURFACE_ORIGINAL（原始尺寸）。

方法

所有方法都是异步的，结果统一通过 onResult 事件回传，同时支持入参的 success / fail 回调：

// 事件形式
function onResult(action: string, code: number, msg: string, data: UTSJSONObject) {}

// 回调形式
playerRef.value?.getPlayerData({
    success: (res) => { console.log(res.data) },
    fail: (err) => { console.error(err.code, err.message) }
})

code == 0 表示成功，其余为失败。

checkMediaValid 播放源无效时 code = -103；其余失败 code = -1，具体原因见 msg。

事件

onPlayStatus 频率（必读）

TimeChanged / PositionChanged 触发频率很高（每秒多次），用它们更新进度即可，不要在里面写日志或做重计算。

function onPlayStatus(data: UTSJSONObject) {
    const status = data['status'] as string
    if (status == 'TimeChanged' || status == 'PositionChanged') return
    console.log('播放状态', status)
}