当前位置：首页 > news >正文

JSAR 空间小程序开发全指南：从环境搭建到跨场景应用落地

news 2025/10/14 6:48:13

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（低版本可能不兼容插件）。
下载地址：Visual Studio Code - Code Editing. Redefined
推荐插件：除后续安装的 JSAR DevTools 外，可额外安装“TypeScript 扩展”“Babylon.js Debug Tools”，提升编码和调试效率。

2. 安装 Node.js

要求：版本 ≥ 18.0.0（推荐 LTS 版本，稳定性更高）。
下载地址：Node.js — Run JavaScript Everywhere
验证安装：打开终端输入以下命令，能正常显示版本号即成功：

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

环境变量。

PS C:\Users\28453> npm init @yodaos-jsar/widget my-first-jsar-app 
npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。
所在位置 行:1 字符: 1
+ CategoryInfo          : ObjectNotFound: (npm:String) [ ], CommandNotFoundException+ FullyQualifiedErrorId : CommandNotFoundException

安装 Node.js
- 访问 Node.js 官网：https://nodejs.org/
- 下载 LTS 版本（推荐，稳定性更高），根据你的系统（Windows）选择 64 位或 32 位安装包。
- 运行安装包，勾选 “Add to PATH” 选项（关键步骤，自动配置环境变量），然后按默认步骤完成安装。

如果忘记了勾选，需要在系统环境变量中进行手动配置。

js安装完成之后，检查npm和node

按终端提示输入项目描述、作者等信息（也可直接按回车使用默认值），工具会自动下载模板并生成 package.json。
进入项目目录并安装依赖：

cd my-first-jsar-app # 进入项目文件夹 npm install # 安装类型定义等依赖，支持代码补全和类型检查

3. 项目核心结构解析

初始化后的项目结构清晰，核心文件如下（以 NPM 创建的项目为例）：

my-first-jsar-app/
├── lib/                # 业务逻辑文件夹
│   └── main.ts         # 主脚本文件（写交互逻辑、3D 场景控制）
├── model/              # 3D 模型文件夹（存放 glb 等格式模型）
├── main.xsml           # 主场景配置文件（定义空间结构、引用资源）
├── package.json        # 项目配置（名称、版本、依赖等）
├── icon.png            # 应用图标（在系统中显示的图标）
└── tsconfig.json       # TypeScript 配置文件

其中，main.xsml 是空间场景的“入口”，类似前端项目的 index.html，示例代码如下：

<xsml version="1.0"><head><title>我的第一个 JSAR 应用</title>  <!-- 应用名称 --><script src="./lib/main.ts"></script>  <!-- 引入业务脚本 --><link id="cube-model" rel="mesh" type="octstream/glb" href="./model/cube.glb" />  <!-- 引用 3D 模型 --></head><space><mesh id="cube" ref="cube-model" selector="_root_" />  <!-- 在空间中加载模型 --></space>
</xsml>

四、项目运行与调试：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（定义场景）

<xsml version="1.0"><head><title>3D 交互时钟</title><script src="./lib/main.ts"></script><!-- 引用两个时钟模型 --><link id="clock1" rel="mesh" type="octstream/glb" href="./model/clock-style1.glb" /><link id="clock2" rel="mesh" type="octstream/glb" href="./model/clock-style2.glb" /></head><space><!-- 默认加载第一个时钟模型，设置 ID 用于脚本控制 --><mesh id="active-clock" ref="clock1" selector="_root_" /></space>
</xsml>

步骤 2：编写 main.ts（实现交互逻辑）

// 等待 JSAR 环境就绪
document.addEventListener('JSARReady', () => {// 获取当前显示的时钟模型const activeClock = document.getElementById('active-clock') as Element;// 记录当前使用的模型 IDlet currentModelId = 'clock1';// 给时钟模型添加点击事件activeClock.addEventListener('click', () => {// 切换模型 IDcurrentModelId = currentModelId === 'clock1' ? 'clock2' : 'clock1';// 更新模型引用，实现样式切换activeClock.setAttribute('ref', currentModelId);});
});

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能不断更新优化，带来更多的惊喜！

查看全文

http://www.dtcms.com/a/477570.html