项目8 视频播放器应用

项目8视频播放器应用目录1项目描述2学习目标3知识图谱4技术准备5项目实施6项目小结7AI赋能1项目描述本项目旨在创建一个视频播放器应用。该应用能够获取本地存储视频，通过AVPlayer进行视频播放控制，实现播放/暂停、视频切换、倍速播放、进度控制、音量调节等功能。视频播放界面支持全屏播放。应用运行效果如图8-1、图8-2、图8-3所示。

图8-1主界面视频列表效果

图8-2视频播放界面效果

图8-3全屏播放效果2学习目标知识目标1．理解HarmonyOS多媒体开发框架MediaKit的核心功能及其应用场景2．掌握AVPlayer组件的功能特性和状态机生命周期3．掌握XComponent组件在视频渲染中的角色及其与AVPlayer的协作机制4．掌握PanGesture手势控制的用法技能目标能够使用ArkTS实现视频播放器素质目标1．培养用户导向的设计思维2．培养规范的编程习惯，强化资源管理安全意识3知识图谱本项目所涉及的知识图谱以“视频播放器应用”为核心，系统梳理了构建该应用的核心知识体系。图谱采用中心辐射式结构，在核心主题节点下延伸出六大模块，直观呈现了从MediaKit简介、获取本地视频资源、AVPlayer状态机管理、XComponent视频渲染、播放控制功能到PanGesture手势控制的完整学习路径。项目知识图谱如图8-4所示。

图8-4

项目知识图谱4技术准备8.4.1MediaKit简介MediaKit是HarmonyOS提供的多媒体开发框架，为应用开发者提供了一套完整且高效的多媒体处理工具。它通过简洁易用的API，帮助开发者轻松实现音/视频播放和录制、媒体资源管理等功能的开发，以充分利用系统的媒体资源。MediaKit主要包含以下核心功能模块。媒体播放（AVPlayer）：提供音/视频播放功能，支持对本地媒体资源的播放控制（如播放、暂停、跳转、音量调节等）。媒体录制（AVRecorder）：提供音/视频录制功能。媒体元数据提取（AVMetadataExtractor）：用于从媒体文件中提取元数据信息，如歌曲名称、作者、专辑封面等。媒体缩略图生成（AVImageGenerator）：用于从视频文件中生成指定帧的缩略图。MediaKit的设计目标是让开发者能够专注于业务逻辑设计，无须深入底层复杂的多媒体处理细节，从而显著提升开发效率。在视频播放器应用项目中，主要利用MediaKit的AVPlayer组件来实现核心播放功能，具体如下。通过AVPlayer的fdSrc属性播放rawfile目录下的本地视频。利用AVPlayer提供的play、pause、seek、setVolume等方法实现播放控制。通过监听AVPlayer的stateChange事件来管理播放器的状态（如准备完成、播放中、暂停、播放完成等）。简而言之，MediaKit的AVPlayer组件是本项目视频播放功能的核心引擎，负责视频的解码、状态管理以及播放控制。请注意，MediaKit在鸿蒙系统中不支持在预览器中使用，所以本项目的视频播放功能无法在预览器中查看效果，需在模拟器或者真机进行运行调试。4技术准备8.4.2获取本地视频资源本地视频资源获取通过鸿蒙系统的资源管理框架实现。应用内置视频文件放置在entry/src/main/resources/rawfile目录下，运行时通过resourceManager.getRawFd方法获取文件的原始描述符。这个描述符包含系统级的文件访问权限和路径信息，可以直接传递给AVPlayer进行解码。该方法封装了底层的文件系统操作，为应用提供了统一的资源访问接口。获取的RawFileDescriptor包含文件描述符fd、偏移量offset和文件长度length等信息，AVPlayer通过这些信息能够直接访问和读取视频文件内容。//GetRawFdExample.etsimport{BusinessError}from'@ohos.base';@Entry@ComponentstructGetRawFdExample{@StatefdInfo:string='';asyncgetVideoDescriptor(){try{constcontext=getContext(this);//假设rawfile目录下有一个名为demo.mp4的文件constrawFd=awaitcontext.resourceManager.getRawFd('demo.mp4');this.fdInfo=`获取成功！\n文件描述符:${rawFd.fd}\n偏移量:${rawFd.offset}\n长度:${rawFd.length}`;}catch(error){leterr=errorasBusinessError;this.fdInfo=`获取失败:${err.message}`;}}build(){Column({space:20}){Text('获取rawfile视频描述符').fontSize(20).fontWeight(FontWeight.Bold)Button('获取并显示描述符').onClick(()=>this.getVideoDescriptor())Text(this.fdInfo).fontSize(14).padding(10).backgroundColor('#f0f0f0').width('90%')}.width('100%').height('100%').justifyContent(FlexAlign.Center)}}4技术准备8.4.3AVPlayer状态机管理AVPlayer状态机管理是视频播放器的核心机制，它定义了播放器从初始化到销毁的完整生命周期。状态机包含idle、initialized、prepared、playing、paused、completed、stopped、released和error等关键状态，每个状态都有明确的进入条件和可执行操作，如表8-1所示。表8-1AVPlayer状态机的关键状态状态说明idle闲置状态，未初始化资源时的默认状态initialized调用createAVPlayer成功后的状态，此时资源已初始化但未准备播放prepared调用prepare成功后的状态，播放引擎已就绪playing在prepared/paused/completed状态下调用play后的状态，表示正在播放paused在playing状态下调用pause后的状态，播放暂停但保留资源completed播放至结尾且未开启循环播放（loop=false）时自动进入该状态，此时调用play可重播stopped在prepared/playing/paused/completed状态下调用stop后的状态，释放内存但保留属性released调用release后的状态，彻底销毁播放器并释放所有资源error发生不可逆错误（如媒体格式错误）时的状态，需调用reset或release恢复4技术准备状态转换遵循严格的顺序：初始化资源后进入initialized状态；调用prepare后进入prepared状态，此时可以获取视频元信息；调用play进入playing状态；调用pause进入paused状态；播放完成后进入completed状态，需要调用reset返回idle状态才能重新配置资源。AVPlayerStateExample.ets代码实现参见教材。4技术准备8.4.4XComponent视频渲染XComponent提供了原生视频渲染表面（Surface），作为连接ArkUI框架和底层多媒体引擎的桥梁。Surface负责接收解码后的视频帧并进行渲染显示，需要正确处理其生命周期，包括创建、尺寸配置和销毁。关键技术点包括：在XComponent的onLoad回调中先配置Surface尺寸，然后获取SurfaceID并传递给AVPlayer进行关联，最后在组件销毁时正确释放资源。Surface尺寸应与视频分辨率匹配以获得最佳显示效果，同时需要考虑设备屏幕尺寸和比例。AutoPlayXComponentPlayer.ets代码实现参见教材。4技术准备8.4.5播放控制功能播放控制系统提供完整的媒体控制功能，包括播放/暂停、视频切换、倍速播放、进度控制、音量调节等功能。1．播放/暂停播放/暂停是视频播放器的基本功能，需要在prepared、playing和paused状态间正确切换。实现时需要检查当前状态，避免在不适用的状态下调用相关方法。2.视频切换视频切换需要先计算下一个视频索引，然后调用reset()方法重置播放器状态，再加载新视频资源。关键是在切换过程中保持用户体验流畅，避免界面卡顿或闪烁。3.倍速播放倍速播放通过setSpeed方法实现，支持0.5倍到2.0倍的播放速度调整。需要注意，不同设备支持的倍速范围可能有所不同。4技术准备4.进度控制进度条拖动涉及两种交互：拖动中的实时预览和拖动结束后的实际跳转。拖动中更新预览时间但不实际跳转，拖动结束后才执行实际跳转操作。5.音量调节音量调节通过setVolume方法实现，通常结合UI控件如滑块或手势操作提供直观的音量控制体验。PlaybackController.ets代码实现参见教材。8.4.6PanGesture手势控制PanGesture是ArkUI中用于响应滑动操作的核心手势对象。它支持多种输入源（手指、鼠标、触控板、手写笔等），常用于实现拖动、滑动调节（如调节音量、亮度）、平移视图等交互。1.创建PanGesture对象PanGesture提供两种构造函数以适应不同场景。4技术准备//方式1：基础参数（API7及以上版本）PanGesture(value?:{fingers?:number;//触发手指数量，默认为1（范围为[1,10]）direction?:PanDirection;//识别的滑动方向，默认为PanDirection.Alldistance?:number;//最小触发距离（单位为vp），默认值：手写笔为8vp，其他输入源为5vp})//方式2：扩展参数（API15及以上版本）PanGesture(options?:PanGestureHandlerOptions)//新增isFingerCountLimited（手指数量检查）和distanceMap（按输入源定制距离）方向（PanDirection）枚举值如下。PanDirection.Up：仅向上滑动。PanDirection.Down：仅向下滑动。PanDirection.Left：仅向左滑动。PanDirection.Right：仅向右滑动。PanDirection.Horizontal：水平方向（Left|Right）。PanDirection.Vertical：垂直方向（Up|Down）。PanDirection.All：所有方向（默认）。4技术准备2.绑定手势到组件通过组件的.gesture方法进行绑定。4技术准备//GestureExample.ets@Entry@ComponentstructGestureExample{@StateoffsetX:number=0;@StateoffsetY:number=0;build(){Column(){Text("滑动区域").translate({x:this.offsetX,y:this.offsetY})}.gesture(PanGesture({direction:PanDirection.All,distance:5}).onActionUpdate((event:GestureEvent)=>{//实时更新位置this.offsetX=event.offsetX;this.offsetY=event.offsetY;}).onActionEnd((event:GestureEvent)=>{//处理滑动结束逻辑（如惯性滚动）console.log(`滑动速度：X=${event.velocityX},Y=${event.velocityY}`);}))}}3．核心回调函数PanGesture通过事件回调提供动态交互数据，3个核心回调函数分别响应手势的不同阶段，如表8-2所示。4技术准备表8-2核心回调函数回调函数触发时机关键参数onActionStart滑动开始event.offsetX/Y（初始偏移）onActionUpdate滑动过程中位置更新event.offsetX/Y（实时偏移）onActionEnd滑动结束（手指抬起/鼠标松开）event.velocityX/Y（滑动速度）5项目实施8.5.1项目目录结构项目目录结构如图8-5所示。图8-5项目目录结构图5项目实施本项目采用了典型的MVVM架构模式，将UI、业务逻辑和数据管理清晰分离，形成了一个结构严谨、易于维护的应用程序。1．Model层——管理数据状态Model层设计了两个核心数据模型：PlayerModel负责管理播放器的所有状态属性，包括视频尺寸、播放进度、音量等参数；VideoListState则专注于视频列表的状态管理。这两个模型都使用@Observed装饰器进行标记，使得数据变化能够自动通知到UI层，实现了响应式数据流。2．View层——界面渲染和用户交互View层包含丰富的UI组件，从主界面的HomeContent、HomeVideoList到视频播放界面的PlayPlayer、PlayControl等，每个组件都专注于界面渲染和用户交互。这些组件通过声明式的方式构建UI，完全剥离了业务逻辑，保持了UI层的纯净性。例如，HomeVideoListItem只关心如何展示单个视频项，而不关心数据从何而来；PlayControl只处理用户的点击操作，而不关心具体的播放逻辑实现。3．ViewModel层——处理业务逻辑ViewModel层作为连接View和Model的桥梁，承担了核心的业务逻辑处理工作。HomeVideoListModel负责扫描本地视频文件并提取元数据，将原始文件信息转换为UI可用的标准化数据。这一层通过封装复杂的多媒体操作，为View层提供简洁易用的接口。5项目实施8.5.2获取视频视频来源于本地，获取视频前、后的效果如图8-6和图8-7所示。图8-6获取视频前的效果图8-7获取视频后的效果5项目实施HomeVideoListModel是视频播放器应用的数据管理核心类，负责扫描和处理本地视频文件。它通过鸿蒙系统的多媒体API，自动发现rawfile目录下的MP4文件，并提取每个视频的关键信息和缩略图。HomeVideoListModel类采用单例模式设计，确保整个应用使用统一的数据管理器。其主要功能包括获取资源目录下的MP4文件列表，使用AVMetadataExtractor提取视频时长等元数据，通过AVImageGenerator获取视频第一帧作为缩略图，最后将所有信息封装成VideoItem对象并存储到全局上下文中。getLocalVideo方法是主要的对外接口，它会清空现有列表并重新组装视频数据。在assemblingVideoItem方法中，通过遍历MP4文件列表，为每个视频创建对应的多媒体处理对象，提取时长信息和缩略图数据，最终构建完整的视频项目列表。这种设计将复杂的数据处理逻辑封装在ViewModel层，为UI组件提供了简洁的数据接口，同时通过全局上下文实现了跨组件的数据共享。VideoPlayer\entry\src\main\ets\viewmodel目录中HomeVideoListModel.ets文件代码参见教材，所依赖的外部文件见教材配套数字资源中的素材。注意resourceManager.getRawFd方法专门用于获取rawfile目录下MP4文件资源的原始文件描述符，是鸿蒙资源管理系统的核心API之一。在数据处理过程中，可以通过该方法获取MP4文件的原始文件描述符，并将返回的结果直接赋值给多媒体组件的fdSrc属性。这种设计使得底层多媒体组件能够高效地访问rawfile资源，避免了文件复制或路径解析的开销。5项目实施8.5.3视频播放视频播放主要包括视频的暂停、播放、切换、倍速播放、当前进度设置、当前播放时间显示、音量调节等功能，本小节主要介绍播放管理组件（下面简称为AVPlayer），效果如图8-8所示。播放的全流程包含：创建AVPlayer、设置播放资源、设置播放参数（音量/倍速）、播放控制（播放/暂停/上一个视频/下一个视频）、播放重置、销毁资源。AVPlayer状态机生命周期如图8-9所示。图8-8视频播放页图8-9AVPlayer状态机生命周期注：eos（endofstream）是“流结束”事件，表示视频流播放到末尾。它不是一个持续的状态，而是触发状态从playing转换到completed的关键事件。如果开启了循环播放（loop），此事件会触发播放重新开始，状态会再次回到playing。5项目实施1．PlayPlayer.ets——视频播放子组件PlayPlayer组件是视频播放器的核心渲染组件，通过Stack分层布局实现视频播放画面与状态指示的叠加显示。该组件通过XComponent创建Surface，并在上层叠加音量指示器，提供完整的视频播放视觉体验。组件通过@Consume装饰器获取来自父组件的共享状态，包括视频尺寸参数、播放器数据模型、视频源文件和控制栏显示状态。在XComponent组件加载时，通过onLoad回调获取Surface渲染表面id，并调用firstPlay方法启动视频播放，将视频画面渲染到指定的Surface上。视频渲染层基于XComponent的SURFACE类型，配合原生播放库实现硬件加速的视频解码和渲染。组件尺寸通过响应式的xComponentWidth和xComponentHeight动态调整，支持横/竖屏切换时的自适应布局。在视频画面上方，设计了一个环形进度条指示器用于显示系统音量百分比。该组件采用Stack布局，将环形Progress组件与图标叠加显示。通过playerModel中的volumeShow状态控制指示器的显示时机，确保仅在用户调节音量时出现，避免遮挡视频内容，保持界面简洁。VideoPlayer\entry\src\main\ets\view目录中PlayPlayer.ets文件代码参见教材，所依赖的外部文件见教材配套数字资源中的素材。注意视频播放之前需要初始化XComponent组件用于展示视频画面。XComponent组件初始化成功之后，在onLoad中获取surfaceId用于与AVPlayer实例关联。5项目实施2．PlayerController.ets——视频控制类PlayerController.ets是鸿蒙视频播放器项目的核心控制器，负责管理视频播放的所有功能。它封装了鸿蒙AVPlayer的底层API，提供了播放控制、进度管理、手势操作、音量调节等高级功能，与播放器UI组件紧密配合，实现了视频播放的完整业务流程，是项目中最核心的业务逻辑处理模块。VideoPlayer\entry\src\main\ets\controller目录中PlayerController.ets文件代码参见教材，所依赖的外部文件见教材配套数字资源中的素材。5项目实施8.5.4手势控制1．PlayPage.ets——视频播放界面PlayPage.ets是视频播放器项目的播放界面组件，是视频播放功能的核心界面。它集成了视频播放器、控制栏、进度条等组件，并提供了手势控制功能。比如音量环形进度条的效果如图8-10所示。VideoPlayer\entry\src\main\ets\pages目录中PlayPage.ets文件代码参见教材，所依赖的外部文件见教材配套数字资源中的素材。图8-10音量环形进度条的效果5项目实施2．PlayerController.ets——视频控制类本小节以音量调节为例介绍手势控制，当手指触摸音量调节区域时获取当前屏幕坐标，手指在音量调节区域水平滑动时实时获取屏幕坐标并计算音量。手势控制功能的相关代码如右，完整代码参见8.5.3节中的PlayerController.ets。//手指触摸到音量调节区域onVolumeActionStart(event?:GestureEvent){...this.positionX=event.offsetX;}//手指在音量调节区域水平滑动onVolumeActionUpdate(event?:GestureEvent){...this.playerModel.volumeShow=true;letscreenWidth=GlobalContext.getContext().getObject('screenWidth')asnumber;letchangeVolume=(event.offsetX-this.positionX)/screenWidth;letvolume:number=this.playerModel.volume;letcurrentVolume=volume+changeVolume;letvolumeMinFlag=currentVolume<=PlayConstants.MIN_VALUE;letvolumeMaxFlag=currentVolume>PlayConstants.MAX_VALUE;this.playerModel.volume=volumeMinFlag?PlayConstants.MIN_VALUE:(volumeMaxFlag?PlayConstants.MAX_VALUE:currentVolume);

this.avPlayer.setVolume(this.playerModel.volume);this.positionX=event.offsetX;}5项目实施8.5.5全屏播放全屏播放功能通过屏幕方向切换为用户提供沉浸式视频播放体验，其设计核心包括横/竖屏切换、界面元素动态调整和视频尺寸自适应调整，效果如图8-11和图8-12所示。1．横/竖屏切换全屏功能的核心控制位于PlayTitle组件的顶部控制栏中。当用户点击全屏按钮时，系统通过鸿蒙的窗口管理API将屏幕方向设置为横屏，同时隐藏系统状态栏以实现真正的全屏播放。具体实现中，通过获取当前窗口实例并调用setPreferredOrientation方法切换到横屏方向，同时使用setWindowSystemBarEnable方法隐藏所有系统状态栏。还包括返回按钮的逻辑设计：当用户在横屏（全屏）模式下点击返回按钮时，系统会恢复竖屏方向并重新显示状态栏；而在竖屏模式下点击返回按钮，系统会执行正常的界面返回操作。VideoPlayer\entry\src\main\ets\view目录中PlayTitle.ets文件代码参见教材，所依赖的外部文件见教材配套数字资源中的素材。图8-11视频播放页效果图

图8-12全屏播放效果图5项目实施2．界面元素动态调整全屏功能的另一个关键环节是界面元素的动态显示控制。通过响应式状态管理，系统在全屏切换时智能调整各个UI组件的显示状态。在PlayPage组件中使用@ProvideiconVisibility定义控制栏的显示状态，这一状态通过ArkUI的@Provide/@Consume机制共享给所有子组件。当进入全屏模式时，iconVisibility状态被设置为Visibility.Hidden，PlayProgress、PlayControl等子组件自动隐藏；退出全屏模式时，iconVisibility状态恢复为Visibility.Visible，各子组件重新显示。这种设计确保了全屏模式下用户能够获得无干扰的播放体验，同时在需要操作时又能快速唤出控制界面。//PlayPage.ets@ProvideiconVisibility:Visibility=Visibility.Visible;//PlayProgress.ets@ConsumeiconVisibility:Visibility;//PlayControl.ets@ConsumeiconVisibility:Visibility;5项目实施3．视频尺寸自适应调整视频尺寸的自适应调整是全屏功能的重要组成部