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

发布时间:2026/9/21 15:14:00

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/9/21 15:09:00

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

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

2026/9/21 16:09:08

Kuikly框架:基于DSL的跨平台开发实践与优化

1. Kuikly框架与DSL组件概述Kuikly是我团队开发的一款面向多端应用开发的跨平台框架,其核心创新点在于自主研发的声明式领域特定语言(DSL)组件系统。这套系统通过抽象化UI构建逻辑,让开发者可以用接近自然语言的语法描述界面结构和…

2026/9/21 16:09:08

Flutter轻量存储shared_preferences原理与最佳实践

1. 理解shared_preferences的核心定位在移动应用开发中,数据持久化是一个基础但至关重要的需求。shared_preferences作为Flutter框架中的轻量级存储解决方案,其设计初衷是为了解决应用配置、用户偏好设置等小型键值对数据的本地存储问题。与SQLite等重型…

2026/9/21 16:09:08

SAP ERP业务咨询问卷:系统配置的第一道关键决策点

简介:这是一份面向SAP ERP项目实施前期的调研问卷,适用于咨询顾问、项目经理及企业内部关键用户开展业务现状梳理与需求收集。问卷按业务模块组织,涵盖企业基本状况、库存管理、BOM与工艺路线、生产计划、采购、车间生产、产品成本、产品配置…

2026/9/21 16:09:08

哈希表原理与实战:从哈希函数设计到冲突处理与缓存应用

1. 数组做不到的事:哈希表到底在优化哪一环1.1 一次查询背后的复杂度账做后端开发的人,应该都有过这种经历:订单量从十万涨到百万,某天线上突然出现接口变慢的告警。排查到最后,发现不是数据库的问题,而是内…

2026/9/21 3:28:31

GAMP 5 基于风险的计算机化系统验证:软件分类与审计追踪实践

简介:《A Risk-Based Approach to Compliant GxP Computerized Systems》即业内熟知的GAMP 5指南,面向制药企业质量与IT合规人员、验证工程师及计算机化系统管理者,用于解决GxP法规环境下系统合规性难以科学落地的问题。文档以风险管理为主线…

2026/9/21 3:33:19

安全托管MSSP实战:从静态防御到人机协同的攻防运营与应急响应

简介:这份PPT围绕互联网业务安全托管服务展开,面向企业安全负责人、IT运维人员及关注MSSP/MSS选型的读者,重点回应传统安全过度依赖人工、碎片化静态防御难以对抗产业化攻击等痛点。资源共1个pptx文件,包体约30.63MB,以…

2026/9/21 0:02:23

OpenResearch:构建可复现的开放式研究工作流

第一次看到“OpenResearch”这个名字,我脑子里冒出的不是某个具体软件,而更像一种研究方式的宣言:开放、可复现、可验证。这三件事放在一起,其实比大多数人想象中难得多。过去几年我一直在折腾自己的研究工作流,从纯纸…

2026/9/20 4:54:47

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/20 5:01:23

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/21 10:29:02

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

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

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

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