spatial-swiftui-developer

Spatial SwiftUI 开发者

快速开始

1. 如果任务确实涉及表面选择、场景所有权或文件结构，请先切换到 spatial-app-architecture。
2. 如果任务涉及 Chart3D、SurfacePlot、3D 图表标记或 Chart3DPose，请切换到 $swiftui-chart3d-developer。
3. 选择渲染路径：简单资产展示使用 Model3D，自定义实体图和附件使用 RealityView。
4. 仅加载匹配的参考文件。
5. 保持异步加载，并在指定入口点中修改 RealityKit 内容。
6. 将构建、启动、模拟器和测试问题转交给 build-run-debug。

以下情况请加载参考资料

参考资料	使用时机
swiftui-spatial-overview.md	需要了解此技能的整体功能概览、示例和路由指南时。
model3d.md	使用 Model3D 进行异步模型加载、资产、动画或操作时。
realityview.md	设置 RealityView、附件或 RealityKit 集成模式时。
interaction.md	实现空间输入的手势或操作模式时。
buttons-and-controls.md	实现可见的 SwiftUI 按钮、设置为按钮样式的链接、工具栏、表单或控件表面时。
swiftui-scene-lifecycle.md	检查官方 Window、WindowGroup、ImmersiveSpace、打开/关闭、恢复和启动约定时。
windowing-immersion.md	管理窗口、体积表面或沉浸空间转换时。
spatial-layout.md	使用 SwiftUI 空间布局 API、调整尺寸或使用调试工具时。

工作流

1. 确认架构和场景所有权已经确定。
2. 选择渲染表面：Model3D、RealityView、窗口、体积或沉浸式场景。
3. 仅加载匹配的参考文件。
4. 实现最小可行场景，并在正确的层中进行修改。
5. 概述所选的 SwiftUI 到 RealityKit 集成路径。

注意事项

• 每个可见按钮都必须显式设置 .buttonBorderShape(...)（带标签的操作使用 .capsule，仅图标按钮使用 .circle，卡片式按钮使用与背景匹配的 .roundedRectangle(radius:)——在 visionOS 上，这也决定按钮悬停高亮的形状）。非按钮悬停表面应将 .hoverEffect() 与匹配的 .contentShape(.hoverEffect, ...) 配合使用。编写任何控件代码前都要加载 buttons-and-controls.md——即使按钮只是大型任务中的附带内容，也同样适用。
• 保持 RealityKit 加载异步；不要在主执行器上阻塞资产或实体加载。
• 在 RealityView 的 make 或 update 闭包中，或在系统中修改 RealityKit 内容，不要在 SwiftUI body 代码中修改。
• 仅在需要简单展示和布局而非自定义 ECS 图时使用 Model3D。
• 将 ImmersiveSpace 视为具有自身生命周期和环境操作的独立场景。
• 仅将 defaultSize 用作初始提示；系统可能会限制尺寸或恢复几何状态。
• 对于 Chart3D 和空间数据可视化，请使用 $swiftui-chart3d-developer。
• 如果问题涉及启动、构建、模拟器、代码签名或调试工作流，请切换到 build-run-debug。
• 如果问题涉及场景边界、所有权或功能拆分，而非 API 用法，请使用 spatial-app-architecture。
• visionOS 27 的 SwiftUI 未新增场景、体积或沉浸式 API；此处的指南适用于 visionOS 27。27 版新增内容：手势 inputKinds: 过滤（参见 interaction.md），以及同样适用于 visionOS 的跨平台工具栏和导航改进。

输出要求

请提供：

• 选用的渲染和场景路径
• 使用了哪些参考资料
• 涉及的 API 范围（Model3D、RealityView、窗口管理、交互或布局）
• 主要的实现约束或注意事项
• 如有需要，返回架构、Chart3D 或构建／调试相关内容的路径