资产 / 图像 / SpriteAtlas节点

学习目标

读取和验证 Cocos 资产对象，把图片、音频、材质、Prefab 等资源接入工作流逻辑。

覆盖范围

• 节点数量：10
• 分类路径：资产 / 图像 / SpriteAtlas

典型使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

通用注意事项

• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

节点索引

节点	节点 ID	输入/输出	执行方式
按名称获取帧	spriteAtlasGetSpriteFrame	2 / 1	立即继续
获取全部帧	spriteAtlasGetSpriteFrames	1 / 1	立即继续
获取全部帧名称	spriteAtlasGetFrameNames	1 / 1	立即继续
获取所有属性	spriteAtlasGetProperties	1 / 5	立即继续
获取图集纹理	spriteAtlasGetTexture	1 / 1	立即继续
获取帧数量	spriteAtlasGetFrameCount	1 / 1	立即继续
获取帧映射	spriteAtlasGetSpriteFramesMap	1 / 1	立即继续
设置所有属性	spriteAtlasSetProperties	3 / 2	立即继续
是否包含帧	spriteAtlasHasSpriteFrame	2 / 1	立即继续
新建精灵图集	spriteAtlasCreate	1 / 2	立即继续

按名称获取帧

按名称（key）从图集中取出单个 SpriteFrame。该名称通常等于精灵帧资产名，区分大小写。 若 key 不存在或图集为空，将输出 null；请先用 是否包含帧 做存在性判断，或用 获取全部帧名称 查看图集内全部 key。

节点信息

字段	值
节点 ID	spriteAtlasGetSpriteFrame
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填
key	名称	数据	string	名称（Key） 图集中 SpriteFrame 的名称，区分大小写，与资产名保持一致。例如 “icon_coin”。	输入框 默认值：""	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
frame	精灵帧	数据	cc.Asset / SpriteFrame	精灵帧 匹配 key 的精灵帧；未命中时为 null。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取全部帧

一次性读出图集内全部 SpriteFrame，以数组形式输出，顺序按 spriteFrames 映射的枚举顺序。 适合”遍历所有帧”的场景，例如批量切换动画序列、预览图集内容。

节点信息

字段	值
节点 ID	spriteAtlasGetSpriteFrames
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
frames	精灵帧数组	数据	cc.Asset / array / SpriteFrame	精灵帧数组 图集内全部精灵帧组成的数组。图集为空时输出空数组。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取全部帧名称

列出图集内全部精灵帧的名称，以字符串数组形式输出。 等同于对 spriteFrames 做 Object.keys(…)，但节点形式更直观，方便用来遍历、搜索、调试或展示图集内容。

节点信息

字段	值
节点 ID	spriteAtlasGetFrameNames
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
frameNames	帧名称列表	数据	string / array	帧名称列表 图集内全部精灵帧的名称数组。图集为空时输出空数组。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取所有属性

一次性读出图集的全部常用信息：底层纹理、原始 spriteFrames 映射、全部 SpriteFrame 数组、全部帧名称、帧数量。等同于连接多个 获取类节点，但只用一个节点即可。 适合序列化、调试、批量比较、预览图集内容等场景。

节点信息

字段	值
节点 ID	spriteAtlasGetProperties
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
texture	纹理	数据	cc.Asset / Texture2D	纹理 图集绑定的底层纹理。	-	可选
spriteFrames	帧映射	数据	object	帧映射 原始 spriteFrames 对象。	-	可选
frames	精灵帧数组	数据	cc.Asset / array / SpriteFrame	精灵帧数组 图集内全部精灵帧组成的数组。	-	可选
frameNames	帧名称列表	数据	string / array	帧名称列表 图集内全部精灵帧的名称数组。	-	可选
frameCount	帧数量	数据	number	帧数量 图集内精灵帧总数；空图集时为 0。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取图集纹理

读出图集绑定的底层纹理——即所有精灵帧共享的那张大图。 可将输出连接到 Texture2D 系列节点进一步读取纹理元信息。若图集未绑定纹理则输出 null。 说明：引擎签名返回 TextureBase，本节点按项目统一惯例按 Texture2D 建模。这意味着输出端口在类型系统中被视为 Texture2D，可直连 Texture2D 节点组，但如果图集实际绑定的不是 Texture2D（而是 TextureCube 等 TextureBase 子类），则连接到的节点可能获取不到预期数据。

节点信息

字段	值
节点 ID	spriteAtlasGetTexture
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
texture	纹理	数据	cc.Asset / Texture2D	纹理 图集绑定的底层纹理。可连接到 Texture2D 系列节点读取纹理信息。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取帧数量

输出图集内精灵帧的数量（整数）。等同于 Object.keys(atlas.spriteFrames).length 的便利节点。 常用于循环遍历、检测图集是否为空（输出 0 时），或在调试面板中展示统计信息。

节点信息

字段	值
节点 ID	spriteAtlasGetFrameCount
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
frameCount	帧数量	数据	number	帧数量 图集内精灵帧总数；图集为空时为 0。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

获取帧映射

读出图集内部的原始 spriteFrames 映射对象，形式为 Record<string, SpriteFrame | null>。key 是帧名称，value 是对应的精灵帧实例。 首版用 OBJECT 类型承载该原始映射，便于程序化读取；建议常规场景优先使用 Get Sprite Frame 或 Get Properties 这类更具语义的便利节点。

节点信息

字段	值
节点 ID	spriteAtlasGetSpriteFramesMap
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteFrames	帧映射	数据	object	帧映射 原始 spriteFrames 对象。图集为空时输出空对象。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

设置所有属性

整体替换图集的 spriteFrames 映射——首版 SpriteAtlas 公开可写字段只有它。 整体替换：输入是 Record<string, SpriteFrame | null> 形态的对象；执行后会把图集的 spriteFrames 替换为新值。若需逐项增删帧映射，请先用 获取帧映射 取出原对象，修改后再接回本节点。 注意：会影响所有使用该图集的 Sprite / RichText 等消费端；如需隔离修改，请先通过独立构造方式（如 新建精灵图集）创建新实例。

节点信息

字段	值
节点 ID	spriteAtlasSetProperties
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填
spriteFrames	帧映射	数据	object	帧映射 要整体替换的 spriteFrames 对象。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集（透传） 把当前操作的 SpriteAtlas 实例原样传出，便于将多个配置节点串联在一起。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

是否包含帧

判断图集中是否存在指定名称（key）的精灵帧，输出 true / false。 底层等同于 atlas.getSpriteFrame(key) != null，便利节点，避免重复连线。区分大小写。

节点信息

字段	值
节点 ID	spriteAtlasHasSpriteFrame
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 精灵图集 这里需要连接一个已经加载好的 SpriteAtlas 实例。 该端口没有”选择图集”按钮，请先使用以下方式获取图集实例： - 加载资产：把”类型”选为 SPRITE_ATLAS，从资产包按路径异步加载。 - 获取资产：取出资产包里已加载的 SpriteAtlas。 - 新建精灵图集：创建一个空图集实例，再通过 设置所有属性 整体写入 spriteFrames。	-	必填
key	名称	数据	string	名称（Key） 要检查的精灵帧名称，区分大小写。	输入框 默认值：""	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exists	存在	数据	boolean	是否存在 true：该 key 可在图集中找到对应精灵帧；false：key 不存在或图集为空。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。

---

新建精灵图集

在游戏运行时创建一个全新的空精灵图集实例，初始 spriteFrames 为空。 若要加载已有图集资产，请改用 加载资产（类型选 SPRITE_ATLAS）。程序化构造的图集可再通过 设置所有属性 整体写入帧映射。

节点信息

字段	值
节点 ID	spriteAtlasCreate
分类	资产
二级分类	图像
分组	SpriteAtlas
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
spriteAtlas	精灵图集	数据	cc.Asset / SpriteAtlas	SpriteAtlas 实例 新建的空图集实例。连接到 设置所有属性 等节点继续配置。	-	可选

使用场景

• 读取音频时长、图片尺寸、材质参数等资产信息
• 校验加载结果是否可用
• 创建或传递特定类型的资产实例

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 资产节点通常要求连接已加载的资产实例。
• 父类 Asset 生命周期能力应优先使用通用资产管理节点。