# Spatial UI Sample

[English](README.md) | [简体中文](README_zh.md)

一个基于 PICO OS 6 的参考示例应用，用于演示 PICO Spatial SDK 中各类 UI 组件与功能的使用方式。该示例展示了如何将传统 2D UI 演进为具备空间感与高交互性的 3D 空间 UI 界面。

## 概述

Spatial UI Sample 是一个基于 Jetpack Compose 构建的综合性参考项目，用于指导开发者构建丰富的多窗口空间应用。项目涵盖空间窗口管理、空间导航模式，以及在 3D 环境中渲染玻璃拟态（Glassmorphism）材质等核心能力。

通过本项目，你将学习：

- 初始化空间应用，并以声明式方式集成 Compose UI
- 管理空间窗口，包括创建独立的子窗口、工具栏和弹窗
- 实现空间导航模式，如侧边导航和支持视点跟随的 TabBar
- 利用 PICO Spatial UI 设计系统的材质，例如空间特有的玻璃拟态效果（Vibrant 材质），实现 UI 与真实环境的自然融合

## 核心能力

Spatial UI Sample 重点展示了 PICO Spatial SDK 的以下核心能力：

### 1. 基础框架与初始化
- **应用启动**：演示如何使用 `launch(::mainApp)` 初始化空间应用，并挂载 Compose UI
- **作用域管理**：展示 `SpatialAppScope` 和 `DefaultWindowContainer` 的基础用法

### 2. 窗口系统 (Windowing)
- **子窗口 (Subwindow)**：创建独立且可交互的子窗口（如用户详情弹窗），支持多任务协同
- **工具栏 (Toolbar)**：展示附着在窗口边缘的全局操作栏
- **空间弹窗 (SpatialPopup)**：轻量级的空间定位弹窗
- **标题栏 (TitleBar)**：标准的窗口顶部配置，支持自定义标题和返回逻辑

### 3. 空间导航
- **TabBar**：支持侧边导航模式（`TabBarPlacement.Left`）
- **视点跟随 (Gaze-following)**：通过 followViewpoints 实现导航栏随用户视线动态移动
- **侧边导航 (SideNavigation)**：适用于复杂层级页面的标准垂直导航

### 4. 引导与反馈
- **新手引导 (Coachmark)**：演示了 `RichCoachmark` 的用法，支持标题、图片及指向性引导
- **消息提示**：展示了 `SnackbarHost` 空间消息提示系统
- **进度指示**：圆形与线性进度条

### 5. 丰富的基础组件
- **交互控件**：`Button`, `IconButton`, `Switch`, `Slider`, `SegmentControl` 等
- **输入组件**：`TextField`, `TextArea`, `SearchField`, `NumberField`
- **标签系统**：`Badge`, `ButtonChip`, `RemovableChip`, `ToggleableChip`
- **菜单系统**：`Menu` 与 `MenuItem`，结合 `rememberMenuPositionProvider` 实现精确的空间定位弹出

### 6. 设计系统与材质
- **PicoTheme**：全局空间视觉主题
- **Vibrant 材质**：空间 UI 特有的玻璃拟态效果（如 `Vibrant.Light`, `Vibrant.Darkest`），增强 UI 与物理环境的融合感

## 环境要求

构建和运行本项目前，请参照 PICO Spatial SDK 官方文档完成开发环境配置：

- [PICO Spatial SDK 环境配置指南（中国大陆）](https://developer-cn.picoxr.com/document/spatial-sdk/set-up-development-environment/)
- [PICO Spatial SDK 环境配置指南（非中国大陆）](https://developer.picoxr.com/document/spatial-sdk/set-up-development-environment/)

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd SpatialUI
```

### 2. 在 Android Studio 中打开项目

启动 Android Studio，选择 **Open an Existing Project**，然后选择 `SpatialUI` 目录。

### 3. 运行项目

#### 在模拟器上运行

1. 打开 **Device Manager**（可通过工具栏或 **Tools > Device Manager** 进入）
2. 点击 **Add a new device** > **Create a PICO Emulator**
3. 在 **Device Manager** 中启动模拟器
4. 点击 **Run 'app'** 启动应用

#### 在物理设备上运行

1. 将 PICO 设备连接至开发机
2. 在设备上启用 **USB 调试（USB Debugging）**
3. 点击 **Run 'app'** 将应用直接部署到设备

## 目录结构

Spatial UI 示例项目遵循模块化架构，将应用逻辑与 UI 组件分离：

```txt
SpatialUI/
├── app/                                  # 主应用模块
│   └── src/main/
│       ├── java/com/pico/spatialui/sample/ # Kotlin 源代码文件
│       │   ├── app/                        # 平台相关实现
│       │   │   ├── LaunchActivity.kt       # Android 启动 Activity
│       │   │   └── SpatialApplication.kt   # 应用初始化
│       │   ├── model/                      # 数据模型
│       │   │   └── DataModel.kt            # 应用数据模型
│       │   ├── pages/                      # 各种功能页面的实现演示
│       │   │   ├── userpage/               # 用户中心相关页面和内容
│       │   │   ├── ContentDetailPage.kt    # 内容详情页实现
│       │   │   ├── FeedsPage.kt            # 动态内容页实现
│       │   │   ├── HomePage.kt             # 首页主页面实现
│       │   │   └── SearchPage.kt           # 搜索页实现
│       │   ├── router/                     # 应用路由配置
│       │   │   └── AppGraphRouter.kt       # 导航图与路由定义
│       │   ├── viewmodel/                  # 业务逻辑与数据管理
│       │   │   ├── CoachMarkManager.kt     # 新手引导/教程状态管理
│       │   │   ├── FeedsViewModel.kt       # 动态页面业务逻辑
│       │   │   ├── RelationshipViewModel.kt # 用户关系页面业务逻辑
│       │   │   └── SearchViewModel.kt      # 搜索页业务逻辑
│       │   └── Main.kt                     # 入口点：设置空间 UI 容器并启动主应用
│       ├── res/                            # Android 资源文件
│       └── AndroidManifest.xml             # 包含 Spatial 组件声明的应用清单
├── gradle/                               # Gradle 依赖与构建脚本
├── build.gradle.kts                      # 根构建配置
└── settings.gradle.kts                   # 项目设置与 SDK 配置
```

## 学习资源

深入了解空间应用开发，欢迎访问官方开发者网站获取完整资源：

- [PICO 开发者网站（中国大陆）](https://developer-cn.picoxr.com/)
- [PICO 开发者网站（非中国大陆）](https://developer.picoxr.com/)

## 许可证

© 2026 PICO。本项目的源代码依据 [Apache 2.0 License](LICENSE.txt) 协议开源。本项目的美术资产（包括但不限于纹理、3D 模型和音频）基于 [Creative Commons BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权。

## 支持

如有任何问题、疑惑或功能建议，欢迎通过 [PICO 开发者支持门户](https://picodevsupport.freshdesk.com/support/home) 提交工单与我们联系。

---

为空间应用开发者提供的官方参考示例
