音频播放组件（SoundPlayer）

一、概述

SoundPlayer 是LayaAir引擎中用于播放背景音乐或音效的组件，继承自 Component。它是原有音频节点（SoundNode）的组件化版本，可以添加到任意节点上使用。

与直接通过 SoundManager 代码控制音频相比，SoundPlayer 组件可以在IDE中可视化配置音频属性，更加方便直观。

关于音频节点的使用，请参考《音频节点》。

关于代码控制音频的更多用法，请参考《代码控制音频》。

二、添加组件

选中一个节点后，在右侧属性面板中点击 增加组件，选择 SoundPlayer 即可添加音频播放组件。

（动图2-1）

三、组件属性

SoundPlayer 组件的属性面板如图3-1所示，与音频节点（SoundNode）的属性一致。

（图3-1）

四、代码控制

4.1 通过属性引用控制

在自定义脚本中通过 @property 装饰器引用 SoundPlayer 组件进行控制：

const { regClass, property } = Laya;

@regClass()
export class SoundScript extends Laya.Script {

    @property({ type: Laya.SoundPlayer })
    public soundPlayer: Laya.SoundPlayer;

    onAwake(): void {
        this.soundPlayer.source = "resources/sound.wav"; // 设置音频路径
        this.soundPlayer.loop = 0;          // 无限循环
        this.soundPlayer.isMusic = false;   // 作为音效播放
        this.soundPlayer.autoPlay = true;   // 自动播放
    }
}

4.2 通过代码添加组件

let sprite = new Laya.Sprite();
Laya.stage.addChild(sprite);

// 添加 SoundPlayer 组件
let soundPlayer = sprite.addComponent(Laya.SoundPlayer);
soundPlayer.source = "resources/sound.wav";
soundPlayer.loop = 0;
soundPlayer.autoPlay = true;
soundPlayer.isMusic = false;

4.3 播放与停止

// 播放音频（可指定循环次数、完成回调、起始时间）
soundPlayer.play();
soundPlayer.play(3); // 播放3次
soundPlayer.play(1, (success) => {
    console.log("播放完成", success);
});

// 停止播放
soundPlayer.stop();

注意：loop 属性需要在 autoPlay 设置之前赋值，否则自动播放时会使用默认的循环次数。

五、SoundPlayer 与 SoundNode 的区别

两者的属性和功能完全相同，SoundPlayer 是 SoundNode 的组件化封装。推荐使用 SoundPlayer 组件，更符合组件化的开发理念。