使用指南
资产 / 音频 / AudioClip节点
资产 / 音频 / AudioClip 节点手册，包含 5 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。
覆盖范围
- 节点数量：5
- 分类路径：资产 / 音频 / AudioClip
典型使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
通用注意事项
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取加载模式 | audioClipGetLoadMode | 1 / 1 | 立即继续 |
| 获取所有属性 | audioClipGetProperties | 1 / 3 | 立即继续 |
| 获取音频时长 | audioClipGetDuration | 1 / 1 | 立即继续 |
| 校验可用性 | audioClipValidate | 1 / 1 | 立即继续 |
| 新建音频剪辑 | audioClipCreate | 1 / 2 | 立即继续 |
获取加载模式
读出音频剪辑的加载模式（loadMode），输出一个 AudioType 数值枚举。 不同加载模式使用不同的底层播放实现，在不同平台上可能有差异：
- UNKNOWN_AUDIO（-1）：未知 / 尚未确定。
- WEB_AUDIO（0）：使用 Web Audio API，适合短音效，延迟低。
- DOM_AUDIO（1）：使用 HTML5
- MINIGAME_AUDIO（2）：使用小游戏平台原生音频接口。
- NATIVE_AUDIO（3）：使用原生平台音频接口。 可用 数值分支 节点按模式进行分支判断。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | audioClipGetLoadMode |
| 分类 | 资产 |
| 二级分类 | 音频 |
| 分组 | AudioClip |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
audioClip | 音频剪辑 | 数据 | cc.Asset / AudioClip | AudioClip 音频剪辑 这里需要连接一个已经加载好的 AudioClip 实例。 该端口没有”选择音频剪辑”按钮，请先使用以下方式获取音频剪辑实例： - 加载资产：把”类型”选为 AUDIO_CLIP，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 AudioClip。 - 新建音频剪辑：创建一个空音频剪辑实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
loadMode | 加载模式 | 数据 | number | 加载模式 AudioType 数值枚举： UNKNOWN_AUDIO = -1（未知） WEB_AUDIO = 0（Web Audio API） DOM_AUDIO = 1（HTML5 Audio） MINIGAME_AUDIO = 2（小游戏平台） NATIVE_AUDIO = 3（原生平台） | - | 可选 |
使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
注意事项
- 适合的工作流类型：component、library、method、function、class。
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。
获取所有属性
一次性读出音频剪辑的全部已节点化稳定信息：时长、加载模式、是否可用。等同于同时连接 获取音频时长、获取加载模式、校验可用性，但只用一个节点即可。 适合调试、预览、条件判断等场景，减少画布节点数量。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | audioClipGetProperties |
| 分类 | 资产 |
| 二级分类 | 音频 |
| 分组 | AudioClip |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
audioClip | 音频剪辑 | 数据 | cc.Asset / AudioClip | AudioClip 音频剪辑 这里需要连接一个已经加载好的 AudioClip 实例。 该端口没有”选择音频剪辑”按钮，请先使用以下方式获取音频剪辑实例： - 加载资产：把”类型”选为 AUDIO_CLIP，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 AudioClip。 - 新建音频剪辑：创建一个空音频剪辑实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
duration | 时长 | 数据 | number | 时长 音频总时长（秒）；数据未就绪时为 0。 | - | 可选 |
loadMode | 加载模式 | 数据 | number | 加载模式 AudioType 数值枚举：UNKNOWN_AUDIO = -1，WEB_AUDIO = 0，DOM_AUDIO = 1，MINIGAME_AUDIO = 2，NATIVE_AUDIO = 3。 | - | 可选 |
isValid | 可用 | 数据 | boolean | 是否可用 true：音频数据已就绪；false：数据不存在或尚未就绪。 | - | 可选 |
使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
注意事项
- 适合的工作流类型：component、library、method、function、class。
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。
获取音频时长
读出音频剪辑的总时长（duration），单位为秒。 可用于判断音频长短（如长音乐 vs. 短音效），或与 数值分支 节点配合实现分段逻辑。当底层音频数据尚未就绪时，返回值回退为 0。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | audioClipGetDuration |
| 分类 | 资产 |
| 二级分类 | 音频 |
| 分组 | AudioClip |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
audioClip | 音频剪辑 | 数据 | cc.Asset / AudioClip | AudioClip 音频剪辑 这里需要连接一个已经加载好的 AudioClip 实例。 该端口没有”选择音频剪辑”按钮，请先使用以下方式获取音频剪辑实例： - 加载资产：把”类型”选为 AUDIO_CLIP，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 AudioClip。 - 新建音频剪辑：创建一个空音频剪辑实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
duration | 时长 | 数据 | number | 时长 音频总时长（秒）；数据未就绪时为 0。 | - | 可选 |
使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
注意事项
- 适合的工作流类型：component、library、method、function、class。
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。
校验可用性
校验音频剪辑是否具备有效底层数据，输出 true 或 false。 返回 true 表示音频数据已就绪，但实际播放还受 AudioSource 组件状态、平台等因素影响。典型用法：在把 AudioClip 传给 AudioSource 播放之前，先确认音频剪辑是否有效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | audioClipValidate |
| 分类 | 资产 |
| 二级分类 | 音频 |
| 分组 | AudioClip |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
audioClip | 音频剪辑 | 数据 | cc.Asset / AudioClip | AudioClip 音频剪辑 这里需要连接一个已经加载好的 AudioClip 实例。 该端口没有”选择音频剪辑”按钮，请先使用以下方式获取音频剪辑实例： - 加载资产：把”类型”选为 AUDIO_CLIP，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 AudioClip。 - 新建音频剪辑：创建一个空音频剪辑实例。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
isValid | 可用 | 数据 | boolean | 是否可用 true：音频数据已就绪；false：数据不存在或尚未就绪。 | - | 可选 |
使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
注意事项
- 适合的工作流类型：component、library、method、function、class。
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。
新建音频剪辑
在游戏运行时创建一个全新的空音频剪辑实例。 空实例不可直接播放，适合作为占位引用或配合游戏运行时逻辑动态填充音频数据。若要加载已有的音频文件，请使用 加载资产 节点（类型选 AUDIO_CLIP）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | audioClipCreate |
| 分类 | 资产 |
| 二级分类 | 音频 |
| 分组 | AudioClip |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
audioClip | 音频剪辑 | 数据 | cc.Asset / AudioClip | AudioClip 实例 新建的空音频剪辑实例，不可直接播放。 | - | 可选 |
使用场景
- 读取音频时长用于进度条或倒计时
- 校验加载到的音频资产是否可播放
- 把音频资产传给 AudioSource 使用
注意事项
- 适合的工作流类型：component、library、method、function、class。
- AudioClip 只负责音频资产本身，播放、暂停、循环应使用 AudioSource。