跳到主要内容

<pc-sound>

<pc-sound> 添加声音组件，在实体处播放各 <pc-sound-slot>。音量、音高和空间距离衰减设置作用于全部槽位。

用法

属性​

属性类型默认值说明
distance-modelEnum（枚举）"linear"ref-distance 到 max-distance 间的衰减："exponential" | "inverse" | "linear"。线性在默认 roll-off-factor 下于最大距离变为静音；另两种在近处快、远处慢，详见下文
enabledBoolean（布尔）"true"组件启用状态
max-distanceNumber（数字）"10000"超过后不再变小的距离。线性模式下为静音距离，应按场景规模设置
pitchNumber（数字）"1"全局音高倍率，与各槽位 pitch 相乘
positionalBoolean（布尔）"true"是否按相对监听者的位置调整声像和音量。音乐及界面音效应设 false，使各处播放一致
ref-distanceNumber（数字）"1"此距离内按完整音量播放
roll-off-factorNumber（数字）"1"距离衰减速度，越大越快；线性模式限制为 0 到 1
volumeNumber（数字）"1"整体音量，与各槽位 volume 相乘
聆听距离

空间音频相对 <pc-audio-listener> 调整方向和距离，无监听器时以世界原点为准。默认线性在 10000 单位内衰减，因此相隔 10 单位几乎听不出变小。应像空间声音示例设 max-distance 为 12 等场景尺度，或使用 inverse，使超过参考距离后，距离每翻倍音量减半。

示例​

一个组件包含循环脚步声和单次音效。volume 和 pitch 影响全部槽位，可试着音量减半或设 pitch="1.5" 并重跑：

实时示例
<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/footsteps.mp3" id="footsteps"></pc-asset>
    <pc-asset src="https://developer.playcanvas.com/assets/drop.mp3" id="drop"></pc-asset>
    <pc-scene>
        <pc-entity name="camera">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
        </pc-entity>
        <pc-entity name="speaker">
            <pc-sound volume="1" pitch="1" positional="false">
                <pc-sound-slot name="footsteps" asset="footsteps" loop="true"></pc-sound-slot>
                <pc-sound-slot name="drop" asset="drop"></pc-sound-slot>
            </pc-sound>
        </pc-entity>
    </pc-scene>
</pc-app>
<div class="controls">
    <button id="toggle">Toggle footsteps</button>
    <button id="play-drop">Play drop</button>
</div>
<style>
    .controls {
        position: absolute;
        top: 12px;
        left: 12px;
        display: flex;
        gap: 8px;
    }
</style>
<script type="module">
    import { whenReady } from '@playcanvas/web-components';

    const sounds = await whenReady('pc-sound');
    const footsteps = sounds.component.slot('footsteps');
    document.getElementById('toggle').onclick = () => {
        footsteps.isPlaying ? footsteps.stop() : footsteps.play();
    };
    document.getElementById('play-drop').onclick = () => sounds.component.slot('drop').play();
</script>

JavaScript 接口​

可以通过 SoundComponentElement API创建和操作元素。

component 是底层 SoundComponent，就绪前为 null，其余功能可通过它访问。

另请参阅​

示例：基础声音、空间声音、下落方块和钟楼。