文章目录
- 一、JSAR 核心概念与 Rokid 适配基础
- 1.1 什么是 JSAR
- 1.2 JSAR 与 Rokid 设备的深度适配
- 1.3 核心技术组件
- 二、开发环境搭建（Rokid 官方标准流程）
- 2.1 环境依赖清单
- 2.2 分步安装指南
- 2.3 环境验证
- 三、JSAR 项目开发核心流程
- 3.1 项目初始化（两种官方方案）
- 3.2 项目核心结构解析
- 3.3 核心开发语法（XSML + JSAR-DOM）
- 3.4 场景预览与调试
- 四、项目实战-小猫
- 1. 小猫 XSML 文件结构解析
- 2. 小猫身体结构
- 3. 小猫面部特征
- 4. 小猫四肢和尾巴
- 5. 效果展示
降低 AR 开发门槛，让前端开发者快速构建空间化交互体验
一、JSAR 核心概念与 Rokid 适配基础
1.1 什么是 JSAR
JSAR（JavaScript Augmented Reality）是 Rokid 主导的空间小程序开发技术体系，本质为可嵌入物理空间的 Web 运行时。它支持开发者使用 JavaScript、XSML（空间标记语言）等 Web 技术栈，构建能与真实环境融合的沉浸式 AR 应用。
核心价值：大幅降低 AR 开发门槛，让前端开发者无需掌握底层图形学技术，即可快速实现空间化交互体验。
1.2 JSAR 与 Rokid 设备的深度适配
Rokid 作为 JSAR 技术的核心落地载体，从硬件到软件提供全链路支持：
- 硬件适配：兼容 Rokid Glasses 系列、Rokid Max 等主流 AR 头显，利用设备的高精度空间定位、手势识别与近眼显示能力，实现虚拟内容与真实空间的精准对齐。
- 跨设备拓展：依托 WebXR 标准，JSAR 应用可无缝运行于 Rokid、Pico、Apple Vision Pro 等多品牌 AR 设备，且支持 iPhone 等移动终端通过 WebXR Viewer 访问。
- 工具链集成：提供专属 JSAR DevTools 与真机调试方案，优化 Rokid 设备上的渲染性能与交互响应速度。
1.3 核心技术组件
| 组件 | 功能说明 |
|---|---|
| XSML | 空间标记语言，扩展 HTML 语法以描述 3D 空间结构，支持定义平面、模型等空间元素 |
| JSAR-DOM | 空间文档对象模型，基于 Babylon.js 实现，提供空间元素的交互与渲染能力 |
| JSAR DevTools | VS Code 插件，集成场景预览、代码补全、真机调试等核心开发功能 |
| WebXR 适配层 | 支持沉浸式 AR 模式切换，兼容 Rokid 设备的空间定位与姿态追踪 |
二、开发环境搭建（Rokid 官方标准流程）
2.1 环境依赖清单
| 依赖工具 | 版本要求 | 作用说明 |
|---|---|---|
| Visual Studio Code | ≥ 1.80.0 | 代码编辑与插件运行载体 |
| Node.js | ≥ 18.0.0 或最新 LTS 版本 | 依赖管理与项目构建 |
| JSAR DevTools | 最新稳定版 | 场景预览与调试核心工具 |
2.2 分步安装指南
步骤 1：安装基础工具
- Visual Studio Code：前往 VS Code 官网下载对应系统版本，建议安装中文语言包提升开发效率。
- Node.js：访问 Node.js 官网下载 LTS 版本，安装后通过终端验证：
node -v # 需显示 v18.0.0 及以上 npm -v # 配套 npm 版本通常 ≥ 8.0.0
步骤 2：安装 JSAR DevTools
提供两种官方安装方式，推荐优先使用商店安装：
- 方式一：VS Code 商店安装
打开 VS Code 拓展面板，搜索 JSAR DevTools（插件 ID：RokidMCreativeLab.vscode-jsar-devtools），点击安装即可。
- 方式二：VSIX 包离线安装
- 下载最新安装包：https://jsar.netlify.app/installer/vscode-jsar-devtools-latest.vsix
- 打开 VS Code，按下
Ctrl + Shift + P，输入Extensions: Install from VSIX...，选择下载的安装包完成安装。
2.3 环境验证
安装完成后，打开 VS Code 右下角状态栏，若显示 JSAR DevTools: Ready，则说明工具激活成功。
三、JSAR 项目开发核心流程
3.1 项目初始化（两种官方方案）
方案 1：Npm 命令快速创建
打开终端，执行初始化命令：
npm create jsar-widget@latest按照交互提示输入项目名称、描述等信息，工具会自动拉取官方模板 M-CreativeLab/template-for-jsar-widget。
进入项目目录，安装依赖：
cd your-project-name
npm install方案 2：GitHub Template 创建
- 访问官方模板仓库：
template-for-jsar-widget，点击 “Use this template” - 填写仓库名称，创建新的 GitHub 项目（推荐添加
jsar-widget主题标签，便于社区发现） - 克隆项目到本地并安装依赖
3.2 项目核心结构解析
package.json 关键配置：
{
"name": "jsar-widget-template",
"type": "module",
"scripts": {
"dev": "jsar-cli dev",
"build": "jsar-cli build"
},
"dependencies": {
"@rokid/jsar": "^0.2.0"
}
}3.3 核心开发语法（XSML + JSAR-DOM）
XSML 空间元素定义
XSML 扩展 HTML 语法，新增 <space> 标签描述 3D 空间，支持嵌套平面、模型等元素：
<xsml version="1.0"><head><title>JSAR Widget</title><link id="model" rel="mesh" type="octstream/glb" href="./model/welcome.glb" /><script src="./lib/main.ts"></script></head><space><mesh id="model" ref="model" selector="__root__" /></space>
</xsml>3.4 场景预览与调试
1. 本地场景预览
- 在 VS Code 中打开项目的
main.xsml文件 - 点击编辑器右上角的「场景视图」按钮（立体图形图标）
- 场景视图支持两种核心操作：
- 重置位置：将场景恢复到原点坐标
- 刷新：代码修改后自动/手动重新加载场景
2. WebXR 浏览器调试
- 安装 Chrome 插件：Immersive Web Emulator
- 上传项目到本地服务，通过以下 URL 访问：
http://localhost:3000/?mode=ar - 点击「Enter AR」按钮，即可在浏览器中模拟 Rokid 设备的 AR 沉浸式体验
3. Rokid 真机调试
- 确保开发机与 Rokid 设备处于同一局域网
- 在 JSAR DevTools 中选择「真机调试」，自动识别设备并部署应用
- 支持通过 Chrome DevTools 协议（CDP）进行断点调试与日志打印
四、项目实战-小猫
我来为您详细讲解如何创建小猫的 XSML 文件和对应的 JavaScript 逻辑：
1. 小猫 XSML 文件结构解析
main.xsml:
<?xml version="1.0" encoding="UTF-8"?><xsml version="1.0" xmlns="http://www.rokid.com/2019/xsml"><head><title>可爱小猫AR</title><meta name="engine" content="javascript" /><script src="./lib/cat-app.js" type="text/javascript"></script></head><space background-color="#87CEEB"><!-- 地面 --><planeposition="0 -2 0"width="10"height="10"rotation="-90 0 0"color="#7CFC00"/>XSML 基础结构讲解：
<xsml>: 根元素，定义文档类型和命名空间<head>: 头部，包含标题、元数据和脚本引用<space>: 3D空间容器，设置背景颜色<plane>: 创建平面作为地面，rotation="-90 0 0"使其水平放置
2. 小猫身体结构
<!-- 小猫身体 --><panel id="cat-body" position="0 0 -3" width="1.5" height="1" background-color="#FFB6C1" border-radius="0.5"><!-- 小猫头部 --><panel id="cat-head" position="0 0.8 0.1" width="1" height="1" background-color="#FFB6C1" border-radius="0.5"><!-- 左耳 --><panel id="left-ear" position="-0.3 0.4 0" width="0.3" height="0.4" background-color="#FF69B4" border-radius="0.15" rotation="0 0 -20"/><!-- 右耳 --><panel id="right-ear" position="0.3 0.4 0" width="0.3" height="0.4" background-color="#FF69B4" border-radius="0.15" rotation="0 0 20"/>Panel 元素详解：
<panel>: 创建矩形面板，通过组合形成小猫各部分position="x y z": 3D空间中的位置坐标width/height: 面板尺寸background-color: 填充颜色border-radius: 圆角半径，创建圆形效果rotation: 旋转角度，用于倾斜耳朵
3. 小猫面部特征
<!-- 左眼 --><panel id="left-eye" position="-0.2 0.1 0.1" width="0.15" height="0.2" background-color="#FFFFFF" border-radius="0.1"><panel position="0 0 0.05" width="0.08" height="0.08" background-color="#000000" border-radius="0.04"/></panel><!-- 右眼 --><panel id="right-eye" position="0.2 0.1 0.1" width="0.15" height="0.2" background-color="#FFFFFF" border-radius="0.1"><panel position="0 0 0.05" width="0.08" height="0.08" background-color="#000000" border-radius="0.04"/></panel><!-- 鼻子 --><panel id="nose" position="0 0 0.15" width="0.1" height="0.06" background-color="#FF69B4" border-radius="0.03"/><!-- 嘴巴 --><panel id="mouth" position="0 -0.1 0.1" width="0.2" height="0.02" background-color="#000000" border-radius="0.01"/><!-- 胡须 --><panel id="whisker1" position="-0.15 -0.05 0.1" width="0.2" height="0.01" background-color="#000000" rotation="0 0 10"/><panel id="whisker2" position="-0.15 -0.1 0.1" width="0.2" height="0.01" background-color="#000000" rotation="0 0 -10"/><panel id="whisker3" position="0.15 -0.05 0.1" width="0.2" height="0.01" background-color="#000000" rotation="0 0 -10"/><panel id="whisker4" position="0.15 -0.1 0.1" width="0.2" height="0.01" background-color="#000000" rotation="0 0 10"/></panel>嵌套结构：
- 眼睛是嵌套面板：白色大面板 + 黑色小面板作为瞳孔
- 胡须使用细长面板 + 旋转角度创建
- 每个元素都有唯一的 id 用于 JavaScript 控制
4. 小猫四肢和尾巴
<!-- 尾巴 --><panel id="tail" position="0.6 -0.3 0" width="0.8" height="0.08" background-color="#FF69B4" border-radius="0.04" rotation="0 0 30"/><!-- 左腿 --><panel id="left-leg" position="-0.3 -0.5 0" width="0.2" height="0.4" background-color="#FF69B4" border-radius="0.1"/><!-- 右腿 --><panel id="right-leg" position="0.3 -0.5 0" width="0.2" height="0.4" background-color="#FF69B4" border-radius="0.1"/></panel>5. 效果展示
您好，我是肥晨。
欢迎关注我获取前端学习资源，日常分享技术变革，生存法则；行业内幕，洞察先机。
