RealityUI

RealityUI 是一个为 RealityKit 打造的实用工具和 UI 对象集合。RealityUI 中包含的 UI 对象旨在为增强现实和虚拟现实中的 3D 环境提供熟悉的用户界面标准，这一切都通过 RealityKit 实现。

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()

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 拨动开关。默认边界框为 2x1x1 米

更多详情

RUIStepper

RUIStepper 用于递增或递减值。默认边界框为 2x1x0.25 米

更多详情

RUISlider

一个交互式轨道，用于表示插值。默认边界框为 10x1x1 米，包括拇指。

更多详情

RUIButton

RUIButton 用于启动指定的动作。此处的动作仅在手势在按钮上开始并在同一按钮上结束时才会触发。这类似于 touchUpInside UIControl 事件。按下按钮进入底座之前的默认按钮边界框为 [1, 1, 0.3]

更多详情

手势

所有 RealityUI 控制实体都使用 RealityKit 中非标准的自定义手势，但其中一些手势已被隔离，因此任何人都可以使用它们来操作自己的 RealityKit 场景。

拖拽

使用 RUIDragComponent，通过 .move 类型，在空间中的任何位置以 3 个自由度拖动对象。

此类型具有可选的约束，用于将移动限制在特定条件内

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