---
title: "RealityKit-SwiftUI Integration"
type: concept
tags: []
sources: [visionos-spatial-engineer]
last_updated: 2026-04-25
---

## Definition
Apple 提供的 RealityKit 3D 渲染引擎与 SwiftUI 声明式 UI 框架之间的深度集成模式，允许开发者用 SwiftUI 语法声明式地构建 3D 空间界面。

## Core Integration Patterns
- **@Observable Entities**：RealityKit 实体实现 @Observable 协议，与 SwiftUI 视图自动双向绑定
- **Direct Gesture Handling**：SwiftUI 手势（Gesture）直接作用于 RealityKit 实体，无需中间层
- **ViewAttachmentComponent**：将 SwiftUI 视图作为 component 附加到 RealityKit 实体
- **EntityManager Integration**：通过 SwiftUI Environment 访问 EntityManager 实例

## Implementation Benefits
- **Declarative 3D（声明式 3D）**：用 SwiftUI 视图语法替代传统 Entity-Component 模式
- **State Synchronization（状态同步）**：SwiftUI @State/@Binding 与 RealityKit 实体属性自动同步
- **Reduced Boilerplate（减少样板代码）**：相比纯 RealityKit 开发，集成模式显著减少代码量

## Related Concepts
- [[SwiftUI Volumetric APIs]]：基于 RealityKit-SwiftUI 集成的上层 API 集
- [[Spatial Layouts]]：集成后的 3D 内容在空间中的布局管理
- [[Multi-Window Architecture]]：集成模式在多窗口场景下的应用

## Sources
- [[visionos-spatial-engineer]] — visionOS Spatial Engineer Agent 角色定义