Back to Qt.io
Contact Us Blog Download Qt

Video QML Type

用于显示指定视频的方便类型。更多

Import Statement: import QtMultimedia
Inherits:

Item

属性

信号

方法

详细说明

Video 是一种方便的类型，它将 和 的功能合二为一。它提供了简单的视频播放功能，而无需声明多个类型。MediaPlayer VideoOutput

以下是在场景中实现视频播放的示例代码。

Video {
    id: video
    width : 800
    height : 600
    source: "video.avi"

    MouseArea {
        anchors.fill: parent
        onClicked: {
            video.play()
        }
    }

    focus: true
    Keys.onSpacePressed: video.playbackState == MediaPlayer.PlayingState ? video.pause() : video.play()
    Keys.onLeftPressed: video.position = video.position - 5000
    Keys.onRightPressed: video.position = video.position + 5000
}

当您点击MouseArea 的父文件时，源文件video.avi 将播放。视频播放的区域为 800 x 600 像素，其id 属性的值为video。

请注意，由于Keys 的信号已经定义，因此按下 ：

  • Spacebar 可切换暂停按钮。
  • Left Arrow 将视频中的当前位置移动到 5 秒之前。
  • Right Arrow 将视频中的当前位置提前 5 秒。

视频支持未转换、拉伸和均匀缩放的视频呈现方式。有关拉伸均匀缩放演示的说明，请参阅fillMode 属性说明。

另请参阅 MediaPlayer 和VideoOutput 。

属性文档

autoPlay : bool [since 6.7]

该属性控制媒体加载后是否开始自动播放。默认值为false 。

该属性在 Qt 6.7 中引入。


bufferProgress : real

该属性表示数据缓冲区当前被填满的程度，从 0.0（空）到 1.0（满）。


duration : int

该属性表示媒体的持续时间，单位为毫秒。

如果媒体没有固定的持续时间（例如直播流），则该值为 0。


endOfStreamPolicy : enumeration [since 6.9]

该属性指定视频流结束时应用的策略。

endOfStreamPolicy 可以是

常数说明
ClearOutput视频输出被清除。
KeepLastFrame视频输出继续显示最后一帧。使用clearOutput() 方法手动清除输出。

默认值为VideoOutput.ClearOutput 。

此属性在 Qt 6.9 中引入。


error : enumeration

该属性保存视频的错误状态。它可以是

  • MediaPlayerNoError.- 当前没有错误。
  • MediaPlayer.ResourceError - 由于资源分配问题，视频无法播放。
  • MediaPlayer.FormatError - 不支持视频格式。
  • MediaPlayer.NetworkError - 由于网络问题无法播放视频。
  • MediaPlayer.AccessDenied - 由于权限不足，视频无法播放。
  • MediaPlayer.ServiceMissing - 由于无法实例化媒体服务，因此无法播放视频。

errorString : string

该属性包含一个字符串，详细描述了当前的错误状况。


fillMode : enumeration

设置此属性可定义如何缩放视频以适应目标区域。

  • VideoOutput.Stretch - 缩放视频以适应目标区域
  • VideoOutput.PreserveAspectFit - 统一缩放视频以适应目标区域，不进行裁剪
  • VideoOutput.PreserveAspectCrop - 统一缩放视频以填充，必要时进行裁剪

由于该类型在 QML 中使用方便，不支持直接枚举，因此使用VideoOutput 中的枚举来访问可用的填充模式。

默认填充模式是 preserveAspectFit。


hasAudio : bool

该属性显示当前媒体是否有音频内容。


hasVideo : bool

确定当前媒体是否有视频内容。


loops : int

确定媒体在停止前的播放频率。设置为MediaPlayer.Infinite 可永远循环播放当前媒体文件。

默认值为1 。将此属性设置为0 没有任何作用。


metaData : mediaMetaData

此属性保存当前媒体的元数据。

有关各元数据键的详细信息，请参阅MediaPlayer.metaData 。

另请参阅 mediaMetaData 。


mirrored : int

确定显示的视频是否绕其垂直轴镜像。镜像应用于orientation 之后。默认值为false 。


muted : bool

该属性决定音频输出是否静音。


orientation : int [since 6.9]

该属性决定显示的视频在视频坐标中顺时针旋转的角度（度数），其中 Y 轴指向显示屏下方。方向变换在mirrored 之前应用。

只支持90 度的倍数，即 0、90、-90、180、270 等，否则指定值将被忽略。

默认值为0 。

此属性在 Qt 6.9 中引入。


playbackRate : real

该属性用于保存视频播放速率（正常速率的倍数）。


playbackState : enumeration

此只读属性表示媒体的播放状态。

默认状态为MediaPlayer.StoppedState。


position : int

该属性以毫秒为单位保存当前播放位置。


seekable : bool

该属性表示是否可以更改视频的播放位置。

如果为 true，调用seek() 方法或更改position 属性将导致播放到新位置。


source : url

该属性用于保存媒体的源 URL。


volume : real

该属性用于保存音频音量。

音量从0.0 （静音）到1.0 （全音量）线性缩放。超出此范围的值将被箝位。

默认音量为1.0 。

用户界面音量控制通常应以非线性方式缩放。例如，使用对数刻度会使感知响度产生线性变化，而这正是用户通常期望从音量控制中获得的效果。更多详情，请参阅QtAudio::convertVolume() 。


信号文档

errorOccurred(error, errorString)

当发生error 时，将发出该信号。errorString 参数可能包含更详细的错误信息。

注： 相应的处理程序是onErrorOccurred 。


paused()

暂停播放时发出该信号。

注： 相应的处理程序是onPaused 。


playing()

开始或继续播放时发出该信号。

注： 相应的处理程序是onPlaying 。


stopped()

播放停止时发出该信号。

注： 相应的处理程序是onStopped 。


方法文档

[since 6.9] clearOutput()

通过删除当前视频帧来清除视频输出。如果您需要在视频流结束后删除最后一帧视频，且endOfStreamPolicy Video 属性设置为KeepLastFrame ，则推荐使用此方法。

此方法在 Qt 6.9 中引入。


pause()

暂停媒体播放。


play()

开始播放媒体。


seek(offset)

如果seekable 属性为 true，则会将当前播放位置设为offset 。

另请参阅 seekable 和position 。


stop()

停止媒体播放。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.