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

前言

随着 AR 技术在消费级场景的普及，开发者对'低门槛、高兼容'AR 开发工具需求愈发迫切。传统 AR 开发往往依赖专属引擎或复杂语法，导致 Web 开发者难以快速切入。Rokid 推出的 JSAR 技术打破了这一壁垒：以'可嵌入空间的 Web 运行时'为核心，让开发者无需学习新的开发范式，仅用 JavaScript/TypeScript 等熟悉的 Web 技术栈，就能快速开发出支持 3D 物体、2D 界面的空间小程序。

本文围绕 JSAR 技术展开实战指南：从基础的开发环境搭建到核心特性原理解析，再到地球项目、超级马里奥复刻、碰撞检测、动画缓动等场景的实战演练，最终以'3D 时钟'为创意案例，深入拆解 JSAR 项目的文件结构、逻辑实现与空间布局关联。

Rokid JSAR 介绍

JSAR 是'技术转换器'，不用学新东西，用熟悉的 JavaScript、TypeScript 这些 Web 技术，就能做能放进特定空间的小程序，还能在场景里划块区域放 3D 模型、2D 界面，写的代码跟在网页里一样能跑。

可嵌入空间：是指在当前场景中通过定义长宽高划定一块子空间给一个单独的应用程序使用，空间组件可以是一个 3D 物体，也可以是一个 2D 界面，当然也可以是带 GUI 的 3D 物体。
Web 运行时：代表 JSAR 可以运行基于 Web APIs 实现的 JavaScript / TypeScript 代码，同时也可以运行 WebAssembly。

Rokid JSAR 开发环境搭建：基础地球项目开发

开发工具安装

VS Code 安装插件 JSAR Devtools 和 glTF Tools
- JSAR Devtools：辅助 JSAR 项目开发，提供 AR 场景调试、状态查看及性能优化等功能，提升开发效率。
- glTF Tools：处理 glTF/GLB 格式 3D 模型，支持在开发环境中预览和简单编辑，方便模型使用。

项目资源准备

icon.png 准备
通过 glTF 插件预览效果
main.xsml JSAR 项目中用于定义界面结构、资源关联和 3D 场景布局的描述文件，连接项目资源与场景元素，搭建起应用的基础框架。

本地服务器搭建

Web 浏览器运行安装 serve 工具，使用 serve 工具启动静态服务器。
浏览器地址如下显示则表示成功启动服务器。
JSAR 演示场展示：https://jsar.netlify.app/playground?url=填写本地服务器地址

JSAR 实战项目演练：从基础到创意

交互功能实践：碰撞检测实现

动效设计实践：动画缓动实现

创意开发：3D 时钟项目全解析

文件路径 / 名称	文件角色定位	核心功能说明
`lib/clock.ts`	核心逻辑文件	封装坐标计算、时间获取、图形绘制函数，通过 `startClock` 实现模拟 + 数字时钟绘制
`lib/main.ts`	项目入口文件	获取画布、初始化时钟，每秒更新绘制与画布，实现动态走时
`package-lock.json`	依赖配置文件	管理 `@yodaos-jsar/types` 等依赖及版本，保障开发环境稳定
`main.xsml`	3D 页面配置文件	定义画布立方体样式、引入脚本、创建 3D 载体，关联逻辑与空间布局

clock.ts 封装了时钟绘制的核心逻辑，通过一系列函数如计算坐标的 x2、y2，获取时间的 getTime，绘制圆形、线条、文字的 drawCircle、drawLine、drawText 等，最终在 startClock 函数里实现了模拟时钟（含时针、分针、秒针及表盘）与数字时钟的绘制。
main.ts 则作为项目入口，获取画布并借助 startClock 初始化时钟绘制，再通过 setInterval 每秒钟调用一次 startClock 并更新画布，从而让时钟实现动态走时效果。
package-lock.json 配置 JSAR 3D 时钟项目的依赖树。
main.xsml 项目页面配置核心，通过样式定义 #canvas 立方体的缩放与旋转，引入 main.ts 脚本，并以 <cube> 为载体，构建出 3D 时钟在空间展示的基础结构，关联样式与核心逻辑。

总结

Rokid JSAR 最核心的价值就是帮 Web 开发者'零门槛'切入 AR 开发，不用学新引擎、开发流程清晰、项目架构可复用，不管是练手基础功能，还是做 3D 时钟这类创意项目都能高效落地，真正实现 Web 技术和 AR 空间场景互通。

技术门槛低：JSAR 核心是复用 Web 技术，无需学专属 AR 引擎语法，Web 开发者用 JavaScript/TypeScript、Web APIs 即可开发空间应用，且 main.xsml 场景定义、Canvas 纹理绘制等操作熟悉，大幅降低跨领域学习成本。
开发流程清晰可复现：地球项目从工具配置、资源准备、服务器搭建到演示场验证，每步有具体操作与反馈，能快速搭环境；后续项目还提供场景模板，减少功能开发试错成本。
项目架构可复用：3D 时钟项目的文件拆解逻辑、入口、布局等分离提供通用结构参考，契合模块化思维，可直接复用到其他 JSAR 项目。