@realsee/vr-signals

接入使用

使用 npm 包

1. 使用 npm 安装

npm install @realsee/vr-signals

2. 协商确认远端支持的方法和事件，写一个类型声明文件

// vr-signals-types.ts

/**
 * 声明支持的方法列表，方便 IDE 做代码提示
 */
export type ActionMap = {
  'tag.changeData': (arg: { id: string; title: string; description: string }) => void
  'monitor.open': (arg: { id: string }) => void
  'monitor.close': (arg: { id: string }) => void
}

/**
 * 声明支持的事件列表，方便 IDE 做代码提示
 */
export type EventMap = {
  'tag.click': (data: {
    id: string
    data: {
      /** 标签 id */
      id: string
      /** 标签标题 */
      title: string
      /** 标签描述 */
      description: string
      /** 标签类型 */
      type: string
      /** 扩展字段 */
      extraData: string
    }
  }) => void
  'monitor.open': (data: {
    id: string
    data: {
      /** 监控 id */
      id: string
      /** 监控名称 */
      name: string
      /** 监控视频地址 */
      videoSrc: string
      /** 监控类型 */
      type: string
      /** 扩展字段 */
      extraData: string
    }
  }) => void
  'monitor.close': (data: {
    id: string
    data: {
      /** 监控 id */
      id: string
      /** 监控名称 */
      name: string
      /** 监控视频地址 */
      videoSrc: string
      /** 监控类型 */
      type: string
      /** 扩展字段 */
      extraData: string
    }
  }) => void
  'overlay.visible': (data: { visible: boolean }) => void
}

3. 客户端 引入使用（接收 VR 的事件与向 VR 发送请求指令）

// 引入 RealseeVRSignalsClient 类
import { RealseeVRSignalsClient } from '@realsee/vr-signals'
// 引入 ActionMap 和 EventMap 类型声明
import type { ActionMap, EventMap } from './vr-signals-types'

// 创建 RealseeVRSignalsClient 实例
const vrSignalsClient = new RealseeVRSignalsClient<ActionMap, EventMap>({
  // 请将下面的 vrLink 替换为您的 VR 链接
  vrLink: 'xxxx',
  // 传入 iframe 元素
  element: document.getElementById('iframe'),
  // 传入日志级别，可选值为 DEBUG、INFO、WARN、ERROR、NONE，不传则默认无日志，日志会在控制台直接输出
  logLevel: 'DEBUG',
})

// 声明一个标签点击事件回调
const onTagClick: EventMap['tag.click'] = (data) => {
  console.log('tag.click', data)
}

// 在 vrSignalsClient 初始化完成后执行
vrSignalsClient.onReady(async () => {
  // 注册标签点击事件
  vrSignalsClient.on('tag.click', onTagClick)

  // 取消注册标签点击事件
  vrSignalsClient.off('tag.click', onTagClick)

  // 注册标签点击事件，只执行一次
  vrSignalsClient.once('tag.click', onTagClick)

  // 发送一个修改标签数据的请求
  const result = await vrSignalsClient.send('tag.changeData', {
    id: '10896811',
    title: '新标题',
    description: '新描述',
  })

  console.log('tag.changeData', result)
})

4. 服务端 引入使用（向 Client 发送事件并接收 Client 的请求指令）

// 引入 RealseeVRSignalsRemote 类
import { RealseeVRSignalsRemote } from '@realsee/vr-signals'
// 引入 ActionMap 和 EventMap 类型声明
import type { ActionMap, EventMap } from './vr-signals-types'

// 处理 actionMap 的函数映射

const actionMap: ActionMap = {
  'tag.changeData': (arg) => {
    console.log('tag.changeData', arg)
  },
  'monitor.open': (arg) => {
    console.log('monitor.open', arg)
  },
  'monitor.close': (arg) => {
    console.log('monitor.close', arg)
  },
}

// 创建 RealseeVRSignalsRemote 实例
const vrSignalsRemote = new RealseeVRSignalsRemote<ActionMap, EventMap>({
  // 传入日志级别，可选值为 DEBUG、INFO、WARN、ERROR、NONE，不传则默认无日志，日志会在控制台直接输出
  logLevel: 'DEBUG',
  // 传入 actionMap
  actionMap,
})

// 下面的代码是模拟接收到 VR 信号的事件，实际使用时请根据实际情况调用
vrSignalsRemote.sendEevent('tag.click', {
  id: '10896811',
  data: {
    id: '10896811',
    title: '标题',
    description: '描述',
    type: '类型',
    extraData: '扩展字段',
  },
})

API

RealseeVRSignalsClient

构造函数

new RealseeVRSignalsClient(options: {
  vrLink: string, // VR 链接
  element: HTMLElement, // iframe 元素
  logLevel?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE', // 日志级别
})

实例方法

onReady

当 VR 信号准备就绪时触发

onReady(callback: () => void)

on

监听 VR 信号事件

on(eventName: string, callback: (data: any) => void)

off

取消监听 VR 信号事件

off(eventName: string, callback: (data: any) => void)

once

监听 VR 信号事件，只执行一次

once(eventName: string, callback: (data: any) => void)

send

调用 VR 信号方法

send(methodName: string, data: any)

实例属性

logLevel

日志级别

logLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE'

RealseeVRSignalsRemote

构造函数

new RealseeVRSignalsRemote(options: {
  logLevel?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE', // 日志级别
  actionMap: ActionMap, // 方法映射
})

实例方法

sendEevent

发送 VR 信号事件

sendEevent(eventName: string, data: any)

实例属性

logLevel

日志级别

logLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE'

从 0.x 迁移

API 变更

• 移除 RealseeVRSignals 类，改为 RealseeVRSignalsClient 和 RealseeVRSignalsRemote 两个类，分别用于客户端和服务端
• 移除 SDK 里的 方法和事件的类型声明，改为由用户自行声明
• 原有的 onEvent、offEvent、onceEvent 方法改为 on、off、once 方法

代码变更

• 从 0.x 迁移时，需要将原有的 RealseeVRSignals 类的实例改为 RealseeVRSignalsClient 或 RealseeVRSignalsRemote 类的实例
• 将原有的 onEvent、offEvent、onceEvent 方法改为 on、off、once 方法
• 原有的 send 方法保持不变，不需要变更
• 原有的 logLevel 属性保持不变，不需要变更

License

See the LICENSE file for license rights and limitations.