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

Rokid JSAR 技术开发全指南：基于 Web 技术栈的 AR 开发实战 - 实践

news 2026/3/26 17:46:13

在这里插入图片描述

文章目录

      • 一、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 DevToolsVS Code 插件，集成场景预览、代码补全、真机调试等核心开发功能
WebXR 适配层支持沉浸式 AR 模式切换，兼容 Rokid 设备的空间定位与姿态追踪

二、开发环境搭建（Rokid 官方标准流程）

2.1 环境依赖清单
依赖工具版本要求作用说明
Visual Studio Code≥ 1.80.0代码编辑与插件运行载体
Node.js≥ 18.0.0 或最新 LTS 版本依赖管理与项目构建
JSAR DevTools最新稳定版场景预览与调试核心工具
2.2 分步安装指南

步骤 1：安装基础工具

  1. Visual Studio Code：前往 VS Code 官网下载对应系统版本，建议安装中文语言包提升开发效率。
  2. 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 包离线安装
    1. 下载最新安装包：https://jsar.netlify.app/installer/vscode-jsar-devtools-latest.vsix
    2. 打开 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 创建

  1. 访问官方模板仓库：template-for-jsar-widget，点击 “Use this template”
  2. 填写仓库名称，创建新的 GitHub 项目（推荐添加 jsar-widget 主题标签，便于社区发现）
  3. 克隆项目到本地并安装依赖
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 浏览器调试

  1. 安装 Chrome 插件：Immersive Web Emulator
  2. 上传项目到本地服务，通过以下 URL 访问：
    http://localhost:3000/?mode=ar
  3. 点击「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. 效果展示

您好，我是肥晨。
欢迎关注我获取前端学习资源，日常分享技术变革，生存法则；行业内幕，洞察先机。

http://www.jsqmd.com/news/34888/

相关文章：

  • 2025 年 11 月东莞环评公司推荐排行榜，环评手续，环评报告，环评验收，专业高效环评服务厂家推荐
  • 36 个 AI Demo 任选 6 个！JBoltAI 框架助力 Java 团队快速复刻企业级 AI 应用
  • 2025 年 11 月红木家具厂家推荐排行榜，交趾黄檀/小叶紫檀/巴里黄檀/缅甸花梨/阔叶黄檀，明清古典榫卯工艺高端定制全屋整装，白胚烘干源头工厂精选
  • 2025年电预热厂家权威推荐榜：管道电预热/热力管道电预热工程/热力管道电预热设备专业供应商精选
  • 面试问题总结
  • Java 开发者福音！JBoltAI 框架让 AI 应用开发效率翻倍
  • JBoltAI 的 Function Call + MCP 集成
  • 甲烷检测仪/氧气检测仪/二氧化碳检测仪/四合一气体检测仪/可燃气体报警器等气体检测仪器生产厂家有哪些？知名品牌厂家推荐
  • 如何去宣传你的游戏
  • 不用自己封装大模型！JBoltAI 框架为 Java AI 开发提供稳定 AI 应用支撑
  • 财务报销 + 智慧采购！JBoltAI 框架为 Java 企业打造场景化 AI 应用窗口
  • 向量库 + Embedding 模型！JBoltAI 框架帮 Java 团队搭建高精度 AI 应用知识库
  • 动态加载so库
  • AI元人文：价值权衡范式——环境、价值体系与规则体系的辩证统一
  • 2025年高活性氢氧化钙厂家权威推荐榜单：熟石灰/高比表氢氧化钙/氢氧化钙颗粒源头厂家精选
  • 行业方案 + VIP 支持！JBoltAI 框架全程帮 Java 团队搞定 AI 应用落地难题
  • 老Java系统想加AI能力？JBoltAI框架帮改造，AI应用无缝衔接旧系统
  • 嵌入式,liunx内核开发编写笔记 谢双元2023-2024成长历程
  • 《ESP32-S3使用指南—IDF版 V1.6》第四十六章 SD卡模拟U盘实验
  • 2025年广州ai广告服务权威推荐榜单：广告运营/互联网广告/代运营服务精选
  • 省4-6个月研发成本！Java AI开发选JBoltAI框架，企业级AI应用极速上线
  • 2025年打包箱房制造企业权威推荐榜单：隔离房/创意集装箱/彩钢房源头厂家精选
  • 2025年知名的冷拉型钢杭州老房装修
  • 2025年管母线厂家综合实力排行榜：全绝缘铜管母线/管型母线/全屏蔽绝缘铜管母线领先厂家精选
  • 2025年6月deepseek排名优化跨平台能力推荐排行榜
  • 2025年M14连接器插座厂家权威推荐榜单：M14焊线式插座/M14成型式针型插头/M14成型连接器插头源头厂家精选
  • 2025年6月生成式引擎优化推荐榜揭晓五强竞逐AI搜索赛道
  • 2025年11月股权融资律师推荐风向：跨域经验成关键
  • 英语_阅读_Robotic_待读
  • 终身授权 + 100% 源码！Java AI 开发选 JBoltAI 框架，AI 应用商用无后顾之忧