uni-app x Android 原生集成 uni-video 视频组件模块:依赖配置、组件注册与底层实现全指南

发布时间:2026/11/17 10:34:25

uni-app x Android 原生集成 uni-video 视频组件模块:依赖配置、组件注册与底层实现全指南 示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载uni-app x 在 Android 平台上通过原生 SDK 打包时video组件由uni-video原生模块提供底层能力。本文以官方文档 docs/native/modules/android/uni-video.md 为核心骨架完整讲解 HBuilderX 5.08 以上与 5.08 以下两套集成方案本地依赖库、线上 Maven 依赖、模块依赖、组件注册并结合仓库源码config.json、VideoImpl.kt深入剖析 AndroidX Media3/ExoPlayer 的底层实现。读者阅读完本文将掌握在 Android 主工程中完整接入uni-video模块、正确注册video组件并排查集成问题的全部实战能力。一、uni-video 模块与集成时机uni-video是 uni-app x 中video组件在 Android 端的原生实现模块。当你使用原生 SDK 方式打包而非云打包时若页面中使用了video组件就必须在主工程中手动集成该模块的依赖库并完成组件注册否则运行期将提示组件未注册或直接渲染失败。从当前仓库源码看该模块的 uts 插件源码位于 src/uni_modules/uni-video 目录其 Android 侧配置 config.json 明确声明了所依赖的线上库{ dependencies: [ androidx.media3:media3-exoplayer:1.8.0, androidx.media3:media3-exoplayer-hls:1.8.0 ] }这印证了 5.08 之后 Android 端播放内核全面切换到AndroidX Media3ExoPlayer的事实与集成文档中的线上依赖完全一致。需要特别注意的是HBuilderX 5.08 是集成方式的版本分水岭5.08 以上使用新的UTSEasyCom组件注册机制与 Media3 播放内核5.08 以下使用旧的UTSRegisterComponents注册机制与 ijkplayer 播放内核。请先确认你的 HBuilderX 版本再选择对应章节操作。二、HBuilderX 5.08 以上版本的集成配置2.1 本地依赖库需要将本地依赖库uni-video-release.aar复制到 app 项目的libs目录下。名称uni-video-release.aar该 aar 提供模块的注册类与组件类实现复制完成后需确保主模块build.gradle中已通过fileTree方式引入 libs 目录一般模板工程已默认配置dependencies { implementation fileTree(include: [*.aar], dir: libs) ... }2.2 线上依赖库在 app 项目的build.gradle中声明 Media3 播放内核依赖。Groovy DSL 写法dependencies { implementation androidx.media3:media3-exoplayer:1.8.0 implementation androidx.media3:media3-exoplayer-hls:1.8.0 }使用 Kotlin DSLbuild.gradle.kts的工程写法dependencies { implementation(androidx.media3:media3-exoplayer:1.8.0) implementation(androidx.media3:media3-exoplayer-hls:1.8.0) }参数说明media3-exoplayerMedia3 的核心播放器ExoPlayer实现负责音视频解码、渲染与播放控制media3-exoplayer-hlsHLS 流媒体协议的支持库用于播放 m3u8 直播/点播源版本号1.8.0由模块 config.json 与官方文档共同确认升级版本时需自行验证兼容性。2.3 模块依赖uni-video模块运行时还依赖以下内置模块需要同步集成到 app 项目中集成方式可参考 docs/native/modules/android/others.md名称uni-fileSystemManageruni-getSystemInfouni-screenBrightness特别说明蒸汽模式Vapor还需额外依赖uni-event模块。Vapor 是 uni-app x 的轻量渲染模式详见 docs/app-vapor.md其组件事件分发机制依赖事件总线因此必须补上uni-event。2.4 组件注册将以下内容添加到主模块的build.gradle中具体原理详见 根据 configjson 配置应用 的components一节。Groovy DSLVDOM 模式defaultConfig { buildConfigField String, UTSEasyCom, [{\class\:\uts.sdk.modules.DCloudUniVideo.UniVideoExtApiComponentsRegister\,\method\:\register\}] }Kotlin DSLVDOM 模式defaultConfig { buildConfigField(String, UTSEasyCom, \[{\\\class\\\:\\\uts.sdk.modules.DCloudUniVideo.UniVideoExtApiComponentsRegister\\\,\\\method\\\:\\\register\\\}]\) }配置要点UTSEasyCom是 5.08 之后新增的注册字段注册方式从声明组件类演进为声明 Register 类 register 方法由UniVideoExtApiComponentsRegister.register()在运行时完成video组件的注册反斜杠转义符不能删减JSON 字符串格式必须严格一致否则运行时解析失败若主模块已存在UTSEasyCom字段需要将原有内容与新增内容合并为同一个 JSON 数组字符串后整体写入暂不支持在 build.gradle 中设置applicationIdSuffix添加该配置会导致组件初始化失败。三、HBuilderX 5.08 以下版本的集成配置如果你的 HBuilderX 版本低于 5.08请使用本节配置。该方案对应旧的 ijkplayer 播放内核与UTSRegisterComponents注册机制。3.1 本地依赖库需要将以下三个本地依赖库全部复制到 app 项目的libs目录下名称uni-video-release.aarijkplayer.aarvideoplayer.aar其中ijkplayer.aar为 ijkplayer 播放内核封装videoplayer.aar为视频播放器组件封装三者缺一不可。3.2 线上依赖库在 app 项目的build.gradle中添加以下线上依赖dependencies { implementation com.github.bumptech.glide:glide:4.9.0 implementation androidx.annotation:annotation:1.1.0 implementation androidx.core:core:1.1.0 }Kotlin DSL 写法dependencies { implementation(com.github.bumptech.glide:glide:4.9.0) implementation(androidx.annotation:annotation:1.1.0) implementation(androidx.core:core:1.1.0) }参数说明glide:4.9.0图片加载库用于视频封面poster等图片资源的加载展示androidx.annotation:annotation:1.1.0与androidx.core:core:1.1.0旧版播放器依赖的 AndroidX 基础库。3.3 组件注册旧版使用UTSRegisterComponents字段直接声明video组件与实现类。Groovy DSLdefaultConfig { buildConfigField String, UTSRegisterComponents, \[{\\\name\\\:\\\video\\\,\\\class\\\:\\\uts.sdk.modules.DCloudUniVideo.VideoComponent\\\}]\ }Kotlin DSLdefaultConfig { buildConfigField(String, UTSRegisterComponents, \[{\\\name\\\:\\\video\\\,\\\class\\\:\\\uts.sdk.modules.DCloudUniVideo.VideoComponent\\\}]\) }配置要点name字段为video即页面模板中使用的标签名class字段为组件实现类uts.sdk.modules.DCloudUniVideo.VideoComponent与 5.08 方案相同转义符不可删减JSON 格式必须严格一致若已有其他组件的UTSRegisterComponents配置需要将新旧条目合并到同一个 JSON 数组字符串中。四、两种版本方案的对比与升级建议对比维度HBuilderX ≥ 5.08HBuilderX 5.08播放内核AndroidX Media3ExoPlayer 1.8.0ijkplayer本地 aaruni-video-release.aaruni-video-release.aar、ijkplayer.aar、videoplayer.aar线上依赖media3-exoplayer、media3-exoplayer-hlsglide、androidx.annotation、androidx.core注册字段UTSEasyComRegister 类 register 方法UTSRegisterComponents组件类直连注册类UniVideoExtApiComponentsRegisterVideoComponent额外模块依赖uni-fileSystemManager、uni-getSystemInfo、uni-screenBrightnessVapor 另需 uni-event—旧版接口从 docs/native/modules/ios/modules.md 的 iOS 侧文档同样可以看到这一版本分界5.08 之前 uni-video 依赖IJKMediaFrameworkWithSSL5.08 之后改用基于UniVideoPlayerManager的全新播放器实现。Android 与 iOS 在 5.08 节点同步完成了播放内核的升级升级 HBuilderX 后务必同步切换集成配置避免新旧 aar 混用导致类冲突。五、源码级解析Media3/ExoPlayer 如何驱动 video 组件集成配置的背后是 VideoImpl.kt 对 Media3 ExoPlayer 的完整封装。该文件位于 src/uni_modules/uni-video/utssdk/app-android/VideoImpl.kt是理解video组件底层行为的最佳入口。5.1 组件本质TextureView ExoPlayer从源码结构看VideoImpl类继承自TextureView并实现了TextureView.SurfaceTextureListener与Player.ListenerVideoImpl.kt。即 Android 端的video组件本质上是一个绑定 ExoPlayer 输出的 TextureView 原生视图视频帧直接渲染到纹理表面这也是它能与 uni-app x 的 VDOM/Vapor 渲染树无缝结合的原因。5.2 属性到播放器的映射源码中多个属性 setter 直接驱动 ExoPlayer 能力与 docs/component/video.md 中的组件属性一一对应autoplay设置player.playWhenReadyloop设置player.repeatMode为REPEAT_MODE_ONEmuted切换player.volume为 0 或 1playbackRate调用player.setPlaybackSpeed对应组件的播放速率控制src非空且 surface 可用时调用setupSource装载数据源。从源码还可以看到播放器还使用了CacheDataSourceSimpleCacheLeastRecentlyUsedCacheEvictor淘汰策略来实现http-cache属性VideoImpl.kt即对 http/https 视频源的本地缓存能力同时通过DefaultRenderersFactory支持codec属性的硬件/软件解码器切换。5.3 进度上报与事件回调源码中使用主线程Handler周期性回调onTimeUpdate并在播放到userDuration终点时触发onEndedVideoImpl.kt。这一机制支撑了组件层的timeupdate、ended等事件也解释了duration属性未指定时取播放器实际时长的行为。5.4 组件层封装ut 组件层封装位于 src/uni_modules/uni-video/components/video/video.uvue仓库示例页 src/pages/component/video/video.uvue 提供了video组件的完整使用示例含 src、autoplay、controls、object-fit 等属性的典型组合。集成 uni-video 模块后即可直接运行这些示例页验证效果。六、video 组件核心属性速览完成模块集成与组件注册后video组件即可在页面中使用。其常用属性详见 docs/component/video.md包括属性类型默认值说明srcstring—视频资源地址autoplaybooleanfalse是否自动播放loopbooleanfalse是否循环播放mutedbooleanfalse是否静音播放controlsbooleantrue是否显示默认播放控件object-fitstringcontain视频与容器尺寸不一致时的表现contain/fill/coverposterstring—视频封面图controlsfalse 时无效codecstringhardware解码器选择http-cachebooleanfalse是否对 http/https 视频源开启本地缓存initial-timenumber0指定视频初始播放位置在 Android 端codec、http-cache等能力均已在 VideoImpl.kt 中有对应的原生实现可直接放心使用。七、集成检查清单与常见问题完成配置后建议按以下清单逐项自检版本对齐确认 HBuilderX 版本选用 5.08± 对应的整套配置新旧方案配置混用如同时出现UTSEasyCom与UTSRegisterComponents会导致组件重复注册或注册失败aar 就位确认所有本地 aar 已复制到 app 项目的libs目录且主模块 build.gradle 已引入 libs 目录转义符完整buildConfigField中的反斜杠转义符不可删减JSON 格式必须严格一致字段合并多个模块同时注册组件时需将各自条目合并到同一个数组字符串而非覆盖式写入模块依赖齐全确认 uni-fileSystemManager、uni-getSystemInfo、uni-screenBrightnessVapor 模式再加 uni-event均已按 docs/native/modules/android/others.md 完成集成禁止 applicationIdSuffix主模块 build.gradle 中不要设置applicationIdSuffix否则组件初始化失败事件与属性验证集成完成后使用 src/pages/component/video/video.uvue 示例页验证播放、进度上报、循环、静音等行为是否符合预期。八、延伸阅读uni-video 模块官方集成文档本文的配置依据原文含完整 gradle 代码块根据 configjson 配置应用UTSEasyCom/UTSRegisterComponents字段的通用配置规则与合并写法video 组件完整文档组件全部属性、事件与兼容性说明Android 模块总览uni-video 所依赖的其它内置模块的集成方式iOS uni-video 集成参考5.08 版本分界在 iOS 侧的对应实现便于跨端对齐uni-video uts 插件源码组件层与 Android 原生层完整实现包括 config.json 与 VideoImpl.kt。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x Android 原生工程集成 uni-verify 一键登录模块依赖配置、应用 ID 与插件注册完整指南uni app x Android 原生工程集成 uni verify 一键登录模块依赖配置、应用 ID 与插件注册完整指南 uni app x 的 App示例工程前端移动开发跨平台uni-app uni-oauth Android 集成指南微信登录 SDK 依赖配置与插件注册详解uni app uni oauth Android 集成指南微信登录 SDK 依赖配置与插件注册详解 本文是 uni app 开源仓库中 Android 原生示例工程前端移动开发跨平台uni-app x Android 实人认证原生模块 uni-facialRecognitionVerify 集成指南uni app x Android 实人认证原生模块 uni facialRecognitionVerify 集成指南 uni facialRecognitio示例工程前端移动开发跨平台上一篇PaddleOCR 多场景模型推理部署指南Python / C / Serving / Paddle-Lite / ONNX 全链路方案解析下一篇DeepSpeedExamples目标检测YOLOv5分布式训练实战创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/17 10:34:25

Java日期处理:获取N天前日期的最佳实践

1. 需求背景与场景解析在日常开发中,处理日期时间是最基础却最容易出错的环节之一。上周我就遇到一个典型场景:业务系统需要自动生成以"yyyyMMdd"格式命名的报表文件,但必须基于两周前的日期作为基准。类似这种"获取N天前日期…

2026/11/17 10:30:08

如何快速学习考电工证证全国通用吗

电工证怎么考能一次过?通过率揭秘+备考干货全在这里 怕考不过白交培训费?你不是一个人在战斗。现在考电工证的人越来越多,但真正能一次过的人并不多。很多人花了几千块报班,结果一到考场就懵,白白浪费钱不说,还耽误了工作机会。这背后其实有个关键问题…

2026/11/17 10:30:08

大学本科期间考电工证的真实经历:怕考不过白交培训费怎么办?

大学本科期间考电工证的真实经历:怕考不过白交培训费怎么办? 怕考不过白交培训费?我大学期间就踩过坑,差点花了几千块打水漂。电工证虽然不是毕业必备,但在实习、兼职甚至毕业后找工作时都派得上用场,尤其是想进入电力、建筑、工程类岗位的同学,电工证…

2026/11/17 10:30:08

汝阳高压电工证报考过期了怎么复审?含金量高不高值得考

汝阳高压电工证报考过期了怎么复审?含金量高不高值得考 证书过期了不知道怎么复审延期?别慌,今天一次性说清楚汝阳高压电工证报考、复审流程和含金量,尤其是对开封水利工程从业者来说,这个证到底值不值得考。…

2026/11/17 10:30:08

侯马报考电工证在哪里考官方报名入口在哪找

侯马报考电工证在哪里考官方报名入口在哪找 学历不高怕报不上名?别担心,侯马报考电工证在哪里考,其实比你想象的简单多了,关键是要找对官方报名入口。别再被一些培训机构忽悠了,今天就来帮你理清思路,从报名到拿证,一条路走到底。…

2026/11/17 10:25:08

祥符区报考电工证官方回应:证书过期了怎么复审延期

祥符区报考电工证官方回应:证书过期了怎么复审延期 证书过期了不知道怎么复审延期,这事儿可不能拖。很多人一忙起来就忘了证书的有效期,结果发现到期了,连能不能继续干都成问题。别急,官方回应早就出来了,流程其实并不复杂,关键是得知道怎么操作。今天…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/17 0:02:41

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期 证书过期了不知道怎么复审延期,这种情况在电工圈里太常见了。我有个同事,去年刚把低压电工证给弄丢了,直到单位查岗才发现证书已经过期,差点被停工处理。今天就用我真实经历给你讲讲电工证操作…

2026/11/17 0:02:41

机修需不需要电工证 在哪考最靠谱 这些细节必须知道

机修需不需要电工证 在哪考最靠谱 这些细节必须知道 之前考的证在外省能不能转过来?这个问题几乎每个特种作业从业者都问过。特别是像你这样,之前在外省考了证,现在想在本地扎根,或者想换证、换岗的机修人员,最关心的就是【机修需不需要电工证】和【在…

2026/11/17 0:02:41

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么 工地太忙根本没时间复习考试,我理解你。作为一名刚从焦作工程类院校毕业的学生,我也经历过这种困扰。电工证年检步骤是什么,听起来简单,但实际操作中,很多人因为流程不清楚、资料准备不…

2026/11/17 0:49:41

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑