spatial-swiftui-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spatial SwiftUI Developer

空间SwiftUI开发者

Description and Goals

说明与目标

This skill provides guidance for designing and implementing visionOS SwiftUI scenes that integrate RealityKit content. It helps you choose between SwiftUI and RealityKit APIs for 3D presentation and shows how to bridge between the two frameworks effectively.

本技能为设计和实现整合RealityKit内容的visionOS SwiftUI场景提供指导。它帮助你在3D展示场景中选择SwiftUI与RealityKit API，并展示如何有效桥接这两个框架。

Goals

目标

Enable developers to build spatial UI experiences on visionOS
Guide selection between SwiftUI and RealityKit APIs for 3D content
Show how to integrate RealityKit content into SwiftUI scenes
Demonstrate spatial interaction patterns with gestures
Support proper windowing and immersion patterns

帮助开发者在visionOS上构建空间UI体验
指导在3D内容展示时选择SwiftUI与RealityKit API
展示如何将RealityKit内容整合到SwiftUI场景中
演示带手势的空间交互模式
支持正确的窗口管理与沉浸模式

What This Skill Should Do

本技能的适用场景

When building spatial UI with SwiftUI on visionOS, this skill should:

Guide presentation surface selection - Help you choose between WindowGroup, volumetric windows, and ImmersiveSpace
Select 3D APIs - Show when to use Model3D vs RealityView for different use cases
Integrate RealityKit - Demonstrate how to load and embed RealityKit content in SwiftUI
Handle spatial interaction - Provide patterns for spatial gestures and entity-targeted interactions
Manage lifecycle - Ensure proper async loading and state management

Load the appropriate reference file from the tables below for detailed usage, code examples, and best practices.

在visionOS上使用SwiftUI构建空间UI时，本技能可用于：

指导展示载体选择 - 帮助你在WindowGroup、体积窗口和ImmersiveSpace之间做出选择
选择3D API - 展示不同场景下何时使用Model3D与RealityView
整合RealityKit - 演示如何在SwiftUI中加载和嵌入RealityKit内容
处理空间交互 - 提供空间手势和实体目标交互的实现模式
管理生命周期 - 确保异步加载和状态管理的正确性

可从下表中加载对应的参考文件，获取详细用法、代码示例和最佳实践。

Quick Start Workflow

快速入门流程

Identify the presentation surface:
```
WindowGroup
```
, volumetric window, or
```
ImmersiveSpace
```
.
Choose a 3D API:
```
Model3D
```
for simple models,
```
RealityView
```
for full RealityKit scenes.
Load RealityKit content asynchronously and add entities in the
```
RealityView
```
make closure.
Use RealityView attachments to place SwiftUI UI in 3D space when needed.
Add spatial interaction with
```
SpatialTapGesture
```
or entity-targeted gestures.
Update RealityKit content in the
```
RealityView
```
update closure, not in SwiftUI body.
Validate scale using
```
defaultSize
```
for volumes and
```
immersionStyle
```
for immersive spaces.

确定展示载体：
```
WindowGroup
```
、体积窗口或
```
ImmersiveSpace
```
。
选择3D API：简单模型使用
```
Model3D
```
，完整RealityKit场景使用
```
RealityView
```
。
异步加载RealityKit内容，并在
```
RealityView
```
的make闭包中添加实体。
必要时，使用RealityView附件在3D空间中放置SwiftUI UI。
通过
```
SpatialTapGesture
```
或实体目标手势添加空间交互。
在
```
RealityView
```
的update闭包中更新RealityKit内容，而非SwiftUI body中。
为体积窗口设置
```
defaultSize
```
、为沉浸空间设置
```
immersionStyle
```
以验证缩放比例。

Information About the Skill

关于本技能的详细信息

Core Concepts

核心概念

Scene and Spatial Presentation

场景与空间展示

Use

WindowGroup

with

windowStyle(.volumetric)

and

defaultSize

for volumes.

Use
```
ImmersiveSpace
```
for unbounded spatial scenes and
```
immersionStyle
```
selection.
Use
```
openImmersiveSpace
```
and
```
dismissImmersiveSpace
```
for transitions.

对

WindowGroup

使用

windowStyle(.volumetric)

和

defaultSize

来创建体积窗口。

使用
```
ImmersiveSpace
```
创建无边界空间场景，并选择
```
immersionStyle
```
。
使用
```
openImmersiveSpace
```
和
```
dismissImmersiveSpace
```
实现场景切换。

RealityKit Embedding in SwiftUI

在SwiftUI中嵌入RealityKit

Use
```
RealityView
```
for full RealityKit scenes and per-frame updates.
Use
```
Attachment
```
and RealityView attachments to embed SwiftUI views in 3D.

Use

ViewAttachmentEntity

and

ViewAttachmentComponent

for attachment entities.

使用
```
RealityView
```
加载完整RealityKit场景并进行逐帧更新。
使用
```
Attachment
```
和RealityView附件在3D空间中嵌入SwiftUI视图。

使用

ViewAttachmentEntity

和

ViewAttachmentComponent

创建附件实体。

3D Model Presentation

3D模型展示

Use
```
Model3D
```
for async model loading with SwiftUI layout.
Use
```
Model3DPhase
```
and
```
Model3DAsset
```
for loading phases and animation choices.

使用
```
Model3D
```
结合SwiftUI布局实现异步模型加载。
使用
```
Model3DPhase
```
和
```
Model3DAsset
```
处理加载阶段和动画选择。

Spatial Input

空间输入

Use
```
SpatialTapGesture
```
for spatial tap locations in 2D/3D coordinate spaces.

使用
```
SpatialTapGesture
```
处理2D/3D坐标系中的空间点击位置。

Reference Files

参考文件

Reference	When to Use
`REFERENCE.md`	When looking for feature-focused code patterns and general guidance.
`model3d.md`	When using Model3D for async model loading, assets, animation, and manipulation.
`realityview.md`	When setting up RealityView, attachments, and RealityKit integration patterns.
`interaction.md`	When implementing gestures and manipulation patterns for spatial input.
`windowing-immersion.md`	When managing windows and immersive space patterns.
`spatial-layout.md`	When using SwiftUI spatial layout APIs and debug tools.
`charts-3d.md`	When implementing Chart3D and surface plot patterns.

参考文件	使用场景
`REFERENCE.md`	查找功能聚焦的代码模式和通用指导时使用。
`model3d.md`	使用Model3D进行异步模型加载、资源管理、动画和操作时使用。
`realityview.md`	设置RealityView、附件和RealityKit整合模式时使用。
`interaction.md`	实现空间输入的手势和操作模式时使用。
`windowing-immersion.md`	管理窗口和沉浸空间模式时使用。
`spatial-layout.md`	使用SwiftUI空间布局API和调试工具时使用。
`charts-3d.md`	实现Chart3D和曲面图模式时使用。

Implementation Patterns

实现模式

Use
```
Model3D
```
when you only need display and layout; use
```
RealityView
```
for custom entity graphs and systems.
Keep RealityKit mutations inside
```
RealityView
```
make/update closures.
Prefer attachments for UI that should remain SwiftUI-driven but positioned in 3D.
Treat
```
ImmersiveSpace
```
as a separate scene with its own lifecycle and environment actions.

仅需展示和布局时使用
```
Model3D
```
；需要自定义实体图和系统时使用
```
RealityView
```
。
将RealityKit的修改操作限制在
```
RealityView
```
的make/update闭包内。
对于需要保持SwiftUI驱动但要放置在3D空间中的UI，优先使用附件。
将
```
ImmersiveSpace
```
视为独立场景，拥有自身的生命周期和环境操作。

Pitfalls and Checks

常见陷阱与检查项

Do not block the main actor with synchronous model or entity loading.
Do not update RealityKit entities inside SwiftUI body computation.
Do not use volumetric window style with
```
Window
```
instead of
```
WindowGroup
```
.
Do not omit
```
defaultSize
```
for volumes; physical scale will be inconsistent.
Prefer
```
.glassBackgroundEffect()
```
for backgrounds instead of custom blur/material backgrounds.

不要使用同步模型或实体加载阻塞主线程。
不要在SwiftUI body计算过程中更新RealityKit实体。
不要对
```
Window
```
而非
```
WindowGroup
```
使用体积窗口样式。
体积窗口不要省略
```
defaultSize
```
，否则物理缩放比例会不一致。
优先使用
```
.glassBackgroundEffect()
```
作为背景，而非自定义模糊/材质背景。