一、前言

在鸿蒙应用开发中，视频播放是非常常见的业务需求，课程播放、短视频、宣传视频等场景都会用到Video组件。ArkUI 提供了原生 Video 视频组件，搭配VideoController控制器，可以脱离系统自带播放控制栏，自定义播放、暂停按钮，灵活实现播放器样式。 本篇提供可直接运行的完整代码，逐行拆解参数、属性、控制器方法，讲解资源存放规范与开发注意事项，适合实训作业与新手学习。

二、完整可运行代码

arkts

@Entry
@Component
struct Index {
  // 创建视频控制器，用于控制播放、暂停等操作
  private controller: VideoController = new VideoController();
  // 网络视频地址（示例，本次案例未使用）
  private videpSrc: string = 'http://www.w3school.com.cn/example/html5/mov_bbb.mp4'

  build() {
    Column({ space: 20 }) {
      Text("本地视频播放器")
        .fontSize(24)
        .width('100%')
        .textAlign(TextAlign.Center)

      // 视频核心组件
      Video({
        // rawfile本地视频资源，存放于entry/src/main/resources/rawfile/下
        src: $rawfile('sd.mp4'),
        // 绑定控制器
        controller: this.controller,
        // 视频未播放时展示的封面图
        previewUri: $r("app.media.cover")
      })
        .width('100%')
        .height(200)
        .muted(false)        // 不静音，正常播放声音
        .controls(false)     // 关闭系统自带播放控制条
        .loop(true)          // 开启循环播放
        .autoPlay(false)     // 进入页面不自动播放
        .objectFit(ImageFit.Contain) // 视频等比例完整显示，不拉伸裁剪

      // 播放、暂停控制按钮组
      Row({ space: 30 }) {
        Button("播放")
          .width(140)
          .height(50)
          .backgroundColor(Color.Blue)
          .fontSize(20)
          .borderRadius(18)
          .onClick(() => {
            // 点击调用控制器播放方法
            this.controller.start()
          })

        Button("暂停")
          .width(140)
          .height(50)
          .backgroundColor(0xf53f3f)
          .fontSize(20)
          .borderRadius(18)
          .onClick(() => {
            // 点击调用控制器暂停方法
            this.controller.pause()
          })
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

三、前置资源配置（必看，否则视频无法加载）

3.1 本地视频文件存放

代码中使用$rawfile('sd.mp4')读取本地视频，存放路径： entry/src/main/resources/rawfile/

1. 没有 rawfile 文件夹则手动新建；
2. 将视频文件sd.mp4放入该目录；
3. 文件名全部小写，不包含中文、空格、特殊符号。

3.2 封面图片存放

previewUri: $r("app.media.cover")为视频封面图： 图片路径：entry/src/main/resources/base/media/ 把图片命名为 cover.png/jpg 放入 media 文件夹。

3.3 网络视频额外配置（代码中预留字段）

如果要使用网络 url 视频，需要申请网络权限： module.json5 -> module.requestPermissions 添加网络权限

json

{
  "name": "ohos.permission.INTERNET"
}

四、代码分层详细解析

4.1 控制器定义

arkts

private controller: VideoController = new VideoController();

VideoController是 Video 组件的操作控制器，是控制视频播放的核心对象，必须实例化并绑定给 Video 组件，提供播放、暂停、跳转、停止等方法。

4.2 Video 构造入参说明

Video 组件接收一个对象参数，包含三个核心参数：

1. src：视频资源地址
   • $rawfile("文件名")：读取 rawfile 下本地短视频；
   • 字符串 url：网络在线视频；
2. controller：绑定创建好的 VideoController 实例，实现外部按钮控制；
3. previewUri：视频加载完成前、未播放时展示的封面图片。

4.3 Video 组件常用属性详解

• width / height：设置播放器宽高，支持百分比与固定数值。
• muted：设置是否静音播放，false 为正常播放声音，true 为静音。
• controls：是否展示系统自带播放控制条，false 为隐藏，实现自定义按钮控制。
• loop：是否开启循环播放，true 视频播放完毕自动重播。
• autoPlay：是否页面加载自动播放，false 需要手动点击按钮触发播放。
• objectFit：视频画面适配方式，Contain 代表等比例完整展示视频，不会拉伸、裁剪画面。

4.4 自定义控制按钮逻辑

两个按钮通过onClick点击事件调用控制器内置方法：

1. this.controller.start()：开始 / 继续播放视频；
2. this.controller.pause()：暂停当前播放视频。

4.5 页面布局

外层 Column 占满全屏，使用justifyContent(FlexAlign.Center)垂直居中，alignItems(HorizontalAlign.Center)水平居中，整体页面内容居中展示。

五、VideoController 拓展常用方法

除了案例中的 start、pause，控制器还有更多实用方法，适配大部分视频开发场景：

1. controller.stop()：停止播放，回到视频开头；
2. controller.setCurrentTime(10)：跳转到指定播放秒数；
3. getCurrentTime()：实时获取当前播放时间；
4. getDuration()：获取视频总时长。

六、常见问题与报错解决

1. 黑屏不播放视频
   • 检查 rawfile 文件夹是否存在、视频文件名匹配；
   • 视频编码不兼容，更换 mp4 标准格式视频；
2. 封面图不显示 media 文件夹图片名称与 $r 内名称完全一致，区分大小写；
3. 网络视频加载失败 未添加 INTERNET 网络权限，或者模拟器无网络；
4. 点击按钮无反应 Video 组件未绑定 controller 字段，控制器实例丢失。

七、开发总结

1. 本地短视频优先使用$rawfile方式加载，无需网络权限，加载速度更快；
2. controls(false)是自定义播放器的核心，隐藏系统控件后可自由设计播放按钮、进度条；
3. 所有播放操作均通过VideoController控制器完成，组件与控制逻辑分离，代码解耦；
4. 开发前规范存放图片、视频资源，文件名避免中文和特殊字符，减少资源加载异常问题