VisionOS中如何用类Znear效果防止实体遮挡RealityView内SwiftUI按钮

问题背景 #

我开发了一款带沉浸式空间视图的VisionOS应用，需要在用户头部前方固定位置设置一个类似游戏仪表盘的底部按钮。但用户靠近视图中的3D物体时，按钮会被遮挡无法交互，这可能导致应用无法通过App Store审核。之前用SceneKit时，可以通过相机视图的Znear和Zfar参数控制3D模型的显示范围（过近或过远时隐藏），想知道RealityView/RealityKit 4里有没有类似机制。

现有代码 #

import SwiftUI
import RealityKit

struct ContentView: View {
    @State var myHead: Entity = {
        let headAnchor = AnchorEntity(.head)
        headAnchor.position = [-0.02, -0.023, -0.24]
        return headAnchor
    }()

    @State var clicked = false

    var body: some View {
        RealityView { content, attachments in
            // 创建3D立方体
            let mainBox = ModelEntity(mesh: .generateBox(size: [0.1, 0.1, 0.1]))
            mainBox.position = [0, 1.6, -0.3]
            
            content.add(mainBox)
            
            content.add(myHead)
            guard let attachmentEntity = attachments.entity(for: "Dashboard") else { return }
            
            myHead.addChild(attachmentEntity)
        }
        attachments: {
            // 沉浸式视图中的SwiftUI内容
            Attachment(id: "Dashboard") {
                VStack {
                    Spacer()
                        .frame(height: 300)
                    Button(action: {
                        goClicked()
                    }) {
                        Text(clicked ? "⏸️" : "▶️")
                            .frame(maxWidth: 48, maxHeight: 48, alignment: .center)
                            .font(.extraLargeTitle)
                    }
                    .buttonStyle(.plain)
                }
            }
        }
    }

    func goClicked() {
        clicked.toggle()
    }
}

问题截图 #

• 正常状态下的按钮显示：
• 被3D物体遮挡的按钮：

解决方案 #

在RealityKit 4中，你可以通过以下几种方式实现类似SceneKit的裁剪效果，解决按钮遮挡问题：

1. 使用CameraComponent的裁剪平面参数 #

RealityKit的CameraComponent提供了near和far属性，对应SceneKit的Znear和Zfar。你可以给场景中的相机设置这两个参数，控制3D内容的显示范围：

// 获取或创建场景中的相机实体
if let cameraEntity = content.entities.first(where: { $0.components.has(CameraComponent.self) }) {
    var cameraComponent = cameraEntity.components[CameraComponent.self]!
    cameraComponent.near = 0.1  // 设置近裁剪面，小于这个距离的物体将被隐藏
    cameraComponent.far = 100.0 // 设置远裁剪面，大于这个距离的物体将被隐藏
    cameraEntity.components[CameraComponent.self] = cameraComponent
}

2. 动态隐藏过近的3D物体 #

通过监听相机与3D物体的距离，实时控制物体的显示状态：

// 在RealityView中添加update闭包
RealityView { content, attachments in
    // 原有代码...
    mainBox.name = "mainBox" // 给模型命名方便查找
} update: { content, attachments in
    guard let mainBox = content.entities.first(where: { $0.name == "mainBox" }) else { return }
    let cameraPosition = content.cameraTransform.translation
    let distance = simd_distance(cameraPosition, mainBox.position)
    
    // 当距离小于0.2时隐藏模型
    mainBox.isEnabled = distance >= 0.2
}

3. 提升仪表盘的渲染层级 #

确保SwiftUI附件始终在最上层显示，直接给attachmentEntity设置更高的渲染优先级：

guard let attachmentEntity = attachments.entity(for: "Dashboard") else { return }
attachmentEntity.renderOrder = 1000 // 数值越大，渲染层级越高
myHead.addChild(attachmentEntity)

这种方式不需要裁剪3D物体，直接让按钮始终显示在所有内容之上，更适合仪表盘这类需要随时可交互的核心元素。

推荐方案 #

对于仪表盘这类核心交互元素，优先使用提升渲染层级的方式，确保按钮始终可见可交互，这也更符合App Store审核对交互可达性的要求。如果需要同时优化3D内容的显示效果，再结合裁剪平面参数配合使用。

内容的提问来源于stack exchange，提问作者Ostoura