SoundEffect QML Type

SoundEffect 类型提供了一种在 QML 中播放音效的方法。更多

Import Statement:	`import QtMultimedia`
In C++:	QSoundEffect

所有成员（包括继承成员）的列表

属性

loops : int
loopsRemaining : int
muted : bool
playing : bool
source : url
status : enumeration
volume : real

信号

方法

bool isLoaded()
play()
stop()

详细说明

该类型允许以延迟较低的方式播放未压缩的音频文件（通常为 WAV 文件），适用于响应用户操作的 "反馈 "类声音（如虚拟键盘声音、弹出对话框的正反馈或游戏声音）。如果低延迟并不重要，可以考虑使用MediaPlayer 类型，因为它支持更多的媒体格式，而且占用资源较少。

音效通常应重复使用，这样可以提前完成所有解析和准备工作，只在必要时触发。这在 QML 中很容易实现，因为您可以声明 SoundEffect 实例并在其他地方引用它。

下面的例子在鼠标点击时播放 WAV 文件。

Text {
    text: "Click Me!";
    font.pointSize: 24;
    width: 150; height: 50;

    SoundEffect {
        id: playSound
        source: "soundeffect.wav"
    }
    MouseArea {
        id: playArea
        anchors.fill: parent
        onPressed: { playSound.play() }
    }
}

由于 SoundEffect 需要稍多的资源来实现低延迟播放，平台可能会限制同时播放音效的数量。

属性文档

loops : int

该属性表示声音的播放次数。值为 0 或 1 表示声音只播放一次；设置为SoundEffect.Infinite 可启用无限循环。

该值可在音效播放时更改，在这种情况下，它会将剩余的循环次数更新为新值。

loopsRemaining : int [read-only]

该属性包含音效自行停止前的剩余循环次数，如果SoundEffect.Infinite 是在loops.Infinite 中设置的，则为 .Infinite 。

muted : bool

该属性提供了一种控制静音的方法。true 的值将使音效静音。否则，将以当前指定的volume 进行播放。

playing : bool [read-only]

此属性表示音效是否正在播放。

source : url

该属性保存要播放的声音的网址。要让SoundEffect 试图加载音源，URL 必须存在，应用程序必须在指定目录下有读取权限。如果所需的音源是本地文件，则可使用绝对或相对（指向声明SoundEffect 的文件）路径指定 URL。

status : enumeration [read-only]

该属性表示SoundEffect 的当前状态，如SoundEffect 中所列举。可能的状态如下。

值	说明
SoundEffect空	未设置源或源为空。
SoundEffect正在加载	SoundEffect 正在尝试加载源。
SoundEffect.就绪	源已加载并可播放。
SoundEffect.Error （错误	操作过程中发生错误，如加载音源失败。

volume : real

该属性用于保存音效播放的音量。

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

默认音量为1.0 。

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

信号文档

loadedChanged()

loadedChanged 信号在加载状态发生变化时发出。

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

loopCountChanged()

loopCountChanged 信号在初始循环数发生变化时发出。

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

loopsRemainingChanged()

当剩余循环数发生变化时，将发出loopsRemainingChanged 信号。

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

mutedChanged()

静音状态发生变化时，将发出mutedChanged 信号。

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

playingChanged()

播放属性发生变化时，将发出playingChanged 信号。

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

sourceChanged()

源已更改时，将发出sourceChanged 信号。

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

statusChanged()

状态属性发生变化时，会发出statusChanged 信号。

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

volumeChanged()

音量发生变化时，会发出volumeChanged 信号。

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

方法文档

bool isLoaded()

返回音效是否已完成加载source 。

play()

开始播放声音效果，循环播放的次数在 loops 属性中指定。

这是SoundEffect 的默认方法。

SoundEffect {
    id: playSound
    source: "soundeffect.wav"
}
MouseArea {
    id: playArea
    anchors.fill: parent
    onPressed: { playSound.play() }
}

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.