更新记录

1.5.2（2026-06-04）

• 支持鸿蒙端

1.5.1（2026-06-01）

• IOS侧支持当视频为4:3时显示全屏观看按钮

1.5.0（2026-05-31）

• MD文档修改

平台兼容性

uni-app x(4.66)

xwq-player-video

xwq-player-video 是一个面向 uni-app x 的原生视频播放组件，当前主要用于短视频列表、详情页续播以及带预加载的播放场景。

目录导航

• 快速上手摘要
• 组件 Props
• 页面调用示例
• 组件事件
• 组件暴露方法
• 使用注意事项
• 推荐配置速查表
• 常见问题 FAQ
• 错误现象排查建议表
• 推荐接入流程
• 可直接复制的数据模板
• VideoType 数据说明
• VideoType 字段说明
• ToolInfoType 字段补充

快速上手摘要

首次接入建议先记住下面这几条：

• 普通公开视频地址：优先使用 httpCache=true、preloadVideo=true
• 带 author_key= 的签名地址：优先使用 httpCache=false、preloadVideo=true
• author_key= 只表示会自动走直连预加载链路，不代表一定要配置 customReferer 或 customUserAgent
• 只有源站明确要求校验 Referer / User-Agent 时，才需要传 customReferer、customUserAgent
• customReferer、customUserAgent 传空串会自动忽略，不会误触发自定义请求头逻辑
• 页面接入时可以直接参考下方“页面调用示例”，数据源可以直接复制“可直接复制的数据模板”里的模板

最常用的参数组合可以直接参考：

推荐先从这三个模板里选一个开始接入：

• normalVideoListTemplate：普通公开地址
• authorKeyVideoListTemplate：签名地址但不需要额外请求头
• authorKeyWithHeadersVideoListTemplate：签名地址且需要额外请求头

最小可运行示例：

<template>
    <xwq-player-video
        :list="videoList"
        :httpCache="true"
        :preloadVideo="true"
        :showProgress="true"
        objectFit="FIXED_HEIGHT"
    />
</template>

<script setup lang="uts">
    import type { VideoType } from '@/uni_modules/xwq-player-video/utssdk/interface'

    const videoList : Array<VideoType> = normalVideoListTemplate
</script>

模板替换说明：

• 普通公开视频地址：使用 normalVideoListTemplate
• 带 author_key= 的签名地址且不需要额外请求头：使用 authorKeyVideoListTemplate
• 带 author_key= 的签名地址且源站还要求 Referer / User-Agent：使用 authorKeyWithHeadersVideoListTemplate

组件 Props

下表整理自 components/xwq-player-video/xwq-player-video.uvue。

补充说明：

• 鸿蒙端当前倍速能力请仅使用 0.5、0.8、1.0、1.25、1.5
• 如果业务侧自行扩展倍速面板或自定义传值，建议不要传 0.75、1.75、2.0 等鸿蒙未支持的档位，避免出现切换后异常或黑屏

页面调用示例

下面按常见接入场景拆成两套示例。

示例 1：普通直链视频

适用于公共 CDN、普通 MP4 地址、无额外请求头要求的视频源。

<template>
    <view class="page-wrap">
        <xwq-player-video
            ref="playerRef"
            :list="videoList"
            :autoNext="false"
            :httpCache="true"
            :preloadVideo="true"
            :showProgress="true"
            objectFit="FIXED_HEIGHT"
            @onLoadNext="handleLoadNext"
            @onChange="handlePlayerChange"
            @onTimeUpdate="handleTimeUpdate"
        />
    </view>
</template>

<script setup lang="uts">
    import { ref } from 'vue'
    import xwqPlayerVideo from '@/uni_modules/xwq-player-video/components/xwq-player-video/xwq-player-video.uvue'
    import type { VideoType } from '@/uni_modules/xwq-player-video/utssdk/interface'

    let playerRef = ref<InstanceType<typeof xwqPlayerVideo> | null>(null)
    const videoList : Array<VideoType> = normalVideoListTemplate

    const handleLoadNext = () => {
        console.log('加载下一页数据')
    }

    const handlePlayerChange = (detail : UTSJSONObject) => {
        console.log('当前播放视频变化', detail)
    }

    const handleTimeUpdate = (detail : UTSJSONObject) => {
        console.log('播放进度更新', detail)
    }
</script>

<style>
    .page-wrap {
        flex: 1;
    }
</style>

示例 2：带 author_key 的签名地址，但不需要额外请求头

适用于以下场景：

• 视频地址带有 author_key= 这类签名参数
• 源站本身不要求额外校验 Referer 或 User-Agent
• 首播不适合走普通代理缓存链路

说明：

• author_key= 链接会自动走直连预加载链路
• 这种场景下通常不需要配置 customReferer 或 customUserAgent

<template>
    <view class="page-wrap">
        <xwq-player-video
            :list="videoList"
            :autoNext="false"
            :httpCache="false"
            :preloadVideo="true"
            :showProgress="true"
            objectFit="FIXED_HEIGHT"
        />
    </view>
</template>

<script setup lang="uts">
    import type { VideoType } from '@/uni_modules/xwq-player-video/utssdk/interface'

    const videoList : Array<VideoType> = authorKeyVideoListTemplate
</script>

<style>
    .page-wrap {
        flex: 1;
    }
</style>

示例 3：既有签名地址，又要求请求头

适用于以下场景：

• 视频地址带有 author_key= 这类签名参数
• 源站同时还要求校验 Referer 或 User-Agent

<template>
    <view class="page-wrap">
        <xwq-player-video
            :list="videoList"
            :autoNext="false"
            :httpCache="false"
            :preloadVideo="true"
            :showProgress="true"
            objectFit="FIXED_HEIGHT"
            customReferer="https://example.xxxx.cn/"
            customUserAgent="AppleCoreMedia/1.0.0.21E230 (iPhone; U; CPU OS 17_4 like Mac OS X; zh_cn)"
        />
    </view>
</template>

<script setup lang="uts">
    import type { VideoType } from '@/uni_modules/xwq-player-video/utssdk/interface'

    const videoList : Array<VideoType> = authorKeyWithHeadersVideoListTemplate
</script>

<style>
    .page-wrap {
        flex: 1;
    }
</style>

如果你只是想表达“这是一个签名地址，但不需要额外请求头”，最小配置可以简化成下面这样：

<xwq-player-video
    :list="videoList"
    :httpCache="false"
    :preloadVideo="true"
    :showProgress="true"
    objectFit="FIXED_HEIGHT"
/>

组件事件

下表整理自 components/xwq-player-video/xwq-player-video.uvue 中 defineEmits 和事件转发逻辑。

组件暴露方法

下表整理自 components/xwq-player-video/xwq-player-video.uvue 中 defineExpose 暴露的方法。

使用注意事项

1. httpCache 适用场景

• 普通直链视频、公共 CDN 地址、无额外鉴权限制的视频地址，优先考虑开启 httpCache
• 开启后，iOS 侧会优先走代理缓存链路，有利于复播和滑动列表时复用已缓存片段
• 如果视频地址本身带有强校验、防盗链、签名鉴权或时效性参数，需要结合下面几条一起判断

2. preloadVideo 适用场景

• 当首个视频起播较慢，或滑动到下一条视频时存在明显等待，可以开启 preloadVideo
• 开启后，组件会在首屏和滑动切换后提前预热后续视频
• 对短视频连续播放场景更有帮助，单视频详情页是否开启取决于你的页面交互和带宽策略

3. customUserAgent / customReferer 适用场景

• 如果视频源站要求特定 User-Agent 或 Referer，需要显式传入 customUserAgent、customReferer
• 只要这两个参数中任意一个传入非空值，iOS 侧就会走自定义请求头的直连预加载与播放链路
• 空串或只包含空白字符的值会被自动忽略，不会误触发自定义请求头逻辑

4. author_key 链接说明

• 如果视频地址中包含 author_key= 这类签名参数，即使没有配置 customUserAgent 或 customReferer，iOS 侧也会走直连预加载链路
• 这样做是为了避免代理缓存链路对部分带签名地址的首播和预加载稳定性造成影响
• 这类地址建议优先配合 preloadVideo 使用，通常不建议把它当作纯普通缓存地址处理
• 只有当源站明确要求校验 Referer / User-Agent 时，才需要继续配置 customUserAgent 或 customReferer

5. 参数组合建议

6. 鸿蒙端倍率使用限制

• 鸿蒙端当前建议仅使用 0.5、0.8、1.0、1.25、1.5 这 5 档倍率
• 如果你在业务层自定义了倍速面板，建议保持和插件内置鸿蒙档位一致
• 不建议在鸿蒙端传 0.75、1.75、2.0 等未支持档位，否则可能出现倍率切换异常、切视频黑屏或播放状态不稳定

推荐配置速查表

如果你只想快速判断参数怎么配，可以直接参考下表。

常见问题 FAQ

1. 为什么开启 httpCache 后反而出现黑屏或首播异常？

• 常见原因是视频地址带有防盗链、签名鉴权、时效性参数，代理缓存链路转发后源站校验失败
• 这类场景建议优先关闭 httpCache，并开启 preloadVideo
• 如果源站还要求特定请求头，需要继续配置 customUserAgent 或 customReferer

2. 为什么 author_key 链接不会走代理首播链路？

• author_key= 这类地址通常属于带签名的时效性播放地址
• 为了减少代理缓存链路对签名校验和首播稳定性的影响，iOS 侧会把这类地址归到直连预加载链路
• 所以即使打开了 httpCache，这类链接首播和预加载仍然会优先按直连方式处理

3. author_key 链接是不是一定要配置 customUserAgent / customReferer？

• 不一定
• author_key= 只表示该地址会自动走直连预加载链路，不代表源站一定要求额外请求头
• 只有当你的服务端或源站明确要求校验 Referer / User-Agent 时，才需要配置这两个参数

4. 什么情况下必须配置 customUserAgent / customReferer？

• 当视频源站明确要求校验 User-Agent 或 Referer 时必须配置
• 常见现象包括：浏览器里能播、App 里不能播，或者直接返回 403、无数据、首播一直等待
• 如果不确定源站是否要求这些头，可以先抓服务端日志或网络日志确认

5. customUserAgent / customReferer 传空串会怎么样？

• 空串或只包含空白字符的值会被自动忽略
• 这种情况下不会触发自定义请求头逻辑，播放器会按普通地址处理
• 这意味着你可以安全地把这两个字段作为可选配置透传给插件

6. 为什么开启 preloadVideo 后还是感觉第一个视频慢？

• preloadVideo 更擅长优化首屏之后的视频切换体验，以及首个视频的资源准备链路
• 如果第一个视频本身地址响应慢、鉴权慢、DNS 慢，预加载也无法完全抵消源站本身的耗时
• 这时建议优先检查视频源响应速度、签名地址生成时机，以及是否需要自定义请求头

7. httpCache 和 preloadVideo 可以同时开启吗？

• 可以，同时开启时会根据地址类型自动选择更合适的链路
• 普通地址更偏向代理缓存链路，带请求头或带 author_key 的地址更偏向直连预加载链路
• 如果你的列表里混合了多种视频地址，这是比较推荐的配置方式之一

8. 鸿蒙端为什么切换倍率后再切视频可能黑屏？

• 常见原因是传入了鸿蒙未支持的倍率档位，而不是业务层切页逻辑本身有问题
• 鸿蒙端请优先确认当前倍率是否属于 0.5、0.8、1.0、1.25、1.5
• 如果你自己封装了自定义倍速按钮或弹窗，建议直接复用这组档位，不要额外扩展成 Android / iOS 的档位集合

错误现象排查建议表

如果你遇到的不是“不会配参数”，而是“已经接上了但表现不对”，可以先对照下面这张表排查。

推荐接入流程

如果你是第一次接入这个插件，建议按下面顺序验证，能更快定位问题属于“地址本身”、“签名链路”还是“请求头要求”。

第一步：先用普通地址验证基础播放

• 先准备一个无需鉴权、无需额外请求头的普通 MP4 或 CDN 地址
• 建议先配置：httpCache=true、preloadVideo=true
• 先确认基础播放、切换下一条、进度更新、事件回调都正常

第二步：再验证签名地址是否能正常播放

• 把数据源切换成带 author_key= 的签名地址
• 先不要急着配置 customReferer / customUserAgent
• 建议先配置：httpCache=false、preloadVideo=true
• 如果此时能正常播放，说明你的源站只是签名地址，不一定要求额外请求头

第三步：如果签名地址失败，再判断是否需要请求头

• 如果带 author_key 的地址依然黑屏、403 或一直等待
• 再确认源站是否要求校验 Referer / User-Agent
• 只有在源站明确要求的情况下，再追加 customReferer、customUserAgent

第四步：最后再决定是否重新开启 httpCache

• 普通公开地址通常可以保留 httpCache=true
• 带签名参数、带时效性校验或带特殊源站限制的地址，通常建议优先保持 httpCache=false
• 如果你一定要在复杂源站场景下开启缓存，建议先做真机验证，不要只依赖单个测试地址

第五步：列表场景重点验证首屏和下一条

• 确认第一个视频起播时间是否可接受
• 确认滑动到下一条、下下条时是否明显变快
• 如果首屏正常但切换慢，优先检查 preloadVideo
• 如果普通地址正常但签名地址异常，优先检查 author_key 链路和请求头配置

可直接复制的数据模板

下面把 README 里示例使用到的 videoList 模板统一整理出来，接入时可以直接复制后改地址和文案。

模板 1：普通直链视频列表

const normalVideoListTemplate : Array<VideoType> = [
    {
        isPlaying: false,
        duration: 0,
        vduser: '追风少女',
        nickname: '妈妈不要哭泣',
        videoId: '672b6be8e4ca03e4581a0063',
        playurl: 'https://example.com/short_dram/002.mp4',
        vdtitle: '01黄亚男早年丧偶，带着年幼的两个儿子和一个女儿艰难度日',
        position: 0,
        showTitleArrow: true,
        toolInfo: [
            { icon: 'shoucang', text: '追剧' },
            { icon: 'dianzan', text: '点赞', num: 99 },
            { icon: 'share', text: '分享' }
        ],
        showLookAllBtn: true,
        lookAllBtnText: '观看完整短剧 · 全80集1',
        showBottomArea: false,
        bottomAreaBtnText: '选集 · 全80集 · vip免费'
    }
]

模板 2：author_key 签名地址列表

const authorKeyVideoListTemplate : Array<VideoType> = [
    {
        isPlaying: false,
        duration: 0,
        vduser: '追风少女💓( ˘ ³˘)💋',
        nickname: '签名短剧示例',
        videoId: 'author-key-demo-001',
        playurl: 'https://example.com/video/001.m3u8?author_key=abc123',
        vdtitle: '示例：带签名参数的短剧视频地址',
        position: 0,
        showTitleArrow: true,
        toolInfo: [
            { icon: 'shoucang', text: '追剧' },
            { icon: 'dianzan', text: '点赞', num: 99 },
            { icon: 'share', text: '分享' }
        ],
        showLookAllBtn: true,
        lookAllBtnText: '观看完整短剧 · 全80集1',
        showBottomArea: false,
        bottomAreaBtnText: '选集 · 全80集 · vip免费'
    }
]

模板 3：author_key + 自定义请求头列表

const authorKeyWithHeadersVideoListTemplate : Array<VideoType> = [
    {
        isPlaying: false,
        duration: 0,
        vduser: '追风少女💓( ˘ ³˘)💋',
        nickname: '签名 + 请求头示例',
        videoId: 'author-key-header-demo-001',
        playurl: 'https://example.xxxx.cn/static/ceshi/263.mp4?author_key=abc123',
        vdtitle: '示例：签名地址且源站要求附加请求头',
        position: 0,
        showTitleArrow: true,
        toolInfo: [
            { icon: 'shoucang', text: '追剧' },
            { icon: 'dianzan', text: '点赞', num: 99 },
            { icon: 'share', text: '分享' }
        ],
        showLookAllBtn: true,
        lookAllBtnText: '观看完整短剧 · 全80集1',
        showBottomArea: false,
        bottomAreaBtnText: '选集 · 全80集 · vip免费'
    }
]

VideoType 数据说明

VideoType 的可直接复制示例已经统一整理到上面的 可直接复制的数据模板 小节。

• 普通公开地址示例：normalVideoListTemplate
• author_key 签名地址示例：authorKeyVideoListTemplate
• author_key + 自定义请求头示例：authorKeyWithHeadersVideoListTemplate

下面保留字段级说明，方便你按需自行组装数据源。

VideoType 字段说明

下表整理自 utssdk/interface.uts 中的 VideoType。

ToolInfoType 字段补充

VideoType.toolInfo 中每一项都应满足以下结构：

其他插件预览

• （兼容安卓、IOS）UTS 车牌识别插件

• (兼容IOS、安卓、鸿蒙)二维码、条码识别，mlkit扫码插件 毫秒级识别效率，支持多码识别，连续扫

• TTS（安卓、ios、鸿蒙、web）将文字转成语音播报

• （兼容安卓、IOS端）离线语音识别插件、支持离线语音

• （UNIAPPX原生播放器）仿抖音视频刷刷刷 刷视频 自动滑动视频，短剧刷视频必备神器

• (安卓、IOS) PDF预览插件

• (兼容安卓、鸿蒙端、iOS)onnx 大模型实时语音识别 wav音频文件转文本

• （兼容安卓、鸿蒙）录音插件，支持pcm实时回调，wav转换，后台录音

• （nvue）app端仿抖音短视频 丝滑切换视频效果，无限数据加载

• 兼容安卓、IOS端支持全局消息弹窗插件

• (支持安卓和IOS端)原生UTS组件svg插件

• （兼容IOS和安卓Web三端）SVGA 动画组件 支持自定义文本、图片，图层隐藏功能

• 系统权限验证、获取、跳转

• （兼容安卓、IOS、鸿蒙）二维码 qrcode 自定义logo图片 颜色可自定义

• 仿抖音短视频微信小程序 丝滑切换视频效果，无限数据加载不卡顿，咨询进IM交流群