更新记录

1.0.0（2026-10-30）

• VLC 视频播放器组件（Android / nvue）
• 支持网络流（rtsp / rtmp / http-flv / hls）、本地文件、assets 资源播放
• 提供 play / pause / resume / stop / setVolume / setTime / setRate / setVideoScale / getPlayerData / isPlaying / takeSnapShot / startRecording / stopRecording / changeScreenDirection / checkMediaValid / checkPermissions / requestPermissions / release / setConfig 等方法
• 提供 onPlayStatus / onError / onResult 事件

平台兼容性

uni-app(4.72)

其他

zy-vlc-play

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

平台支持

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

权限

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

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

基础用法

<template>
    <view style="flex:1">
        <zy-vlc-play ref="player" style="flex:1;height:400rpx" @onPlayStatus="onPlayStatus" @onError="onError"
            @onResult="onResult"></zy-vlc-play>
    </view>
</template>

<script>
    export default {
        onReady() {
            // 组件挂载后下发配置，带 url 且 isAutoPlay 不为 false 时自动播放
            this.$refs.player.setConfig({
                url: 'https://example.com/demo.mp4',
                isAutoPlay: true,
                useSurfaceView: false,
                fullScreenIsLandscape: true,
                scaleType: 'SURFACE_BEST_FIT'
            })
        },
        methods: {
            onPlayStatus(e) { console.log('播放状态', e) },
            onError(e) { console.log('错误', e) },
            onResult(e) { console.log('方法结果', e) }
        }
    }
</script>

调用组件方法：

this.$refs.player.play({ url: 'rtsp://127.0.0.1/live/test' })
this.$refs.player.pause()

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

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

方法

所有方法都是异步的，结果统一通过 onResult 事件回传：

{ type: '方法名', code: 0, msg: '提示信息', data: { ... } }

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

checkMediaValid 播放源无效时 code = -103；其余失败 code = -1。

事件

nvue 里事件参数取值（必读）

$emit 出来的对象在 nvue 里是 UTS 代理对象（{ dynamicJSONFields: {...}, jSONArray: false }），且 nvue 自定义组件回调拿到的是 weex 事件对象，真实内容在 e.detail 里。直接 e.type / e.detail.type 都取不到值，需要还原：

function unwrapUTS(obj) {
    if (obj === null || obj === undefined) return obj
    if (typeof obj !== 'object') return obj
    if (Array.isArray(obj)) return obj.map(unwrapUTS)
    if (obj.dynamicJSONFields !== undefined) {
        const fields = obj.dynamicJSONFields
        if (obj.jSONArray === true) {
            return Object.keys(fields).map(function (key) { return unwrapUTS(fields[key]) })
        }
        return unwrapUTS(fields)
    }
    const result = {}
    Object.keys(obj).forEach(function (key) { result[key] = unwrapUTS(obj[key]) })
    return result
}

// 用法
onResult(e) { const payload = unwrapUTS(e.detail) },      // { type, code, msg, data }
onPlayStatus(e) { const data = unwrapUTS(e.detail) },     // { status, length, time }
onError(e) { const data = unwrapUTS(e.detail) }           // { code, msg }

权限

插件 config.json 已声明：

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

• 默认播放网络流、播放应用私有目录文件、默认目录（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：

// 检查（不传则按 targetSdkVersion 自动选择）
this.$refs.player.checkPermissions(null)
// 申请（权限结果回调由框架托管，插件不接管 onRequestPermissionsResult）
this.$refs.player.requestPermissions([
    'android.permission.READ_EXTERNAL_STORAGE',
    'android.permission.WRITE_EXTERNAL_STORAGE'
])

onResult(e) {
    const payload = unwrapUTS(e.detail)
    if (payload.type == 'requestPermissions') {
        if (!payload.data.granted) {
            // payload.data.deniedPermissions 为被拒项；payload.data.doNotAskAgain 为 true 时需引导去系统设置
        }
    }
}