主要目标系统掌握 ARKit 与 RealityKit 的分工协作机制深入理解空间计算的核心概念世界追踪、锚点、坐标系掌握图像追踪与书籍识别、3D 模型加载与动画控制、空间交互与物理模拟等关键技术并能够构建一个完整的 AR 书库应用。第一部分 建立心智模型ARKit 与 RealityKit 的分工1.1 框架职责划分iOS AR 开发的核心架构可以用一句话概括ARKit 负责“理解现实世界”RealityKit 负责“渲染虚拟内容”。框架定位核心职责关键类ARKit现实世界理解世界追踪、平面检测、图像识别、场景重建ARSession、ARWorldTrackingConfiguration、ARAnchorRealityKit虚拟内容渲染3D 渲染、动画、物理、空间音频RealityView、Entity、ModelEntity、AnchorEntity在 visionOS 中这一分工更加明确。Apple 官方文档指出“在 visionOS 中你使用 ARKit 仅用于获取关于用户周围环境的数据并且使用一组不同的 API。在 visionOS 中构建界面的首选技术是 SwiftUI 和 RealityKit。”RealityKit 是展示 3D 内容的最佳方式而 ARKit 提供关于真实世界环境的详细上下文信息。两者协作的方式ARKit 通过ARSession持续分析摄像头画面识别平面、图像、物体等现实世界特征并生成ARAnchor来标记这些特征的位置。RealityKit 的AnchorEntity可以绑定到这些锚点上将虚拟内容精准地放置在现实世界中。1.2 RealityKit 的 Entity Component SystemECSRealityKit 采用 ECS 架构这是理解 RealityKit 的关键概念职责示例Entity场景中的对象容器ModelEntity、AnchorEntity、EntityComponent附加到 Entity 的数据和行为ModelComponent、PhysicsBodyComponent、CollisionComponentSystem每帧更新的逻辑自定义 System 处理游戏逻辑所有 Entity 至少有一个TransformComponent位置、旋转、缩放。ModelEntity额外包含ModelComponent网格和材质AnchorEntity包含AnchoringComponent。第二部分 SwiftUI 中的 AR 视图RealityView 与 ARView2.1 RealityView推荐方式RealityView是 iOS 18 和 visionOS 中推荐的 SwiftUI 原生 AR 视图提供声明式的 3D 内容构建方式importSwiftUIimportRealityKitstructBookARView:View{StateprivatevarrootEntityEntity()varbody:someView{RealityView{contentin// make 闭包只执行一次用于初始内容加载content.add(rootEntity)}update:{contentin// update 闭包状态变化时执行// 注意不要在此修改被观察的状态避免无限循环}}}关键设计原则make闭包只在视图首次呈现时执行一次适合异步加载模型和初始设置。update闭包在观察状态变化时执行但不要在此修改被观察的状态。Apple 在 WWDC25 中明确警告“要避免在 SwiftUI 和 RealityKit 之间创建无限循环不要在 update 闭包中修改你观察的状态。你可以自由修改你没有观察的实体。”2.2 ARViewUIKit 桥接方式对于需要更底层控制的场景可以使用ARView来自 RealityKit配合UIViewRepresentable桥接到 SwiftUIstructARContainerView:UIViewRepresentable{funcmakeUIView(context:Context)-ARView{letarViewARView(frame:.zero)letconfigARWorldTrackingConfiguration()config.planeDetection[.horizontal]config.environmentTexturing.automatic arView.session.run(config)returnarView}funcupdateUIView(_uiView:ARView,context:Context){}}选择建议新项目优先使用RealityView它更符合 SwiftUI 的设计哲学。仅在需要访问 ARView 的特有功能如自定义渲染管线时才使用ARView。第三部分 图像追踪与书籍识别3.1 配置参考图像图像追踪是 AR 书库应用的核心能力。ARKit 可以检测并追踪现实世界中的 2D 图像如书籍封面、海报或产品包装。参考图像的质量要求Apple 官方文档强调具有高对比度、包含丰富不规则纹理和大量独立视觉特征的图像最利于算法实现快速追踪。应尽量指定待检测图像的预期物理尺寸以提升检测性能。文档建议开发者尽量选用哑光或防反光材质制作现实中的实体标识因为强烈的反光斑点或光滑表面反射的环境倒影会直接破坏视觉算法对特征点的稳定提取。Apple 将不可追踪的图像定义为具有重复结构、均匀颜色区域、狭窄直方图。在 Xcode 中配置将书籍封面添加到 Assets.xcassets 中设置为 AR Reference Image 类型并指定物理尺寸如 15cm × 22cm。3.2 配置世界追踪会话funcconfigureImageTracking(inarView:ARView){guardletreferenceImagesARReferenceImage.referenceImages(inGroupNamed:AR Resources,bundle:nil)else{return}letconfigARWorldTrackingConfiguration()config.detectionImagesreferenceImages config.maximumNumberOfTrackedImages4arView.session.run(config)}3.3 处理图像锚点当 ARKit 检测到参考图像时会通过ARSessionDelegate的session(_:didAdd:)回调通知funcsession(_session:ARSession,didAdd anchors:[ARAnchor]){foranchorinanchors{guardletimageAnchoranchoras?ARImageAnchorelse{continue}letanchorEntityAnchorEntity(anchor:imageAnchor)anchorEntity.addChild(createBookContent(for:imageAnchor))arView.scene.addAnchor(anchorEntity)}}3.4 从图像锚点获取信息ARImageAnchor提供以下关键信息属性用途referenceImage.name识别到的参考图像名称用于匹配书籍referenceImage.physicalSize图像的物理尺寸isTracked图像当前是否被追踪funccreateBookContent(foranchor:ARImageAnchor)-Entity{guardletbookTitleanchor.referenceImage.nameelse{returnEntity()}letbookContentEntity()letlabelModelEntity(mesh:.generateText(bookTitle,extrusionDepth:0.005),materials:[SimpleMaterial(color:.white,isMetallic:false)])label.position[0,0.1,0]bookContent.addChild(label)returnbookContent}第四部分 3D 模型加载与动画控制4.1 异步加载模型从 iOS 18 开始ModelEntity.loadAsync(named:)已被废弃。推荐使用Entity(named:)异步初始化器替代。funcloadBookModel(named name:String)asyncthrows-Entity{letentitytryawaitEntity(named:name)returnentity}在RealityView的make闭包中异步加载RealityView{contentinTask{ifletmodeltry?awaitEntity(named:book_model){content.add(model)}}}4.2 动画播放控制使用Model3DAsset加载并控制 3D 内容的动画。模型从资源中载入动画并让开发者选择要播放哪一个。资源会提供一个animationPlaybackController用于控制播放// 使用 Model3DAsset 加载模型和动画letassettryawaitModel3DAsset(named:robot)asset.selectedAnimationasset.availableAnimations.firstletmodel3DModel3D(asset:asset)// 通过 animationPlaybackController 控制播放asset.animationPlaybackController?.play()4.3 实体操作与交互visionOS 26 新增了ManipulationComponent让用户可以用单手或双手抓起虚拟物体。ManipulationComponent.configureEntity会自动添加CollisionComponent、InputTargetComponent和HoverEffectComponent使实体能够响应手势操作。RealityKit 还新增了ViewAttachmentComponent、GestureComponent和PresentationComponent三个 SwiftUI 风格的新组件。第五部分 空间锚点与持久化5.1 世界地图持久化Apple 官方文档指出持久化 AR 体验的核心是当 App 进入非活跃状态时保存世界地图然后在下次于同一物理环境中启动 App 时恢复该地图。可以使用恢复的世界地图中的锚点将相同的虚拟内容放置在与已保存会话中相同的位置。// 保存世界地图funcsaveWorldMap(){arView.session.getCurrentWorldMap{worldMap,erroringuardletmapworldMapelse{return}do{letdatatryNSKeyedArchiver.archivedData(withRootObject:map,requiringSecureCoding:true)trydata.write(to:worldMapURL)}catch{print(保存世界地图失败:\(error))}}}// 恢复世界地图funcloadWorldMap(){guardletdatatry?Data(contentsOf:worldMapURL),letworldMaptry?NSKeyedUnarchiver.unarchivedObject(ofClass:ARWorldMap.self,from:data)else{return}letconfigARWorldTrackingConfiguration()config.initialWorldMapworldMap config.detectionImagesreferenceImages arView.session.run(config)}第六部分 光照与材质让虚拟内容融入现实6.1 环境光照贴图RealityKit 自动使用环境光照来照亮虚拟内容。当 App 获得世界追踪权限后ARKit 会自动分析现实世界的光照条件色温、亮度RealityKit 据此调整虚拟物体的光照效果使虚拟内容看起来像真实存在于环境中。6.2 物理基础材质PhysicallyBasedMaterialPBR是 RealityKit 中最常用的材质类型会对光照做出真实反应可用于表示各种真实世界的材质。PBR 材质通过金属度、粗糙度、法线贴图等参数模拟真实的表面光学特性。6.3 软阴影RealityKit 新增了软阴影支持。默认情况下阴影具有硬边缘当光源有一定面积时会投射更柔和的边缘半影区域。可以通过设置shadow.lightSize来调整光源直径单位为米数值越大阴影边缘越柔和。shadow.quality控制采样数量.medium和.high才能产生软阴影.low会退化成硬阴影。shadow.lightSize0.7// 米shadow.quality.medium// 或 .high第七部分 综合实战AR 书库应用7.1 架构设计ObservablefinalclassARBookLibraryViewModel{varselectedBook:String?varisModelLoadedfalsefunchandleImageAnchor(_anchor:ARImageAnchor)-Entity{guardletbookNameanchor.referenceImage.nameelse{returnEntity()}letentityEntity()lettextModelEntity(mesh:.generateText(bookName,extrusionDepth:0.003),materials:[SimpleMaterial(color:.white,isMetallic:false)])text.position[0,0.12,0]entity.addChild(text)returnentity}}7.2 SwiftUI 视图structARBookLibraryView:View{StateprivatevarviewModelARBookLibraryViewModel()varbody:someView{ARContainerView().ignoresSafeArea().overlay(alignment:.bottom){ifletbookviewModel.selectedBook{BookInfoCard(title:book).padding()}}}}第八部分 习题与答案解读每题后紧跟答案和解读共15题。习题1【单选】ARKit 与 RealityKit 的分工以下哪项最准确地描述了 ARKit 和 RealityKit 的分工A. ARKit 和 RealityKit 是竞争关系选一个即可B. ARKit 负责渲染 3D 内容RealityKit 负责世界追踪C. ARKit 负责理解现实世界世界追踪、平面检测、图像识别RealityKit 负责渲染虚拟内容D. 两者功能完全相同可以互换使用答案C解读ARKit 负责“理解现实世界”RealityKit 负责“渲染虚拟内容”。在 visionOS 中Apple 明确指出“你使用 ARKit 仅用于获取关于用户周围环境的数据而 SwiftUI 和 RealityKit 控制 2D 或 3D 内容的放置。”习题2【判断】ModelEntity.loadAsync(named:) 是当前推荐的模型加载方式答案错误解读ModelEntity.loadAsync(named:in:)在 iOS 18 中已被标记为 deprecated。推荐使用Entity(named:)异步初始化器替代。习题3【多选】RealityView 的 make 和 update 闭包以下关于 RealityView 的 make 和 update 闭包的说法哪些是正确的A. make 闭包只在视图首次呈现时执行一次B. update 闭包在观察状态变化时执行C. 可以在 update 闭包中自由修改被观察的状态D. 在 update 闭包中修改被观察的状态可能导致无限循环E. make 闭包适合异步加载模型答案A、B、D、E解读make 闭包只在视图首次呈现时执行一次适合异步加载模型。update 闭包在观察状态变化时执行。但不要在 update 闭包中修改被观察的状态否则会创建无限循环。Apple 明确警告“不要修改你观察的状态你可以自由修改你没有观察的实体。”C 错误。习题4【单选】图像追踪参考图像的质量要求以下哪项不是 ARKit 参考图像的推荐特征A. 丰富纹理B. 高对比度C. 纹理重复D. 高分辨率答案C解读Apple 官方文档指出参考图像应具有高对比度、包含丰富不规则纹理和大量独立视觉特征。纹理重复会降低检测性能Apple 将具有重复结构的图像定义为不可追踪。习题5【简答】RealityKit 的 ECS 架构是什么答案RealityKit 采用 Entity Component SystemECS架构将应用程序对象分为三种类型Entity场景中的对象容器可以是 3D 模型、形状图元、灯光甚至不可见的声音发射器。所有 Entity 至少有一个TransformComponent。Component附加到 Entity 的数据和行为如ModelComponent网格和材质、PhysicsBodyComponent物理属性、CollisionComponent碰撞形状。System每帧更新的逻辑处理跨多个 Entity 的行为。习题6【多选】ARWorldMap 的用途以下哪些是 ARWorldMap 的用途A. 保存 AR 会话的空间映射数据B. 在下次启动时恢复虚拟内容的位置C. 实时渲染 3D 模型D. 实现持久化 AR 体验E. 替代 ARImageAnchor答案A、B、D解读ARWorldMap 用于保存 AR 会话的空间映射数据可以在下次于同一物理环境中启动 App 时恢复该地图实现持久化 AR 体验。C 错误——ARWorldMap 不负责渲染。E 错误——ARWorldMap 和 ARImageAnchor 是不同层面的技术。习题7【代码补全】配置图像追踪会话补全代码配置一个支持图像追踪的 AR 会话。funcconfigureImageTracking(inarView:ARView){guardletreferenceImagesARReferenceImage.referenceImages(inGroupNamed:__________,bundle:nil)else{return}letconfigARWorldTrackingConfiguration()config.__________referenceImages config.maximumNumberOfTrackedImages__________arView.session.run(config)}答案guardletreferenceImagesARReferenceImage.referenceImages(inGroupNamed:AR Resources,bundle:nil)else{return}letconfigARWorldTrackingConfiguration()config.detectionImagesreferenceImages config.maximumNumberOfTrackedImages4习题8【简答】RealityView和ARView的区别是什么各自适用什么场景答案RealityViewSwiftUI 原生视图提供声明式的 3D 内容构建方式。适合新项目与 SwiftUI 状态管理集成自然。使用make和update闭包管理内容。ARViewRealityKit 提供的 UIKit 视图提供更底层的控制。适合需要访问 ARView 特有功能如自定义渲染管线、直接操作 ARSession的场景。需要通过UIViewRepresentable桥接到 SwiftUI。解读新项目优先使用RealityView仅在需要 ARView 特有功能时才使用桥接方式。习题9【判断】图像追踪可以在任何表面上工作答案错误解读Apple 官方文档明确指出应仅使用平面上的图像进行检测。如果待检测图像位于非平面表面上如酒瓶上的标签ARKit 可能完全无法检测到或者可能在错误位置创建图像锚点。习题10【代码补全】处理图像锚点补全代码在检测到参考图像时创建虚拟内容。funcsession(_session:ARSession,didAdd anchors:[ARAnchor]){foranchorinanchors{guardletimageAnchoranchoras?__________else{continue}letanchorEntityAnchorEntity(anchor:__________)anchorEntity.addChild(createBookContent(for:imageAnchor))arView.scene.addAnchor(anchorEntity)}}答案guardletimageAnchoranchoras?ARImageAnchorelse{continue}letanchorEntityAnchorEntity(anchor:imageAnchor)习题11【多选】以下哪些是 RealityKit 支持的物理模拟功能A. 碰撞检测B. 重力模拟C. 布料模拟D. 光线追踪E. 导航网格答案A、B、C、E解读RealityKit 支持碰撞检测、重力模拟、布料模拟和导航网格。D 错误——光线追踪不是 RealityKit 的标准物理模拟功能。习题12【简答】如何实现 AR 内容的持久化答案实现 AR 内容持久化的核心步骤在 App 进入非活跃状态时调用arView.session.getCurrentWorldMap获取当前世界地图。将世界地图序列化为 Data 并保存到文件系统。下次启动时从文件系统加载世界地图数据反序列化为ARWorldMap。创建新的ARWorldTrackingConfiguration设置config.initialWorldMap worldMap。运行会话恢复的锚点会自动重新定位虚拟内容。习题13【设计题】设计一个 AR 书库应用的核心功能请设计一个 AR 书库应用的核心功能包括书籍识别、3D 内容展示和持久化。答案示例书籍识别将书籍封面添加到 Asset Catalog 的 AR Resources 中配置ARWorldTrackingConfiguration.detectionImages。3D 内容展示检测到书籍封面后创建AnchorEntity并添加 3D 书签、评分标签或动画效果。持久化保存 ARWorldMap下次启动时恢复虚拟内容的位置。核心代码结构ObservablefinalclassARBookLibrary{vardetectedBooks:[String][]varselectedBook:String?funchandleImageAnchor(_anchor:ARImageAnchor)-Entity{/* ... */}funcsaveWorldMap(){/* ... */}funcloadWorldMap(){/* ... */}}习题14【简答】RealityKit 的软阴影是什么有什么用途答案RealityKit 的软阴影是对传统硬阴影的改进。默认情况下RealityKit 中的阴影具有硬边缘当光源无限小时这是准确的。但当光源有一定面积时投射的阴影会呈现更柔和的边缘半影区域半影的大小受光源面积影响。可以通过设置shadow.lightSize来调整光源直径单位为米产生柔和阴影。例如将lightSize从默认值 0硬阴影更新为 0.7 米可以产生漂亮的柔和阴影。shadow.quality需要设置为.medium或.high才能产生软阴影。习题15【综合论述】如何构建一个完整的 AR 书库应用答案构建完整的 AR 书库应用需要整合以下核心技术1. 图像追踪ARKit将书籍封面配置为 AR Reference Image设置ARWorldTrackingConfiguration.detectionImages在ARSessionDelegate的session(_:didAdd:)回调中处理检测到的ARImageAnchor。2. 虚拟内容渲染RealityKit使用AnchorEntity(anchor:)将 RealityKit 内容绑定到图像锚点。使用ModelEntity加载 3D 模型使用PhysicallyBasedMaterial实现真实的材质效果。使用Entity(named:)异步加载模型。3. 空间持久化ARWorldMap保存世界地图在下次启动时恢复实现虚拟内容的位置持久化。4. SwiftUI 集成使用RealityView构建 AR 视图通过make闭包异步加载模型通过update闭包响应状态变化。关键原则ARKit 负责理解现实世界RealityKit 负责渲染虚拟内容。图像追踪识别书籍RealityKit 展示 3D 内容ARWorldMap 实现持久化。第九部分 知识点总结1. 框架职责划分框架定位核心职责ARKit现实世界理解世界追踪、平面检测、图像识别、场景重建RealityKit虚拟内容渲染3D 渲染、动画、物理、空间音频2. RealityKit ECS 架构概念职责示例Entity场景中的对象容器ModelEntity、AnchorEntityComponent附加到 Entity 的数据和行为ModelComponent、PhysicsBodyComponentSystem每帧更新的逻辑自定义 System3. 图像追踪核心 APIAPI用途关键要点ARReferenceImage定义参考图像丰富纹理、高对比度、纹理不重复ARWorldTrackingConfiguration配置追踪会话detectionImages设置图像集合ARImageAnchor图像锚点referenceImage.name匹配书籍AnchorEntity(anchor:)绑定锚点将 RealityKit 内容绑定到 ARKit 锚点4. 模型加载与动画API用途关键要点Entity(named:)异步加载模型替代废弃的loadAsyncModel3DAsset加载模型和动画提供animationPlaybackControllerManipulationComponent实体操作visionOS 26 新功能5. 持久化与光照API用途关键要点ARWorldMap世界地图持久化保存后恢复虚拟内容位置PhysicallyBasedMaterialPBR 材质对光照做出真实反应软阴影真实光照效果设置shadow.lightSize和shadow.quality6. 常见陷阱ModelEntity.loadAsync已废弃应使用Entity(named:)在RealityView的update闭包中修改被观察的状态会导致无限循环参考图像纹理重复会降低检测性能在非平面表面上使用图像追踪可能无法检测未配置maximumNumberOfTrackedImages可能影响性能在 visionOS 上优先使用 RealityKit 而非 ARKit7. 行动清单将书籍封面配置为 AR Reference Image确保纹理丰富且不重复使用ARWorldTrackingConfiguration.detectionImages配置图像追踪在session(_:didAdd:)回调中处理ARImageAnchor使用AnchorEntity(anchor:)将 RealityKit 内容绑定到锚点使用Entity(named:)异步加载 3D 模型使用RealityView的make闭包执行一次性初始化在update闭包中只修改未观察的实体使用ARWorldMap实现持久化 AR 体验使用PhysicallyBasedMaterial实现真实材质效果在 visionOS 上优先使用 RealityKit 的SpatialTrackingSession