一、JSAR 简介与开发环境搭建
1.1 什么是 JSAR？
JSAR（JavaScript Augmented Reality）是 Rokid 推出的空间小程序开发框架，允许开发者使用 Web 技术栈（JavaScript/TypeScript）构建可嵌入物理空间的 AR 应用。其核心优势在于：
- 低门槛：无需学习 Unity 或 Unreal Engine，前端开发者可直接上手
- 强隔离：空间组件独立运行，互不干扰
- 跨平台：支持 Rokid AR 眼镜、手机等多设备
1.2 开发环境准备
必备工具（版本要求严格）：
- Visual Studio Code ≥ 1.80.0
- Node.js ≥ 18.0.0（建议使用 18.12.1 LTS）
- JSAR DevTools 插件（VS Code 商店搜索安装）
环境搭建步骤：
# 验证 Node.js 安装
node -v # 需显示 ≥ v18.x.x
npm -v # 配套版本 ≥ 8.0.0
# 安装 JSAR 脚手架
npm init @yodaos-jsar/widget@latest my-weather-widget
cd my-weather-widget
npm install # 安装类型定义与依赖
二、JSAR 项目结构与核心概念
2.1 项目文件解析
my-weather-widget/
├── main.xsml # 空间布局定义（类似 HTML）
├── package.json # 项目配置
├── lib/main.ts # TypeScript 逻辑
└── model/ # 3D 模型资源
关键文件详解：
- main.xsml：使用空间标记语言定义 3D 场景结构
<xsml version="1.0">
<head>
<title>天气小摆件</title>
<script src="./lib/main.ts"></script>
</head>
<space><!-- 3D 场景容器 --></space>
</xsml>
- package.json：需指定 xsml 入口文件
{
"main": "main.xsml",
"dependencies": {
"@rokid/jsar": "^0.2.0"
}
}
2.2 核心概念图解
| 概念 | 说明 | 类比 Web 开发 |
|---|---|---|
| 可嵌入空间 | 划定的 3D 子空间区域 | iframe 容器 |
| XSML | 空间标记语言，定义 3D 元素布局 | HTML |
| JSAR-DOM | 空间文档对象模型，操作 3D 元素 | DOM API |
| Babylon.js | 3D 渲染引擎，处理图形渲染与动画 | CSS + Canvas |
三、实战开发：3D 天气小摆件
3.1 基础场景搭建
在 lib/main.ts 中创建 Babylon.js 场景：
// 获取 JSAR 全局场景对象
const scene = spaceDocument.scene as BABYLON.Scene;
// 添加环境光
const light = new BABYLON.HemisphericLight("light",
new BABYLON.Vector3(0, 1, 0),
scene
);
light.intensity = 0.7;
// 创建地面
const ground = BABYLON.MeshBuilder.CreateGround("ground",
{
width: 10, height: 10 },
scene
);
const groundMat = new BABYLON.StandardMaterial("groundMat", scene);
groundMat.diffuseColor = new BABYLON.Color3(0.8, 0.8, 0.8);
ground.material = groundMat;
3.2 集成和风天气 API
步骤 1：获取 API Key
- 访问 和风天气开发者平台 注册账号
- 创建应用获取 API Key（免费版每日可调用 1000 次）
步骤 2：编写 API 调用函数
async function fetchWeather(city: string): Promise<any> {
const apiKey = "YOUR_API_KEY";
// 替换为实际密钥
const cityUrl = `https://geoapi.qweather.com/v2/city/lookup?location=${
city}&key=${
apiKey}`;
try {
// 获取城市 ID
const cityRes = await fetch(cityUrl);
const cityData = await cityRes.json();
const cityId = cityData.location[0].id;
// 获取天气数据
const weatherUrl = `https://devapi.qweather.com/v7/weather/now?location=${
cityId}&key=${
apiKey}`;
const weatherRes = await fetch(weatherUrl);
return await weatherRes.json();
} catch (error) {
console.error("天气 API 调用失败:", error);
return null;
}
}
3.3 3D 天气可视化实现
创建动态更新的天气球体：
async function createWeatherSphere() {
// 创建球体作为天气指示器
const sphere = BABYLON.MeshBuilder.CreateSphere("weatherSphere",
{
diameter: 2 },
scene
);
sphere.position.y = 1;
// 创建材质
const sphereMat = new BABYLON.StandardMaterial("sphereMat", scene);
sphere.material = sphereMat;
// 更新天气数据
setInterval(async () => {
const weatherData = await fetchWeather("北京");
if (weatherData && weatherData.code === "200") {
const temp = weatherData.now.temp;
const text = weatherData.now.text;
// 根据天气状况改变球体颜色
switch(text) {
case "晴":
sphereMat.diffuseColor = new BABYLON.Color3(1, 0.8, 0); // 晴天-黄色
break;
case "雨":
sphereMat.diffuseColor = new BABYLON.Color3(0.3, 0.5, 1); // 雨天-蓝色
break;
case "阴":
sphereMat.diffuseColor = new BABYLON.Color3(0.6, 0.6, 0.6); // 阴天-灰色
break;
}
console.log(`当前温度: ${
temp}℃, 天气: ${
text}`);
}
}, 60000); // 每分钟更新一次
return sphere;
}
// 初始化天气球体
createWeatherSphere();
四、调试与打包发布
4.1 本地调试
方法 1：VS Code 预览
- 打开 main.xsml 文件
- 点击右上角 "场景视图" 按钮启动预览
- 使用 WASD 键控制视角，鼠标滚轮缩放
方法 2：浏览器测试
# 安装静态服务器
npm install -g serve
serve -p 8080 --cors
# 在 JSAR Playground 中打开
https://jsar.netlify.app/playground?url=http://localhost:8080/main.xsml
4.2 打包发布
# 构建项目
npm run build
# 生成的包位于 dist/ 目录
# 可通过 Rokid 开发者平台上传至 AR 应用商店
五、进阶技巧与注意事项
5.1 性能优化建议
- 模型轻量化：3D 模型面数控制在 1000 以内
- 减少绘制调用：合并静态模型，共享材质
- 按需加载：非关键资源使用懒加载模式
5.2 常见问题排查
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 场景无渲染 | VS Code 扩展未激活 | 重启 VS Code 或重装 JSAR DevTools |
| API 调用失败 | 跨域问题 | 使用 Rokid 设备测试或配置代理 |
| 模型不显示 | GLB 文件路径错误 | 检查 xsml 中 link 标签的 href 属性 |
5.3 创新拓展方向
- 多设备同步：结合 WebSocket 实现多 AR 眼镜间数据同步
- 语音交互：集成 Rokid 语音 SDK 实现语音控制天气查询
- 数据可视化：展示未来 7 天天气预报的 3D 时间轴
六、总结
本教程通过开发一个实时天气小摆件，介绍了 JSAR 开发的完整流程。从环境搭建到 API 集成，再到 3D 可视化实现，我们展示了如何将 Web 开发经验迁移到 AR 领域。JSAR 技术正在快速发展，建议持续关注 Rokid 开发者论坛 获取最新更新。
希望这个教程能帮助你迈出空间开发的第一步，期待看到更多创意十足的 JSAR 应用！
