CrossBridge 使用示例

本指南提供了 CrossBridge 插件在各种场景下的详细使用示例。

1. 基础安装与配置

首先引入 CrossBridge：

import { CrossBridge } from '@pt/cross-bridge';

2. 同域通信场景

2.1 独立标签页通信 (Standalone Tabs)

页面 A (发送方):

const bridgeA = new CrossBridge({
  pageId: 'tab-a',
  role: 'standalone',
  adapters: ['shared-worker', 'broadcast-channel'], // 优先使用 SharedWorker，降级使用 QC
  debug: true
});

await bridgeA.connect();

// 发送消息给 tab-b
bridgeA.sendTo('tab-b', 'greeting', { text: 'Hello from Tab A' });

页面 B (接收方):

const bridgeB = new CrossBridge({
  pageId: 'tab-b',
  role: 'standalone',
  adapters: ['shared-worker', 'broadcast-channel']
});

await bridgeB.connect();

bridgeB.on('greeting', (data, from) => {
  console.log(`Received from ${from}:`, data.text);
});

2.2 iframe 通信

父页面 (Parent):

const parentBridge = new CrossBridge({
  pageId: 'parent-page',
  role: 'parent',
  adapters: ['post-message']
});

await parentBridge.connect();

// 广播给所有子 iframe
parentBridge.broadcast('update-theme', { theme: 'dark' });

子 iframe (Child):

const childBridge = new CrossBridge({
  pageId: 'child-1',
  role: 'child',
  adapters: ['post-message']
});

await childBridge.connect();

childBridge.on('update-theme', (data) => {
  document.body.className = data.theme;
});

3. 完全跨域通信场景

3.1 使用 WebSocket 中继 (高性能)

适用于需要实时通讯的场景。需要部署 server/relay-server.ts。

客户端配置:

const bridge = new CrossBridge({
  pageId: 'cross-domain-app',
  role: 'standalone',
  adapters: [
    {
      type: 'websocket-relay',
      config: {
        relayServer: 'ws://localhost:8080', // 你的 WebSocket 服务地址
        authentication: {
          token: 'your-auth-token',
          domain: 'your-domain.com'
        }
      }
    }
  ]
});

await bridge.connect();

3.2 使用 Iframe 桥接 (无后端)

适用于无法部署 WebSocket 服务端的场景。需要部署 server/bridge.html。

客户端配置:

const bridge = new CrossBridge({
  pageId: 'static-site-app',
  role: 'standalone',
  adapters: [
    {
      type: 'iframe-bridge',
      config: {
        bridgeUrl: 'https://cdn.example.com/bridge.html' // 你的静态桥接页地址
      }
    }
  ]
});

await bridge.connect();

4. 消息队列与持久化

CrossBridge 默认启用了消息队列，但你可以根据需求进行深度配置，尤其是持久化策略。

高级配置示例:

const bridge = new CrossBridge({
  pageId: 'app-main',
  role: 'standalone',
  adapters: ['shared-worker'],
  
  // 队列配置
  queue: {
    maxQueueSize: 2000,
    cleanupInterval: 60000, // 每分钟清理一次
    
    // 针对不同消息类型的特定配置
    messageTypes: {
      // 普通用户操作，短期缓存
      'user-action': {
        priority: 5,
        ttl: 30000, // 30秒过期
        storage: 'memory',
        persistent: false
      },
      
      // 关键系统通知，必须送达，持久化到本地存储
      'system-alert': {
        priority: 1, // 最高优先级
        ttl: 7 * 24 * 60 * 60 * 1000, // 7天有效
        storage: 'local', // 使用 LocalStorage
        persistent: true
      },
      
      // 大数据量同步，使用 IndexedDB
      'data-sync': {
        priority: 10,
        ttl: 24 * 60 * 60 * 1000,
        storage: 'indexeddb',
        persistent: true
      }
    }
  }
});

5. 生命周期管理与错误处理

const bridge = new CrossBridge({ /* config */ });

try {
  await bridge.connect();
  console.log('Connected!');
  
  // 检查连接状态
  if (bridge.isConnected()) {
    const pages = bridge.getConnectedPages();
    console.log('Online pages:', pages);
  }
} catch (error) {
  console.error('Failed to connect:', error);
}

// 优雅断开
window.addEventListener('beforeunload', () => {
  bridge.disconnect();
});