亮风台 HRS 预览小程序插件

详细说明

本插件可用来在小程序端实现多锚点场景数据HRS DATA的渲染
web管理端通过以2D图片创建锚点入口，结合HiAR Studio工具进行
空间布局和AR资源编辑，生成用于描述空间场景数据的HRS DATA。
插件支持两种预览方式预览HRS：页面预览和组件预览

功能形式	说明
预览页面	使用者可直接指定空间id，和HRS数据即可预览扫描图片锚点预览空间
预览组件	使用者可使用插件中提供的组件进行功能开发 1. 无需3D开发技能(会小程序开发即可)； 2. 支持图片、视频、glb/gltf模型素材

注意：微信版本>=8.0.14，同时小程序基础库>=2.20.0才支持Slam效果

使用前准备

1、 Toolkit 编辑器支持 2D 图片锚点编辑虚景

添加插件

在使用插件前，首先要在小程序管理后台的“设置-第三方服务-插件管理”中添加插件。开发者可登录小程序管理后台，通过 appid [] 查找插件并添加。

引入插件代码包

使用插件前，使用者要在 app.json 中声明需要使用的插件，例如：

代码示例：

{
  ...
  "plugins": {
    "hi-player": {
      "provider": "wxc74c2f70d72c8edd",
      "version": "1.0.0"
    }
  },
  "lazyCodeLoading" : "requiredComponents"
  ...
}

通过页面预览HRS

页面的使用

页面路径为：plugin://hi-player/preview

只需使用标签

<navigator url="plugin://hi-player/preview?hrsData={...}">点击打开预览页面</navigator>

或执行js接口,通过url传参

注意：此时的hrsData为字符串，因为object会被转换为[object Object]

wx.navigateTo({ url: 'plugin://hi-player/preview?hrsData={xxx}' });

或执行js接口，通过channel传参

可以用channel方式实现动态更新hrs数据

wx.navigateTo({
  url: 'plugin://hi-player/preview',
  success: (res) => {
    // hrsData为json数据或json字符串或null
    res.eventChannel.emit('updateHrs', {hrsData})
  }
})

页面参数

参数名称	格式约束	说明	备注
hrsData	json或json字符串或null	空间的HRS数据	接入方小程序接入开放平台，调用 Space Core 服务器提供的接口获取空间数据和 HRS 数据

通过组件预览HRS

组件定义的properties参数同页面参数，组件会observers其变更并实时渲染

使用组件的页面配置

{
  ...
  "usingComponents": {
    "hi-player": "plugin://hi-player/hi-player"
  },
  "disableScroll": true,
  ...
}

使用组件的wxml示例

<view>
  <hi-player
    bindready="handleReady"
    disable-scroll
    id="scene"
    width="{{width}}"
    height="{{height}}"
    render-width="{{renderWidth}}"
    render-height="{{renderHeight}}"
    hrsData="{{hrsData}}">
  </hi-player>
</view>

事件监听

事件类型	参数	作用
ready	xr-frame中scene的ready事件参数的`event.detail`	scene准备完成
ar-ready	xr-frame中scene的ar-ready事件参数的`event.detail`	ar准备完成
markers-load-start	无	识别图资源开始加载
markers-load-progress	`{progress: 整数0-99, assets:Record<assetId,Gltf	Texture
markers-load-end	`{progress: 100, assets:Record<assetId,Gltf	Texture
assets-load-start	`{anchorId: string}`	相关锚点的资源开始加载
assets-load-progress	`{anchorId:string, progress: 整数0-99, assets:Record<assetId,Gltf	Texture
assets-load-end	`{anchorId:string, progress: 100, assets:Record<assetId,Gltf	Texture
click	`{backendId:string}`	单击虚拟物体
dbclick	`{backendId:string}`	双击虚拟物体
ar-tracker-state	`{anchorId: string,detected:boolean,state:number,errorMessage:string}`	Tracker状态改变
ar-tick	`{value: number(毫秒数)}`	一帧驱动开始
ar-pause	无	场景暂停，一般是是压后台
ar-resume	无	场景恢复，一般是从后台唤醒
anim-stop	同xr-frame的anim-stop事件的参数	gltf动画播放结束

插件接口功能

导入插件

interface HiPlayerPluginExports {
  /**
   * 通过hrsObjectId获取元素(`Element`)的`Transform`组件，可以操作显示/隐藏、 图层属性
   * 可用时机: 
   */
  getTransform(id: string): Transform|null
  /**
   * 通过hrsObjectId获取元素(`Element`)的`Animator`组件, 用于动画控制
   * 可用时机: 监听到 `assets-load-end` 之后
   */
  getAnimator(id: string): Animator | null
  /**
   * 通过hrsObjectId获取元素(`Element`)的`VideoTexture`资源, 用于控制视频的播放/暂停
   * 可用时机: 监听到 `assets-load-end` 之后
   */
  getVideo(id: string): VideoTexture | null
  /**
   * 获取Effect
   */
  getEffect(effectId: string): Effect | null
  /**
   * 通过资源类型和hrsobjectId获取资源
   * 可用时机: 监听到 `markers-load-end` 之后可获取到锚点的识别图资源(texture)
   *          监听到 `assets-load-end` 之后可获取到相关锚点下的虚景对象的资源(trxture, video-texture, gltf)
   */
  getAsset<T extends keyof IAssetClass, R = IAssetClass[T]>(assetType: T, id: string): R|null
  /**
   * 通过锚点id获取tracker
   * 可用时机: 监听到 `markers-load-end` 事件 之后
   */
  findTracker(anchorId: string): XRARTracker | null
  /**
   * 通过hrsObjectId获取元素(`Element`),用于基于当前节点/组件的操作
   * 通过元素(`Element`)可以操作其`Component`组合、访问父子级等
   * 可用时机: 监听到 `assets-load-end` 之后
   */
  findElement(id: string): XRElement | null
  /**
   * 获取 xr-frame的 Scene实例, 
   * 可用时机: 监听到 'ready' 事件后
   **/
  getScene(): Scene | null
}

const hiplayer = requirePlugin('hi-player') as HiPlayerPluginExports