示例工程前端移动开发跨平台【免费下载链接】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），仅供参考