RealityUI

RealityUI 是一个用于 RealityKit 的实用工具和 UI 对象集合。 RealityUI 中包含的 UI 对象旨在通过 RealityKit 为增强现实和虚拟现实提供熟悉的用户界面标准,但在三维环境中呈现。

RealityUI 还包含一系列组件,用于通过触摸或拖动交互与任何实体进行交互。

RealityKit VR 空间中的 RealityUI 元素

要求

iOS 13, macOS 10.15 或 visionOS 1.0
Swift 5.8
Xcode 13

内容

RealityUI
- 要求
- 内容
- 安装
  - Swift Package Manager
- 使用
  - 注册 RealityUI 组件
  - 激活手势
    - visionOS
    - iOS/macOS
- 控制实体
- 手势
  - 拖动
  - 转动
  - 点击
- 动画
  - 旋转
  - 抖动
- 文本
- 更多

安装

Swift Package Manager

将此仓库的 URL 添加到 Xcode 11+ 项目的 Project > Swift Packages 中。

https://github.com/maxxfrazer/RealityUI.git

使用

在 Swift 文件顶部添加 import RealityUI 即可开始使用。

注册 RealityUI 组件

在使用 RealityUI 中的所有组件之前,必须先注册这些组件。只需在应用程序中任何以 RUI 开头的类初始化之前调用 RealityUI.registerComponents() 即可,以避免出现问题。有关注册组件的更多信息,请参阅 Apple 的文档。

激活手势

visionOS

在 visionOS 中,可以使用 View/addRUIDragGesture() 或 View/addRUITapGesture() 修饰符在 RealityView 上启用手势,或直接添加手势 .gesture(RUIDragGesture()) 或 .gesture(RUITapGesture())。RealityView 可能如下所示:

RealityView { content in
    let swtch = RUISwitch()
    swtch.scale = .init(repeating: 0.1)
    content.add(swtch)
}.addRUIDragGesture()

上面的代码片段向场景中添加了一个可交互的开关/切换。

此手势适用于任何带有 RUIDragComponent 的实体,例如:

RealityView { content in
    let movable = try! await ModelEntity(named: "toy_biplane")
    movable.generateCollisionShapes(recursive: false)

    movable.components.set(RUIDragComponent(type: .move(nil)))
    movable.components.set(InputTargetComponent())

    content.add(movable)
}.addRUIDragGesture()

在 Vision Pro 模拟器中移动双翼飞机

iOS/macOS

可以通过调用 RealityUI.enableGestures(.all, on: ARView) 来启用 RealityUI 手势,其中 ARView 是你的 ARView 对象实例。

RUISlider、RUISwitch、RUIStepper 和 RUIButton 都使用 RUIDragComponent，需要 .ruiDrag。如果你添加了使用 RUITapComponent 组件的元素,可以使用 .tap 手势。我建议在启用手势时使用 .all,因为随着 RealityUI 的发展,这些手势可能会发生变化。

RealityUI.enableGestures(.all, on: arView)

控制实体

默认情况下,所有 RealityUI 实体都相当大。这是为了标准化尺寸,以便你始终知道会得到什么结果。例如,所有 UI 滑块都是直径为 1 米的球体,在 RealityKit 中相当于 1 个单位,± 任何填充调整。所有 RealityUI 实体默认面向 [0, 0, -1]。要让它们指向用户摄像机或 .zero,你可以使用 .look(at:,from:,relativeTo:) 方法,如下所示: .look(at: .zero, from: [0, 0, 1])。或者,如果你想让它在定位在 [0, 0, -1] 时立即转向,将方向设置为 simd_quatf(angle: .pi, axis: [0, 1, 0])。通过将 at: 值设置为按钮应该从中使用的方向,可以在此处使用 .look() 方法。

RUISwitch

RUISwitch 是一个具有开启和关闭状态的 3D 切换开关。默认边界框为 2x1x1m

带有和不带有光响应的 RUISwitch

更多详情

RUIStepper

RUIStepper 用于增加或减少一个值。默认边界框为 2x1x0.25m

带有光响应的 RUIStepper

更多详情

RUISlider

一个交互式轨道,用于表示插值。默认边界框为 10x1x1m,包括滑块。

带有光响应的 RUISlider

更多详情

RUIButton

RUIButton用于触发特定操作。这里的操作只有在手势开始于按钮上并在同一按钮上结束时才会触发。这类似于touchUpInside UIControl事件。按下按钮到底座之前的默认按钮边界框为[1, 1, 0.3]

具有轻响应性的RUIButton

更多详情

手势

所有RealityUI控制实体都使用自定义手势，这些手势在RealityKit中并非标准，但其中一些已被独立出来，以便任何人都可以使用它们来操作自己的RealityKit场景。

拖拽

使用RUIDragComponent的.move类型，可以在空间中以三个自由度拖拽对象。

拖拽立方体

这种类型有一个可选的约束，用于在特定条件下限制移动：

盒子约束：将移动限制在指定的BoundingBox内，提供一个实体可以移动的定义区域。
点约束：将移动限制在一组预定义的点上，以SIMD3<Float>数组表示。
钳制约束：使用自定义钳制函数来控制移动。此函数接收一个SIMD3<Float>作为输入，并返回一个修改后的SIMD3<Float>以确定新位置。