更新记录

1.0.0（2026-04-04）

• 首个正式版本，提供 uni-app x 原生视频播放组件
• 支持 Android 与 iOS 双端播放，Harmony 当前为不支持状态占位实现
• 支持 source、poster、autoplay、muted、loop、controls、objectFit、playbackRate
• 支持 play()、pause()、stop()、seek()、getCurrentTime()、getDuration()
• 支持 enterFullscreen()、exitFullscreen()、requestPictureInPicture()
• 支持 loaded、play、pause、ended、waiting、buffering、seeking、seeked、timeupdate、fullscreenchange、pictureinpicturechange、error
• 支持全屏手势、锁定控制层，以及 gesturestart、gesturechange、gestureend、lockchange
• 支持通过 createHansVideoContext(id) 获取播放器上下文进行控制

平台兼容性

uni-app x(5.06)

hans-video

hans-video 是一个面向 uni-app x 的原生视频组件，提供统一的播放控制、封面、全屏、画中画和手势交互能力。

支持平台

功能概览

• 视频源播放：支持 mp4、m3u8(HLS)
• 播放控制：play、pause、stop、seek
• 播放参数：autoplay、muted、loop、playbackRate
• 显示能力：poster、objectFit、插件自定义 controls
• 状态事件：loaded、play、pause、ended、waiting、buffering、seeking、seeked、timeupdate
• 扩展能力：enterFullscreen()、exitFullscreen()、requestPictureInPicture()
• 手势能力：快进快退、亮度、音量、锁定控制层

接入方式

将插件安装到项目的 uni_modules/hans-video 后，可直接在页面中使用 <hans-video />。

基础示例

<template>
    <view class="page">
        <hans-video
            id="video-player"
            class="player"
            :source="source"
            poster="https://example.com/poster.jpg"
            :controls="true"
            :autoplay="false"
            @loaded="handleLoaded"
            @error="handleError"
            @timeupdate="handleTimeUpdate"
        />
    </view>
</template>

<script setup lang="uts">
    import { createHansVideoContext, IHansVideoContext } from '@/uni_modules/hans-video'

    const source = ref({
        url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
        type: 'hls'
    })

    let videoContext: IHansVideoContext | null = null

    onReady(() => {
        nextTick(() => {
            videoContext = createHansVideoContext('video-player')
        })
    })

    function handleLoaded(): void {
        videoContext?.play()
    }

    function handleError(error: any): void {
        console.error('hans-video error', error)
    }

    function handleTimeUpdate(event: any): void {
        console.log('progress', event)
    }
</script>

<style>
    .page {
        padding: 24rpx;
    }

    .player {
        width: 100%;
        height: 420rpx;
    }
</style>

source 参数

source 为对象类型：

type HansVideoSourceHeader = {
    name: string
    value: string
}

type HansVideoSource = {
    url: string
    type?: string | null
    headers?: HansVideoSourceHeader[] | null
    cookies?: string[] | null
}

字段说明：

• url：视频地址，必填
• type：资源类型，可传 mp4、hls 等标识；不传时由播放器自行判断
• headers：附加请求头
• cookies：附加 Cookie 列表，插件会合并为请求头发送

Props

事件

基础事件

进度与状态事件

手势事件

HansVideoGestureEvent 包含以下字段：

• type：seek、volume、brightness
• phase：start、change、end
• fullscreen：当前是否处于全屏
• locked：当前是否已锁定控制层
• gestureZone：left、right、center
• deltaX、deltaY、targetTime、currentTime、duration、volume、brightness：按手势类型返回对应数据

上下文控制

通过 createHansVideoContext(id) 获取播放器上下文：

import { createHansVideoContext } from '@/uni_modules/hans-video'

const videoContext = createHansVideoContext('video-player')

注意事项：

• id 需要和组件上的 id 保持一致
• 需要在组件完成挂载和原生视图绑定后再获取上下文
• 若返回 null，表示当前原生视图尚未完成绑定，应在稍后重试

IHansVideoContext 方法

调试日志

插件提供可选日志开关：

import { isHansVideoLogEnabled, setHansVideoLogEnabled } from '@/uni_modules/hans-video'

setHansVideoLogEnabled(true)
const enabled = isHansVideoLogEnabled()

建议仅在联调阶段开启。

错误码

平台说明

• controls 控制的是插件自定义控制层，不是系统原生控制条
• autoplay 只影响新视频源加载后的自动起播，不用于替代运行中的 play() / pause() 控制
• 传入 poster 时，组件会在起播前和 stop() 后显示封面；不传时会尝试提取首帧作为预览
• Android 内联态默认支持横向快进快退；亮度和音量手势主要用于全屏态
• iOS 当前手势能力主要在全屏态启用
• Android 画中画需要宿主支持 PiP；iOS 画中画需要宿主启用 Background Modes -> Audio, AirPlay, and Picture in Picture

建议验证项

发布前建议至少验证以下场景：

• source、poster、controls、autoplay、muted、loop、playbackRate
• play、pause、stop、seek
• loaded、timeupdate、fullscreenchange、pictureinpicturechange、error
• 全屏、画中画、手势、锁定控制层