VisionOS-UI-Framework

一个面向 visionOS 2、iOS 18 和 macOS 15、无依赖的 Swift package(模块名 VisionUI)。5 种布局能根据同一份数据,在 3D 空间中摆放 SwiftUI view 和 RealityKit entity;一个 coordinator 按一次一个请求的方式打开和关闭沉浸式空间;一个值类型的状态会把被拖动、捏合和旋转的物体保持在你设定的限制范围内。在 iOS 和 macOS 上,这些布局会以正面视角绘制,因此同一份代码也能在那些平台上运行。

功能特性

5 种布局(arc、ring、grid、sphere、helix),为每个元素返回以米为单位的位置和朝向;SwiftUI view 通过 SpatialLayoutView 使用,RealityKit entity 通过 arrangeChildren(using:) 使用

SpatialCarousel:一圈 view 组成的环,拖动后会停在最近的一个 view 上,支持 selection binding、VoiceOver 的 adjustable action,以及 Reduce Motion

ImmersiveSpaceCoordinator 在过渡期间拒绝第二个请求,会先关闭一个空间再打开另一个,忽略已被替换请求的迟到应答,并在空间被 Digital Crown 关闭时跟随系统状态

ManipulationState 把物体限制在一个盒状范围和一个缩放范围内,支持自由旋转、保持竖直或锁定旋转、yaw 吸附,并为每次手势记录一个起始值

SpatialCard、一个在 visionOS 上会变成 ornament 的工具栏,以及按 Apple 规范设定尺寸的点击目标(visionOS 60 pt、iOS 44 pt、macOS 28 pt)

每个公开 API 都有输入检查:数量上限为 4096 项,长度上限为 10 km,NaN 或无穷大的参数会回退到文档中说明的默认值

97 个 Swift Testing 测试在 macOS 和 iPhone 模拟器上运行;其中除像素测试外的 87 个,也会在 visionOS 模拟器上运行

包含 4 篇文章的 DocC catalog,以及面向 visionOS、iOS 和 macOS 的 SpatialGallery 示例 app;README 中的示例代码由该 app 和测试共同编译验证

快速开始

swift

1import SwiftUI
2import VisionUI
3 
4struct ContentView: View {
5    let planets = ["Mercury", "Venus", "Earth", "Mars", "Jupiter"]
6 
7    var body: some View {
8        SpatialLayoutView(.arc(radius: 0.6, spacing: 0.17), planets, id: \.self) { planet in
9            SpatialCard {
10                Text(planet)
11                    .font(.title)
12            }
13        }
14    }
15}

安装

Xcode (File › Add Package Dependencies…)

text

1https://github.com/muhittincamdali/VisionOS-UI-Framework.git

Swift Package Manager

swift

1dependencies: [
2    .package(url: "https://github.com/muhittincamdali/VisionOS-UI-Framework.git", from: "2.0.0")
3],
4targets: [
5    .target(name: "YourApp", dependencies: [
6        .product(name: "VisionUI", package: "VisionOS-UI-Framework")
7    ])
8]