@genee/uno-webview

基于 iframe 的父窗口和子窗口的通讯机制实现，支持 React 和 Vue 3。

安装

npm install @genee/uno-webview

使用方式

React Hooks (默认)

import { useUno, useUnoParams, useUnoGlobals } from '@genee/uno-webview';

function MyComponent() {
    const uno = useUno();
    const params = useUnoParams();
    const globals = useUnoGlobals();

    // 事件订阅
    useUnoEvent('customEvent', (data) => {
        console.log('Received event:', data);
    });

    // 方法创建
    useUnoMethod('customMethod', (param) => {
        console.log('Method called with:', param);
        return 'response';
    });

    // 使用逻辑
    return <div>Hello World</div>;
}

Vue 3 Composition API

import { useUno, useUnoParams, useUnoGlobals, useUnoEvent, useUnoMethod } from '@genee/uno-webview/vue';

export default {
    setup() {
        const uno = useUno();
        const params = useUnoParams();
        const globals = useUnoGlobals();

        // 事件订阅
        useUnoEvent('customEvent', (data) => {
            console.log('Received event:', data);
        });

        // 方法创建
        useUnoMethod('customMethod', (param) => {
            console.log('Method called with:', param);
            return 'response';
        });

        return { uno, params, globals };
    },
};

显式导入 React 模块

import { useUno, useUnoParams, useUnoGlobals } from '@genee/uno-webview/react';

父端 WebView（宿主页）

import { WebView } from '@genee/uno-webview/parent';

<WebView
    src="https://app.example.com/embed"
    params={{ token: 'xxx' }}
    // 只接受这些来源的子端；不传则不限制（targetOrigin 回落为 '*'）
    targetOrigins={['https://app.example.com']}
/>;

配置了 targetOrigins 后，来源不在白名单内的 iframe 不会被握手、收不到任何消息，父端也不会响应它发起的 getParams 等方法调用。来源以浏览器填写的 event.origin 为准（不可伪造），命中的来源会被用作后续 postMessage 的 targetOrigin。

API 参考

核心函数

useUno() / getUno()

获取 Uno 实例，用于与父窗口通信。

useUnoParams(keys?: string[])

获取响应式参数。

• React: 返回 Record<string, any> 或 any[]
• Vue: 返回 Ref<Record<string, any>> 或 Ref<any[]>

useUnoGlobals(keys?: string[])

获取响应式全局状态。

• React: 返回 Record<string, any> 或 any[]
• Vue: 返回 Ref<Record<string, any>> 或 Ref<any[]>

useUnoEvent(event: string, handler: Function)

订阅事件，组件卸载时自动取消订阅。

useUnoMethod(method: string, handler: Function)

创建方法，组件卸载时自动销毁。

父端组件

<WebView />

| 属性 | 类型 | 说明 | | --- | --- | --- | | params | any | 下发给当前子端实例的参数（必填） | | targetOrigins | string[] | 可信子端来源白名单；留空则不做校验 | | logger | CommonLogger | 日志实现，默认 console | | sessionStorage | { getItem, setItem } | 子端 Session.* 的落地方 | | onLocationChange | (uri: string) => void | 子端 updateCurrentLocation 回调 | | onMethod | (method, params) => any | 兜底处理子端发起的任意方法调用 | | onReady | (rpc: ContentWindowRPC) => void | 每次握手完成时回调当前 rpc 实例 |

类型支持

本库提供完整的 TypeScript 类型定义，支持 React 和 Vue 3 的类型推断。

兼容性

• React 18+
• Vue 3.0+
• TypeScript 4.5+