组合

相关参考：

• Scene API / 动态创建内容
• Scene API / 对象层级与生命周期

组合（Group）适合把多个对象当成一个整体来管理。

组合也是3D对象，因此3D对象支持的功能也都可以使用。

因为只是一种封装容器，因此组合不能被直接看见。

普通的3D对象，本质上也是一种组合。也可以使用addChild、removeChild和getChildren等功能。

只是在代码可读性上，更建议直接使用Group，而不是普通3D对象。

创建组合

const group = await api.createGroup();
await api.add(group);

将对象挂到组合下

const image = await api.getObject('image');
const model = await api.createGltfModel(glbBuffer);

await api.add(model);

await api.addChild(group, image);
await api.addChild(group, model);

之后你对 group 的位置、旋转、缩放修改，会整体影响其子对象。

组合可以继续挂到组合下，形成多层次的树状结构。

常见使用场景

把“标题 + 图标 + 按钮”打成一个整体

如果你在场景里动态加了多张图片或多个模型，希望它们一起移动，组合会非常实用。

暂时替代编辑器中的预设结构

有些业务不方便把所有层级都提前放进场景编辑器，也可以在运行时通过 createGroup() 组装一棵简单的层级树。

查询组合子节点

const children = await api.getChildren(group);

或按属性查找：

const child = await api.getChildByProperty(group, 'name', 'title-image');

解除挂接

await api.removeChild(group, image);

对象只是从组合中移除，和remove()类似，不会销毁资源，后续还可以继续add() 或 addChild()。

如果要彻底移除，则需要执行destroyObject()。

推荐习惯

1. 在把对象加入组合前，先为对象设定清晰名称。
2. 组合本身也建议命名，方便后续排查。
3. 需要整体开关显隐时，优先改组合对象，而不是逐个改子对象。