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

原创

肥晨

发布于 2025-10-10 14:55:44

6040

降低 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 商店安装undefined打开 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 创建

访问官方模板仓库：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">
    <!-- 地面 -->
    <plane 
      position="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. 效果展示

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

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

ar 云服务

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

ar 云服务

登录后参与评论

0 条评论

热度