3D内容放置屏幕

相关参考：

• Scene API / 相机与拍照
• Scene API / 对象层级与生命周期
• Scene API / 变换属性

把 3D 内容“放到屏幕上”是可以实现的，但更准确地说，这不是单独的一条专用 API，而是通过把对象挂到相机下面来实现。

核心思路如下：

const camera = await api.getDefaultCamera();
await api.addChild(camera, obj);

这样对象会跟随相机一起移动和旋转，视觉上就会更接近“固定在屏幕前方”。

更推荐的方案：宿主层叠加 UI

如果你的目标是典型 HUD 或固定 UI，仍然更推荐：

1. 宿主页面自己做一层 HTML/CSS UI
2. Kivicube iframe 只负责 3D/AR 内容

这种方式更适合：

• 标题
• 按钮
• 说明文字
• 引导箭头
• 响应式布局

原因也很直接：

• 更容易做多端适配
• 更容易和宿主页面样式统一
• 更容易点击、埋点、做动画
• 不需要反复调 3D 坐标

什么时候适合用 3D 对象贴屏

更适合下面这类内容：

• 希望它仍然是一个 3D 对象
• 需要参与场景内的材质、光照或透明效果
• 想做“漂浮在镜头前方”的 3D 装饰
• 想让它继续复用已有对象动画或模型资源

基本实现方式

1. 获取相机和目标对象

const camera = await api.getDefaultCamera();
const obj = await api.getObject('screen-object');

如果对象是你运行时创建的，也可以直接使用创建返回的句柄：

const obj = await api.createImage('/assets/tag.png');

2. 挂到相机下面

await api.addChild(camera, obj);

3. 调整对象在相机坐标系下的位置

await api.setPosition(obj, 0, 0, -2);
await api.setScale(obj, 0.5, 0.5, 0.5);

这里最关键的是 z：

• z 一般要放在负方向，表示放到镜头前方
• 数值越接近 0，看起来越贴近屏幕
• 数值越小，看起来越远

x、y 则决定它在屏幕中的左右和上下位置。

例如：

// 居中偏下
await api.setPosition(obj, 0, -0.6, -2);

// 左上角附近
await api.setPosition(obj, -1.2, 0.8, -2);

4. 修改渲染状态

// 使物体始终最上层显示，取消渲染时的深度测试，以及对深度缓冲区的影响
const recursive = true; // 是否同时设置所有子节点。默认为false
await api.setGLState(obj, "depthTest", false, recursive);
await api.setGLState(obj, "depthWrite", false, recursive);

一个完整示例

iframe.addEventListener('ready', async (event) => {
  const { api } = event.detail;

  const camera = await api.getDefaultCamera();
  const image = await api.createImage('/assets/floating-badge.png');

  await api.addChild(camera, image);

  await api.setPosition(image, 1.1, -0.8, -2);
  await api.setScale(image, 0.35, 0.35, 0.35);

  const recursive = true;
  await api.setGLState(obj, "depthTest", false, recursive);
  await api.setGLState(obj, "depthWrite", false, recursive);
});

取消贴屏

如果后面不想继续挂在相机下，可以移除父子关系，再重新挂回其他对象：

await api.removeChild(camera, obj);

如果只是想隐藏：

await api.setObjectVisible(obj, false);

适配建议

虽然这种方案可以实现“贴屏”，但它仍然是 3D 坐标，不是 CSS 像素坐标。因此：

• 不同屏幕比例下，位置可能需要微调
• 不同 FOV 下，视觉位置也会变化
• 过于靠近镜头时，容易显得过大或裁切异常

更稳妥的方式是：

• 固定一套基础坐标
• 在关键机型上做少量微调
• 把真正的交互按钮仍放在宿主层 HTML 中

什么时候不建议用这种方式

• 需要精确对齐宿主页面按钮
• 需要复杂响应式布局
• 需要大量文字内容
• 需要稳定的点击热区
• 需要和页面滚动、弹层、表单联动

这种情况下，HTML/CSS 会比 3D 方案更适合。