@realsee/vr-signals

Version:

vr 信号器

77 lines (70 loc) • 121 kB

HTML

<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@realsee/vr-signals API Documentation - v2.0.0</title><meta name="description" content="Documentation for @realsee/vr-signals API Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script><script async src="assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">@realsee/vr-signals API Documentation - v2.0.0</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@realsee/vr-signals API Documentation - v2.0.0</h1></div><div class="tsd-panel tsd-typography"><h1 id="realseevr-signals" class="tsd-anchor-link">@realsee/vr-signals<a href="#realseevr-signals" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1>VR 信号通信库，用于在 VR 应用和父窗口之间建立双向通信。 <h2 id="特性" class="tsd-anchor-link">特性<a href="#特性" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul> <li>🔄 自动握手和连接管理</li> <li>📡 双向消息通信</li> <li>🚀 智能重试策略（指数退避 + 抖动）</li> <li>🔌 自动重连机制</li> <li>📝 详细的日志记录</li> <li>🎯 类型安全的 API</li> <li>🛡️ 企业级安全特性</li> <li>✨ 开箱即用的核心类型 - 无需传入泛型参数</li> </ul> <h2 id="🆕-核心类型支持" class="tsd-anchor-link">🆕 核心类型支持<a href="#🆕-核心类型支持" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>SDK 现在提供了核心类型支持，包含了必要的 Action 和 Event。这意味着你可以直接使用 SDK，无需定义自己的类型映射： <h2 id="🚀-动态-action-注册系统" class="tsd-anchor-link">🚀 动态 Action 注册系统<a href="#🚀-动态-action-注册系统" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>SDK 现在支持动态注册和移除 Actions，无需在初始化时传入完整的 <code>actionMap</code>： <h3 id="remote-端动态管理" class="tsd-anchor-link">Remote 端动态管理<a href="#remote-端动态管理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">import { RealseeVRSignalsRemote } from '@realsee/vr-signals' const remote = new RealseeVRSignalsRemote({ logLevel: 'INFO' }) // 动态注册单个 Action remote.registerAction('setState', async (data) => { console.log('setState 被调用:', data) // data 包含 mode, longitude, latitude, fov 等 Five SDK 状态 return { success: true, message: '状态已设置' } }) // 批量注册 Actions remote.registerActions({ 'updateCamera': async (data) => { console.log('updateCamera 被调用:', data) // data.state 包含 longitude, latitude, fov, offset 等 Five SDK 相机状态 return { success: true, message: '相机已更新' } }, 'tag.changeData': async (data) => { console.log('tag.changeData 被调用:', data) return { success: true, message: '标签已更新' } } }) // 移除 Action remote.unregisterAction('tag.changeData') // 监听 Action 变化 remote.onActionChange((event) => { console.log('Action 变化:', event) }) // 获取统计信息 const stats = remote.getActionStats() console.log('已注册 Actions:', stats.registered) </code><button type="button">Copy</button></pre> <h3 id="client-端智能检查" class="tsd-anchor-link">Client 端智能检查<a href="#client-端智能检查" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">import { RealseeVRSignalsClient } from '@realsee/vr-signals' const client = new RealseeVRSignalsClient({ vrLink: 'http://localhost:3000/vr-app', element: iframeElement }) // 检查 Action 是否可用 if (client.isActionAvailable('setState')) { // 安全调用 const result = await client.send('setState', { mode: 'panorama', longitude: 0, latitude: 0, fov: 90 }) console.log('结果:', result) } else { console.log('setState 不可用') } // 监听 Action 可用性变化 client.onActionAvailabilityChange('setState', (available) => { if (available) { console.log('setState 现在可用了！') } else { console.log('setState 不可用了') } }) // 等待特定 Action 可用 try { await client.waitForAction('setState', 5000) console.log('setState 可用，开始调用...') await client.send('setState', { mode: 'panorama', longitude: 0, latitude: 0, fov: 90 }) } catch (error) { console.log('等待超时:', error.message) } // 获取可用 Actions 列表 const availableActions = client.getAvailableActions() console.log('可用的 Actions:', availableActions) </code><button type="button">Copy</button></pre> <h3 id="无需泛型的简单用法" class="tsd-anchor-link">无需泛型的简单用法<a href="#无需泛型的简单用法" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">import { RealseeVRSignalsClient, RealseeVRSignalsRemote } from '@realsee/vr-signals' // 客户端 - 无需泛型 const client = new RealseeVRSignalsClient({ vrLink: 'http://localhost:3000/vr-app', element: document.getElementById('vr-container') as HTMLDivElement, logLevel: 'INFO' }) // 服务端 - 无需泛型 const remote = new RealseeVRSignalsRemote({ logLevel: 'INFO', actionMap: { setState(data) { console.log('State update:', data) // data 包含 mode, longitude, latitude, fov 等 Five SDK 状态 return { success: true } }, updateCamera({ state }) { console.log('Camera update:', state) // state 包含 longitude, latitude, fov, offset 等 Five SDK 相机状态 return { success: true } } } }) // 直接使用预定义的事件和动作 client.on('stateSynced', (data) => { console.log('State synced:', data) // data 包含 mode, longitude, latitude, fov 等 Five SDK 状态 }) client.on('cameraUpdate', (data) => { console.log('Camera updated:', data.state) // data.state 包含 longitude, latitude, fov, offset 等 Five SDK 相机状态 }) client.on('tag.click', (data) => { console.log('Tag clicked:', data.data.title) }) client.on('monitor.open', (data) => { console.log('Monitor opened:', data.data.name) }) client.on('monitor.close', (data) => { console.log('Monitor closed:', data.data.name) }) client.on('overlay.visible', (data) => { console.log('Overlay visibility:', data.visible) }) // 发送动作 client.send('setState', { mode: 'panorama', longitude: 0, latitude: 0, fov: 90 }) client.send('updateCamera', { state: { longitude: 0, latitude: 0, fov: 90, offset: { x: 0, y: 0, z: 0 } } }) // 发送事件 remote.sendEvent('stateSynced', { mode: 'editing', view: 'panorama' }) remote.sendEvent('cameraUpdate', { state: { longitude: 0, latitude: 0, fov: 90, offset: { x: 0, y: 0, z: 0 } }, userAction: false }) </code><button type="button">Copy</button></pre> <h3 id="已实现的核心功能" class="tsd-anchor-link">已实现的核心功能<a href="#已实现的核心功能" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>SDK 包含了以下核心功能： <h4 id="🎮-actions（动作）" class="tsd-anchor-link">🎮 Actions（动作）<a href="#🎮-actions（动作）" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><ul> <li>状态管理: <code>setState</code> - 设置应用状态</li> <li>相机控制: <code>updateCamera</code> - 更新相机状态</li> </ul> <h4 id="📡-events（事件）" class="tsd-anchor-link">📡 Events（事件）<a href="#📡-events（事件）" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><ul> <li>状态同步: <code>stateSynced</code> - 状态同步事件</li> <li>相机事件: <code>cameraUpdate</code> - 相机更新事件</li> <li>标签事件: <code>tag.click</code> - 标签点击事件</li> <li>监控事件: <code>monitor.open</code>, <code>monitor.close</code> - 监控开启/关闭事件</li> <li>覆盖层事件: <code>overlay.visible</code> - 覆盖层显示/隐藏事件</li> </ul> <h3 id="高级用法---扩展核心类型" class="tsd-anchor-link">高级用法 - 扩展核心类型<a href="#高级用法---扩展核心类型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>如果你需要添加自定义功能，仍然可以使用泛型： <pre><code class="typescript">import { RealseeVRSignalsClient, DefaultActionMap, DefaultEventMap } from '@realsee/vr-signals' // 扩展核心类型 interface CustomActionMap extends DefaultActionMap { 'custom.action': (data: { message: string }) => Promise<{ result: string }> } interface CustomEventMap extends DefaultEventMap { 'custom.event': (data: { message: string }) => void } // 使用扩展的类型 const customClient = new RealseeVRSignalsClient<CustomActionMap, CustomEventMap>({ vrLink: 'http://localhost:3000/vr-app', element: document.getElementById('vr-container') as HTMLDivElement }) // 使用核心功能 customClient.on('cameraUpdate', (data) => { console.log('Camera updated:', data.state) }) // 使用自定义功能 customClient.on('custom.event', (data) => { console.log('Custom event:', data.message) }) customClient.send('custom.action', { message: 'Hello' }) </code><button type="button">Copy</button></pre> <h2 id="安全特性" class="tsd-anchor-link">安全特性<a href="#安全特性" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="🚨-安全风险提醒" class="tsd-anchor-link">🚨 安全风险提醒<a href="#🚨-安全风险提醒" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>重要：为了兼容 1.x 版本，2.x 版本默认禁用了严格的安全模式： <ul> <li>默认允许所有域名的跨域通信</li> <li>这提供了与 1.x 版本的最大兼容性</li> <li>在生产环境中建议启用安全模式以提高安全性</li> </ul> <h3 id="🛡️-内置安全机制" class="tsd-anchor-link">🛡️ 内置安全机制<a href="#🛡️-内置安全机制" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ol> <li>Origin 验证：验证消息来源域名</li> <li>消息结构验证：验证消息格式和必需字段</li> <li>时间戳验证：防止重放攻击</li> <li>消息签名：可选的数字签名验证</li> <li>严格模式：限制只允许可信域名</li> <li>🆕 自适应策略：智能识别 iframe 和父级窗口的域名关系</li> </ol> <h3 id="🔄-自适应安全策略" class="tsd-anchor-link">🔄 自适应安全策略<a href="#🔄-自适应安全策略" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>自适应策略是 <code>vr-signals</code> 的核心安全特性，能够智能识别和适应不同的域名关系： <h4 id="自动识别的场景" class="tsd-anchor-link">自动识别的场景<a href="#自动识别的场景" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><ul> <li>同源环境：<code>http://localhost:3000</code> ↔ <code>http://localhost:3000</code> ✅</li> <li>同域名不同端口：<code>http://localhost:3000</code> ↔ <code>http://localhost:1234</code> ✅</li> <li>同域名不同协议：<code>http://example.com</code> ↔ <code>https://example.com</code> ✅</li> <li>子域名关系：<code>https://app.example.com</code> ↔ <code>https://vr.example.com</code> ✅</li> <li>恶意域名：<code>https://app.example.com</code> ↔ <code>https://malicious-site.com</code> ❌</li> </ul> <h4 id="自适应策略优势" class="tsd-anchor-link">自适应策略优势<a href="#自适应策略优势" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><ol> <li>🎯 零配置：开发环境无需手动配置域名白名单</li> <li>🔧 自动适应：自动处理 localhost 不同端口的情况</li> <li>🌐 智能识别：自动识别同域名下的子域名关系</li> <li>🛡️ 安全可靠：完全避免使用危险的通配符</li> <li>⚡ 开箱即用：减少配置错误和安全漏洞</li> </ol> <h3 id="🔒-安全配置示例" class="tsd-anchor-link">🔒 安全配置示例<a href="#🔒-安全配置示例" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><h4 id="完全自适应模式（推荐用于所有环境）" class="tsd-anchor-link">完全自适应模式（推荐用于所有环境）<a href="#完全自适应模式（推荐用于所有环境）" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript">const adaptiveClient = new RealseeVRSignalsClient({ vrLink: 'http://localhost:1234/vr-app', element: iframeElement, // 安全配置：完全自适应 security: { strictMode: true, // 启用严格模式 validateOrigin: true, // 验证消息来源 validateSignature: false, // 开发环境不启用签名验证 signatureKey: undefined } }) </code><button type="button">Copy</button></pre> <h4 id="生产环境配置（自适应--签名验证）" class="tsd-anchor-link">生产环境配置（自适应 + 签名验证）<a href="#生产环境配置（自适应--签名验证）" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript">const productionClient = new RealseeVRSignalsClient({ vrLink: 'https://vr-app.example.com', element: iframeElement, // 安全配置：自适应 + 签名验证 security: { strictMode: true, validateOrigin: true, validateSignature: true, // 启用消息签名验证 signatureKey: 'your-secret-key' // 签名密钥 } }) </code><button type="button">Copy</button></pre> <h2 id="安装" class="tsd-anchor-link">安装<a href="#安装" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="bash">npm install @realsee/vr-signals </code><button type="button">Copy</button></pre> <h2 id="基本用法" class="tsd-anchor-link">基本用法<a href="#基本用法" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="🆕-客户端（父窗口）--使用核心类型" class="tsd-anchor-link">🆕 客户端（父窗口）- 使用核心类型<a href="#🆕-客户端（父窗口）--使用核心类型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">import { RealseeVRSignalsClient } from '@realsee/vr-signals' // 无需泛型参数，直接使用核心类型 const client = new RealseeVRSignalsClient({ vrLink: 'http://localhost:3000/vr-app', element: iframeElement, logLevel: 'INFO', // 自定义握手重试策略 handshakeRetryStrategy: { baseDelay: 500, // 基础延迟 500ms maxDelay: 5000, // 最大延迟 5s jitterRange: [0.85, 1.15] // 抖动因子范围 }, // 自定义重连策略 reconnectStrategy: { baseDelay: 2000, // 基础重连延迟 2s maxDelay: 30000, // 最大重连延迟 30s jitterRange: [0.8, 1.2] // 抖动因子范围 }, shakehandRetryTimes: 10, // 握手重试次数 enableAutoReconnect: true, // 启用自动重连 maxReconnectAttempts: 5 // 最大重连次数 }) // 监听连接状态 client.onConnectionStatusChange((status) => { console.log('Connection status:', status) }) // 等待连接就绪 client.onReady(() => { console.log('Client is ready!') }) // 发送核心动作（无需类型声明） client.send('setState', { mode: 'panorama', longitude: 0, latitude: 0, fov: 90 }) client.send('updateCamera', { state: { longitude: 0, latitude: 0, fov: 90, offset: { x: 0, y: 0, z:<s