SoundEffect QML Type

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

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

属性

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

信号

• loadedChanged()
• loopCountChanged()
• loopsRemainingChanged()
• mutedChanged()
• playingChanged()
• sourceChanged()
• statusChanged()
• volumeChanged()

方法

• bool isLoaded()
• void play()
• void 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() }
    }
}

属性文档

loops : int

该属性用于指定声音播放的次数。值为 0 或 1 时，声音仅播放一次；设置为 `SoundEffect.Infinite` 可启用无限循环。

在音效播放过程中可以更改该值，此时系统会将剩余循环次数更新为新值。

loopsRemaining : int [read-only]

该属性包含音效自动停止前剩余的循环次数，即SoundEffect 。如果loops 中设置了“Infinite”，则该值为“Infinite”。

muted : bool

此属性提供了一种控制静音的方式。当值为true 时，将静音此效果。否则，播放将使用当前指定的volume 进行。

playing : bool [read-only]

该属性用于指示音效是否正在播放。

source : url

该属性存储要播放的音频的 URL。为了使SoundEffect 能够尝试加载该音频源，该 URL 必须真实存在，且应用程序必须对指定目录具有读取权限。如果目标音频源是本地文件，则可以使用绝对路径或相对路径（以声明SoundEffect 的文件为基准）来指定该 URL。

status : enumeration [read-only]

该属性表示SoundEffect 的当前状态，该状态是在SoundEffect 中枚举得到的。可能的状态如下所示。

volume : real

该属性控制音效播放的音量。

音量按线性比例从0.0 （静音）到1.0 （最大音量）进行调节。超出此范围的数值将被限制。

默认音量为1.0 。

UI音量控件通常应采用非线性刻度。例如，使用对数刻度会产生感知响度的线性变化，这正是用户通常对音量控件的预期。更多详情请参阅convertVolume()。

信号文档

loadedChanged()

当加载状态发生变化时，会发出loadedChanged 信号。

loopCountChanged()

当初始循环次数发生变化时，会触发loopCountChanged 信号。

loopsRemainingChanged()

当剩余循环次数发生变化时，会触发loopsRemainingChanged 信号。

mutedChanged()

当静音状态发生变化时，会触发mutedChanged 信号。

playingChanged()

当 playing 属性发生变化时，会触发playingChanged 信号。

sourceChanged()

当源发生更改时，会触发sourceChanged 信号。

statusChanged()

当 status 属性发生变化时，会触发statusChanged 信号。

volumeChanged()

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

方法文档

bool isLoaded()

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

void play()

开始播放音效，并根据 loops 属性中指定的次数循环播放该音效。

这是 `SoundEffect` 的默认实现方式。

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

void stop()

停止当前播放。