@ spective/ 运算

传输层,用于在Web Publications,iframes,和Web应用程序之间进行跨平台通信.

安装

# npm
npm install @aspectly/transports

# pnpm
pnpm add @aspectly/transports

# yarn
yarn add @aspectly/transports

概览

@aspectly/transports 提供了灵活的抽象层,用于平台检测和消息通过不同执行背景. 它会自动检测当前环境(CefSharp,WKWebView/WebKitGTK,React Introduct WebView,Android WebView,Flutter WebView,iframe,或浏览器窗口),并为双向通信提供统一的API.

内建运输

自动检测

这个 TransportRegistry 根据优先级顺序自动选择适当的运输。 优先运输首先检查,确保使用最具体的运输:

cefsharp (100) > webkit (95) > react-native (90) > android (85) >
flutter (84) > iframe (80) > window (70) > postmessage (10) > null (fallback)

快速启动

自动检测( 建议)

import { detectTransport } from '@aspectly/transports';

// Automatically detect the current environment
const transport = detectTransport();
// transport.name is one of: 'cefsharp', 'webkit', 'react-native', 'android',
// 'flutter', 'iframe', 'window', 'postmessage', or 'null'
console.log(`Using transport: ${transport.name}`);

// Send a message
transport.send(JSON.stringify({ type: 'hello', data: 'world' }));

// Subscribe to incoming messages
const unsubscribe = transport.subscribe((message) => {
  const data = JSON.parse(message);
  console.log('Received:', data);
});

// Cleanup when done
unsubscribe();

直接运输使用

import { CefSharpTransport } from '@aspectly/transports';

const transport = new CefSharpTransport();

if (transport.isAvailable()) {
  transport.send(JSON.stringify({ method: 'getData' }));
}

自定义运输登记

import { registerTransport, detectTransport } from '@aspectly/transports';

// Register a custom transport with high priority
registerTransport({
  name: 'electron',
  priority: 150, // Higher than CefSharp (100)
  detect: () => {
    return typeof window !== 'undefined' &&
           window.electron?.send !== undefined;
  },
  createTransport: () => new ElectronTransport(),
});

// Now auto-detection will check your custom transport first
const transport = detectTransport();

API 参考

运输接口

所有传输系统实施的核心接口 :

interface Transport {
  readonly name: string;
  isAvailable(): boolean;
  send(message: string): void;
  subscribe(listener: TransportListener): TransportUnsubscribe;
}

属性 :

• name - 运输的唯一标识(例如“cefsharp”、“反应-内生”)

方法:

• isAvailable() - 检查当前环境中是否有运输工具
• send(message: string) - 向父/主机上下文发送信息
• subscribe(listener) - 订阅收到的信件, 返回清理功能

类型

// Message listener callback
type TransportListener = (message: string) => void;

// Cleanup function returned by subscribe
type TransportUnsubscribe = () => void;

// Factory function for creating transports
type TransportFactory = () => Transport;

传输检测器接口

用于登记海关运输:

interface TransportDetector {
  readonly name: string;
  readonly priority: number;
  detect(): boolean;
  createTransport(): Transport;
}

属性 :

• name - 运输标识符
• priority - 检测优先级(先检查较高值)

方法:

• detect() - 回来 true 如果有这种运输工具
• createTransport() - 创建并返回运输实例

基础运输类

提供共同功能的抽象基础类:

abstract class BaseTransport implements Transport {
  abstract readonly name: string;
  abstract isAvailable(): boolean;
  abstract send(message: string): void;
  abstract subscribe(listener: TransportListener): TransportUnsubscribe;

  protected hasWindow(): boolean;
  protected getWindow(): Window | null;
}

受保护的助手 :

• hasWindow() - 检查是否 window 定义( SSR 安全)
• getWindow() - 安全获取 window 对象或 null

运输登记

全球运输探测器管理登记册:

class TransportRegistry {
  register(detector: TransportDetector): void;
  unregister(name: string): void;
  getDetectors(): readonly TransportDetector[];
  detect(forceRedetect?: boolean): Transport;
  clearCache(): void;
  reset(): void;
}

方法:

• register(detector) - 登记海关运输探测器
• unregister(name) - 取出一个名字的探测器
• getDetectors() - 获取所有注册的探测器
• detect(forceRedetect?) - 探测并返回适当的运输工具(密封)
• clearCache() - 清除缓存运输工具
• reset() - 重置为默认状态(仅装入探测器)

方便职能

// Detect the current transport
function detectTransport(forceRedetect?: boolean): Transport;

// Register a custom detector
function registerTransport(detector: TransportDetector): void;

内建运输

CefSharp 运输

用于使用桌面应用程序 切夫共享 (.NET的铬嵌入框架).

检测 : 检查 window.CefSharp.PostMessage 优先级 : 100 (最高)

import { CefSharpTransport } from '@aspectly/transports';

const transport = new CefSharpTransport();
transport.send(JSON.stringify({ action: 'openFile' }));

const unsubscribe = transport.subscribe((message) => {
  console.log('From C#:', message);
});

通讯:

• 通过 window.CefSharp.PostMessage(message)
• 通过 window.postMessage 事件

WebKit 运输

对于在 Apple WKWebView (iOS, macOS, visionOS) 或 Linux WebKitGTK 内运行的网页内容 WebKitWebView。两者重复使用相同 window.webkit.messageHandlers.aspectly 机制.

检测 : 检查 window.webkit.messageHandlers.aspectly 优先级 : 95 (韩语)

import { WebKitTransport } from '@aspectly/transports';

const transport = new WebKitTransport();
transport.send(JSON.stringify({ action: 'openFile' }));

通讯:

• 通过 window.webkit.messageHandlers.aspectly.postMessage(message)
• 通过 window.postMessage 事件

反向运输

对于在内部运行的网络内容 反应原生网络视频。 。 。 .

检测 : 检查 window.ReactNativeWebView.postMessage 优先级 : 90 (韩语)

import { ReactNativeTransport } from '@aspectly/transports';

const transport = new ReactNativeTransport();
transport.send(JSON.stringify({ action: 'navigate' }));

通讯:

• 通过 window.ReactNativeWebView.postMessage(message)
• 信件被iOS兼容性的引文所包裹 : '${message}'
• 通过 window.postMessage 事件

Android 运输公司

在Android内运行的网络内容 WebView。 。 。 .

检测 : 检查 window.AspectlyAndroid.postMessage 优先级 : 85个

import { AndroidTransport } from '@aspectly/transports';

const transport = new AndroidTransport();
transport.send(JSON.stringify({ action: 'navigate' }));

通讯:

• 通过 window.AspectlyAndroid.postMessage(message)
• 通过 window.postMessage 事件

小蝶运输

对于在小蝶内运行的网络内容 webview_flutter WebViewController。 。 。 .

检测 : 检查 window.AspectlyFlutter.postMessage 优先级 : 84 (中文(简体) )

import { FlutterTransport } from '@aspectly/transports';

const transport = new FlutterTransport();
transport.send(JSON.stringify({ action: 'navigate' }));

通讯:

• 通过 window.AspectlyFlutter.postMessage(message)
• 通过 window.postMessage 事件

框架运输

对于在iframe内运行的网络内容.

检测 : 检查是否 window.parent !== window 优先级 : 80个

import { IframeTransport } from '@aspectly/transports';

// Default: sends to any origin ('*')
const transport = new IframeTransport();

// Specify target origin for security
const secureTransport = new IframeTransport('https://parent-domain.com');

transport.send(JSON.stringify({ type: 'ready' }));

构造器 :

• new IframeTransport(targetOrigin?: string) - 默认 : '*'

通讯:

• 通过 window.parent.postMessage(message, targetOrigin)
• 通过 window.postMessage 事件

窗口传输

在弹出窗口内运行的网络内容 window.open。 。 。 .

检测 : 检查是否 window.opener !== null 优先级 : 70个

import { WindowTransport } from '@aspectly/transports';

// Default: sends to any origin ('*')
const transport = new WindowTransport();

// Specify target origin for security
const secureTransport = new WindowTransport('https://opener-domain.com');

transport.send(JSON.stringify({ type: 'ready' }));

构造器 :

• new WindowTransport(targetOrigin?: string) - 默认 : '*'

通讯:

• 通过 window.opener.postMessage(message, targetOrigin)
• 通过 window.postMessage 事件

邮政运输

常规 window.postMessage 之前用作后退运输 NullTransport。 。 。 .

检测 : 总是可用 优先级 : 10(最低不退缩)

import { PostMessageTransport } from '@aspectly/transports';

const transport = new PostMessageTransport();
transport.send(JSON.stringify({ type: 'ready' }));

通讯:

• 通过 window.postMessage(message, targetOrigin)
• 通过 window.postMessage 事件

零运输

不进行操作的后退运输。 在没有其他运输工具时使用(例如,SSF、测试).

优先级 : 总是可用的( 回落)

import { NullTransport } from '@aspectly/transports';

const transport = new NullTransport();
transport.isAvailable(); // true
transport.send('message'); // No-op (logs warning in development)
transport.subscribe(() => {}); // Returns no-op cleanup function

行为:

• isAvailable() 总是返回 true
• send() 是无( 开发模式下的日志警告)
• subscribe() 返回一个不操作清理函数

子路径条目点

每个平台专用的运输也作为自己的子路径导出被曝光,因此可以仅导入您需要的运输而无需拉入其他运输:

import { WebKitTransport } from '@aspectly/transports/webkit';

const transport = new WebKitTransport();

软件包根( R)@aspectly/transports继续将每一运输连同登记和便利功能再出口.

创建自定义运输

示例:电子运输

import { BaseTransport, registerTransport } from '@aspectly/transports';
import type { TransportListener, TransportUnsubscribe } from '@aspectly/transports';

// Extend BaseTransport for helper methods
class ElectronTransport extends BaseTransport {
  readonly name = 'electron';

  isAvailable(): boolean {
    const win = this.getWindow();
    return typeof win?.electron?.send === 'function';
  }

  send(message: string): void {
    const win = this.getWindow();
    if (!win?.electron?.send) {
      console.warn('[ElectronTransport] electron.send not available');
      return;
    }
    win.electron.send('message', message);
  }

  subscribe(listener: TransportListener): TransportUnsubscribe {
    const win = this.getWindow();
    if (!win?.electron?.on) {
      return () => {};
    }

    const handler = (_event: any, message: string) => {
      listener(message);
    };

    win.electron.on('message', handler);
    return () => {
      win.electron?.removeListener('message', handler);
    };
  }
}

// Register with high priority
registerTransport({
  name: 'electron',
  priority: 150,
  detect: () => {
    return typeof window !== 'undefined' &&
           window.electron?.send !== undefined;
  },
  createTransport: () => new ElectronTransport(),
});

执行情况核对表

创建自定义运输时 :

1. 扩展 BaseTransport 或执行 Transport 接口
2. 提供独有 name 属性
3. 执行 isAvailable() 检查环境
4. 执行 send() 发送信件
5. 执行 subscribe() 接收信件
6. 返回清理函数 subscribe()
7. * 处理安保部门改革/安全丢失全球
8. 创建一个 TransportDetector 登记
9. 设置适当 priority (较高=先检查)

相关软件包

• @aspectly/core - 核心桥梁协议和信息处理
• @aspectly/web - 网络/框架与反应钩的结合
• @aspectly/react-native - 反应原生网络视频集成
• @aspectly/react-native-web - 通用反应原生网络支持

许可证

麻省理工学院