基于 Rokid Max 与 JSAR 构建空间锚定型 AR 信息面板

引言：让数字信息"扎根"现实世界

在增强现实（AR）应用中，最核心的挑战之一是如何让虚拟内容稳定、持久地"附着"在真实物理空间中。传统的屏幕坐标系 UI 在空间计算时代已显乏力------用户希望看到的信息不是漂浮在眼前，而是固定在桌面、墙面或设备上，无论视角如何变化，都能保持一致的空间关系。

Rokid Max 等新一代 AR 眼镜凭借高精度 SLAM（即时定位与地图构建）和空间锚点（Spatial Anchor）能力，为这一需求提供了硬件基础。而 Rokid 推出的 JSAR（JavaScript Spatial Application Runtime） 框架，则让前端开发者无需深入图形学底层，即可快速构建具备空间感知能力的轻量化 AR 应用。

本文将带你从零开始，使用 JSAR + Rokid Max 开发一个可锚定在桌面的实时天气信息面板，重点演示如何利用 Rokid 的空间锚点 API 实现虚实融合，并分享调试中的关键技巧。

技术背景：空间锚点与 JSAR 运行时

什么是空间锚点？

空间锚点是 AR 系统在物理环境中创建的一个持久化参考点。通过 SLAM 算法，设备会识别环境特征（如角点、纹理），并将虚拟对象绑定到该位置。即使用户离开再返回，只要环境未发生显著变化，锚点仍能精确定位。

JSAR 如何简化开发？

JSAR 是 Rokid 为 Web 开发者打造的空间小程序运行时，基于 WebXR 标准 ，封装了 Babylon.js 渲染引擎，并扩展了 XSML（eXtended Spatial Markup Language） 语法用于描述 3D 场景。其核心优势在于：

使用熟悉的 JavaScript/TypeScript 开发
通过 <anchor> 标签声明空间锚点（实验性支持）
内置手势交互、平面检测等能力（需设备支持）

注：JSAR 对空间锚点的支持主要通过 spatialDocument.createAnchor() API 实现，详见 Rokid JSAR 官方文档（以实际 SDK 为准）。

实现步骤：构建桌面天气面板

1. 开发环境搭建

确保安装以下工具（版本要求见官方文档）：

VS Code ≥ 1.80.0
Node.js ≥ 18 LTS
JSAR DevTools 插件（VS Code 扩展市场搜索安装）

bash 复制代码

# 初始化项目
npm create jsar-widget@latest ar-weather-panel
cd ar-weather-panel
npm install

2. 声明空间锚点与 UI 元素（main.xsml）

xml 复制代码

<xsml version="1.0">
  <head>
    <title>AR Weather Panel</title>
    <script src="./lib/weather.ts"></script>
  </head>
  <space>
    <!-- 锚点容器：将整个面板绑定到检测到的水平面上 -->
    <anchor id="desk-anchor" type="horizontal-plane">
      <plane id="panel-bg" width="0.8" height="0.4">
        <material color="#1a1f2e" opacity="0.85" />
      </plane>
      <text id="city-text" content="Loading..." position="0, 0.1, -0.01"
            font-size="0.08" color="#ffffff" />
      <text id="temp-text" content="--°C" position="0, -0.05, -0.01"
            font-size="0.12" color="#4fc3f7" />
    </anchor>
  </space>
</xsml>

说明：<anchor type="horizontal-plane"> 表示该容器将自动吸附到检测到的水平面（如桌面）。这是 Rokid 对 WebXR 平面检测能力的封装。

3. 获取天气数据并更新 UI（lib/weather.ts）

ts 复制代码

// lib/weather.ts
import { spatialDocument } from '@rokid/jsar';

async function fetchWeather() {
  try {
    const res = await fetch('https://api.openweathermap.org/data/2.5/weather?q=Hangzhou&appid=YOUR_KEY&units=metric');
    const data = await res.json();
    
    // 更新文本内容（JSAR-DOM 操作）
    const cityText = spatialDocument.getElementById('city-text') as any;
    const tempText = spatialDocument.getElementById('temp-text') as any;
    
    if (cityText && tempText) {
      cityText.setAttribute('content', data.name);
      tempText.setAttribute('content', `${Math.round(data.main.temp)}°C`);
    }
  } catch (err) {
    console.error('Weather fetch failed:', err);
  }
}

// 页面加载完成后执行
spatialDocument.addEventListener('DOMContentLoaded', () => {
  fetchWeather();
  // 每30分钟更新一次
  setInterval(fetchWeather, 1800000);
});

4. 启用平面检测（package.json 配置）

在 package.json 中声明所需能力：

json 复制代码

{
  "name": "ar-weather-panel",
  "main": "main.xsml",
  "xrFeatures": {
    "planeDetection": true,
    "anchors": true
  }
}

调试技巧与问题解决

问题1：锚点无法稳定附着

现象：面板随头部移动漂移。
原因：环境纹理不足或光照过暗，SLAM 特征点稀疏。
解决方案：

在 spatialDocument 初始化时增加环境提示：
ts 复制代码
```
spatialDocument.requestPlaneDetection({ minPlaneArea: 0.2 });
```
引导用户将眼镜对准有纹理的桌面（如木纹、书本）。

问题2：真机预览黑屏

原因：未在 Rokid 设备上开启"开发者模式"或未授权 JSAR 运行权限。
解决：

在 Rokid Max 设置中开启"开发者选项"
通过 USB 连接电脑，在终端执行：
bash 复制代码
```
adb push dist/ /sdcard/JSAR/
```
在设备"空间应用"中手动加载 .idp 包

扩展思考：迈向智能空间助手

当前实现仅展示静态信息。结合大模型（LLM）可进一步升级：

语音查询天气：调用 Rokid 语音 SDK，用户说"今天杭州天气如何？"，触发 LLM 解析意图并调用 API。
上下文感知：根据锚点位置自动识别城市（如锚定在上海办公室桌面，则默认查询上海天气）。
多模态交互：注视面板 2 秒 + 捏合手势，展开空气质量、湿度等详情。

示例架构：Rokid 设备 → 本地 ASR → 云端 LLM → 动态生成 XSML 片段 → JSAR 渲染更新。

结语

通过 JSAR 与 Rokid Max 的空间计算能力，我们仅用百行代码就实现了具备环境感知的 AR 信息面板。这不仅验证了 Web 技术栈在空间计算时代的可行性，也为构建下一代"空间操作系统"中的轻量化应用提供了范式。

未来，随着 Rokid 对眼动追踪、多用户协同等能力的开放，JSAR 应用将能实现更自然的虚实交互------而这一切，正始于一个稳固的空间锚点。

参考资料

Rokid JSAR 官方开发指南：https://developer.rokid.com/jsar
JSAR GitHub 示例库：https://github.com/M-CreativeLab/jsar-gallery
WebXR 平面检测规范：https://immersive-web.github.io/real-world-geometry/plane-detection.html
Rokid Max 开发者设备文档：https://developer.rokid.com/devices/rokid-max