JSAR 空间应用开发新人指南：从环境搭建到跨场景应用落地
前言
在空间计算飞速发展的当下，Web开发者想要切入AR应用开发往往面临“技术栈不匹配”“硬件依赖重”等难题。而JSAR作为可嵌入空间的Web运行时，以JavaScript/TypeScript为核心，让熟悉Web技术的开发者不需要学习全新引擎，就能快速开发出可交互的空间小程序。本文将从JSAR新人小白开发角度出发，记录JSAR应用开发的操作流程，从环境配置到项目部署，再到实战案例，帮助我们学习JSAR空间应用开发。
一、认识JSAR
1. 什么是 JSAR
JSAR 是可嵌入空间的 Web 运行时，核心能力是让开发者用 Web 技术（JavaScript/TypeScript、HTML 思想的 XSML）开发能嵌入到空间场景中的小程序。它就像空间版的前端框架，把 3D 场景开发、空间交互等复杂能力封装成 Web 开发者熟悉的 API，降低空间应用开发门槛。
2. 为什么选 JSAR
- 技术友好：支持 Web-standard APIs 和 TypeScript，Web 开发者可无缝迁移技能。
- 场景灵活：兼容 Babylon.js 做 3D 场景开发，支持在 VS Code 内完成全流程开发，还能嵌入 Unity 场景运行。
- 安全高效：保证空间组件隔离运行，互不干扰；优化离线体验和性能，打破“Web 技术做 3D 性能差”的刻板印象。
3. JSAR应用开发需求
推荐场景 | 案例 |
|---|---|
轻量空间摆件 / 工具类应用 | ① 3D 桌面宠物（如会动的虚拟猫咪、机器人） ② 实时数据看板（如股票行情、天气信息的 3D 可视化展示） ③ 小型辅助工具（如空间计算器、AR 便签纸、3D 日历） |
2D+3D 结合的混合交互场景 | ① AR 商品展示（如 3D 家具模型 + 2D 规格选择按钮，点击切换家具颜色 / 尺寸） ② 空间地图助手（2D 导航菜单 + 3D 场景地图，点击菜单跳转至对应空间位置） ③ 简易教学工具（如 3D 人体模型 + 2D 器官名称标签，点击标签高亮对应器官） |
YodaOS-Master 系统下的嵌入式应用 | ① AR 桌面扩展工具（如在 YodaOS 桌面中嵌入 3D 地球仪，点击查看各国信息） ② 系统辅助组件（如 YodaOS 场景中的语音控制面板、快捷设置 3D 入口） |
二、环境搭建配置
JSAR 开发依赖 3 个核心工具：Visual Studio Code、Node.js、JSAR DevTools，全程“傻瓜式操作”，新手小白也能 10 分钟内搞定。
1. 安装 Visual Studio Code
- 要求：版本 ≥ 1.80.0（低版本可能不兼容插件）。
- 推荐插件：除后续安装的 JSAR DevTools 外，可额外安装“TypeScript 扩展”“Babylon.js Debug Tools”，提升编码和调试效率。
2. 安装 Node.js
- 要求：版本 ≥ 18.0.0（推荐 LTS 版本，稳定性更高）。
- 验证安装：打开终端输入以下命令，能正常显示版本号即成功：
node -v # 示例输出：v20.10.0 npm -v # 示例输出：10.2.3
3. 安装 JSAR DevTools（核心插件）
提供两种安装方式，任选其一即可：
VS Code安装
- 打开 VS Code，点击左侧“扩展”图标（或按 Ctrl+Shift+X）。
- 在搜索框输入“JSAR DevTools”，找到由“Rokid MCreativeLab”开发的插件。
- 点击“安装”，等待插件自动下载并启用（右下角会提示“安装成功”）。
安装成功：
三、NPM 本地项目创建
JSAR 支持本地创建和 GitHub 模板创建，满足个人开发和团队协作不同需求。对于个人开发者来说我选择NPM命令本地创建。
NPM 命令本地创建（推荐个人开发）
通过一行命令即可拉取模板并初始化项目，步骤如下：
- 打开 VS Code 终端（Ctrl+`），输入以下命令创建项目：
npm init @yodaos-jsar/widget my-first-jsar-app # my-first-jsar-app 是项目名，可自定义
- 如果执行之后出现以下报错信息的，说明缺少Node.js 文件，需要下载配置node.js
- 环境变量。
- 安装 Node.js
- 访问 Node.js 官网
- 下载 LTS 版本（推荐，稳定性更高），根据你的系统（Windows）选择 64 位或 32 位安装包。
- 运行安装包，勾选 “Add to PATH” 选项（关键步骤，自动配置环境变量），然后按默认步骤完成安装。
- 如果忘记了勾选，需要在系统环境变量中进行手动配置。
js安装完成之后，检查npm和node
- 按终端提示输入项目描述、作者等信息（也可直接按回车使用默认值），工具会自动下载模板并生成 package.json。
- 进入项目目录并安装依赖：
cd my-first-jsar-app # 进入项目文件夹 npm install # 安装类型定义等依赖，支持代码补全和类型检查
3. 项目核心结构解析
初始化后的项目结构清晰，核心文件如下（以 NPM 创建的项目为例）：
其中，main.xsml 是空间场景的“入口”，类似前端项目的 index.html，示例代码如下：
四、项目运行与调试：3 种方式覆盖不同场景
JSAR 支持在 VS Code、Web 浏览器、Rokid AR 设备中运行项目，我们可以根据开发阶段选择合适的方式。我这里选择的是vs Code内运行。
VS Code 内运行
适合编写代码时实时预览效果，步骤如下：
- 在 VS Code 中打开项目的
main.xsml文件。 - 选中
main.xsml的标签页，右上角会出现“打开场景视图”按钮（类似眼睛图标），点击该按钮。 - 此时会弹出“Scene View”窗口，自动加载场景中的 3D 模型和交互逻辑。
- 如需重置模型位置，点击场景视图中的“重置”按钮（回到原点）。
- 修改代码后，场景视图会自动刷新，无需手动重启服务。
五、项目打包与发布：生成可部署的 .idp 文件
开发调试完成后，需将项目打包成 JSAR 专用的 .idp 格式，用于发布到应用市场或真机部署。
1. 打包步骤
- 在 VS Code 中右键点击项目文件夹的空白处，选择“JSAR: Package”。
- 工具会自动压缩项目资源（模型、脚本、图标等），生成
- 注意：当前 JSAR 要求打包后的文件小于 10MB，若超过会提示失败。
- 解决方案：用 gltf-transform 工具压缩 3D 模型，或删除冗余资源。
.idp 是 JSAR 的专属打包格式，全称“Interactive Digital Product”（交互式数字产品），本质是一个压缩包，包含应用运行所需的所有资源（模型、脚本、配置文件等）。它的核心优势是“跨场景复用”——同一个 .idp 文件，可嵌入到不同的空间场景中运行，无需重复开发。
六、开发实践：开发一个可交互的 3D 时钟小程序
通过一个简单案例，来理解 JSAR 应用的开发逻辑，实现“点击时钟切换样式”的交互效果。
1. 准备工作
- 3D 模型：准备两个不同样式的时钟模型（glb 格式），放入项目的
model/文件夹，命名为clock-style1.glb和clock-style2.glb。 
- 核心需求：加载默认时钟模型，点击模型时切换为另一种样式。
2. 编写代码
步骤 1：修改 main.xsml（定义场景）
步骤 2：编写 main.ts（实现交互逻辑）
3. 运行与验证
- 按前文“VS Code 内运行”的方式打开场景视图，能看到默认的时钟模型。
- 点击模型，会立即切换为另一种样式，再次点击则切换回来，交互逻辑生效。
- 打包项目：右键选择“JSAR: Package”，生成 .idp 文件后，可安装到 AR 设备上体验真实空间中的点击交互。由于刚学习，没有结合硬件设备使用，感兴趣的大家可以自行去体验
七、使用体验总结与建议
1. 新手友好的核心优势
- Web 开发者无需学习 Unity、Unreal 等引擎，用 JavaScript/TypeScript 就能开发 3D 空间应用。
- 代码补全、实时预览，JSAR DevTools 覆盖全开发流程，减少“配置折腾”时间。
2. 建议
- 3D 场景深化：学习 Babylon.js 与 JSAR 结合，实现更复杂的场景（如光照、动画、物理碰撞）。
- 多模态交互：集成手势、语音控制（需配合 YodaOS-Master 系统 API），提升用户体验。
- 跨设备适配：利用 JSAR 的多平台支持，开发的同时能兼容 AR 眼镜、PC 浏览器的应用。
总结
通过实践使用，JSAR 对开发者来说，它让我们的开发变得方便许多，也能很快速上手，能让我们体验到进行空间应用的开发，不需要重构技术栈，就能用熟悉的工具和语言，将可以开发出一个可交互的 3D 空间小程序。如果感兴趣的开发者们可以尝试开发使用，上手试一试，会发现不一样的惊喜。期待更多开发者用 JSAR 打造出丰富的空间应用，共同完善空间计算生态！也期待JSAR能不断更新优化，带来更多的惊喜！
