@beppla/tapas-ui 1.5.12 → 1.5.13

package/package/module/WebViewBridge/README.md

@@ -1,564 +0,0 @@
-# WebViewBridge 组件
-
-WebView/iframe 通信桥接组件，用于 RN Web 模块与 tapas-sys 底座之间的通信。
-
-## 功能特性
-
-- ✅ **自动环境检测**：自动判断运行在 Android/iOS WebView 或 Web iframe 环境
-- ✅ **消息格式转换**：自动在内部格式（`{ type, payload }`）和 tapas-sys 格式（`{ operate, action, data }`）之间转换
-- ✅ **统一消息格式**：自动适配不同环境的消息格式差异
-- ✅ **消息监听**：支持全局和类型特定的消息监听
-- ✅ **自动初始化**：组件挂载后，在 window.onload 完成时自动发送初始化消息给 tapas-sys（默认行为）
-- ✅ **Base64 编码**：默认启用 base64 编码，符合 tapas-sys 解析要求
-- ✅ **类型安全**：完整的 TypeScript 类型定义
-- ✅ **易于使用**：提供 Hook 简化使用
-
-## 安装
-
-```bash
-yarn add @beppla/tapas-ui
-# 或
-npm install @beppla/tapas-ui
-```
-
-## 基础用法
-
-### 方式一：使用组件
-
-```tsx
-import React from 'react';
-import { WebViewBridge, WebViewMessage, WebViewBridgeRef } from '@beppla/tapas-ui';
-
-function MyComponent() {
-  const bridgeRef = React.useRef<WebViewBridgeRef>(null);
-
-  const handleMessage = (message: WebViewMessage) => {
-    console.log('收到消息:', message);
-    console.log('消息来源:', message.from); // 来自 tapas-sys 的消息
-    
-    if (message.type === 'userInfo') {
-      console.log('用户信息:', message.payload);
-    }
-  };
-
-  const sendDataToTapasSys = () => {
-    // 向 tapas-sys 发送消息（自动包含 from 字段并 base64 加密）
-    if (bridgeRef.current) {
-      bridgeRef.current.sendMessage('requestData', { 
-        moduleId: 'myModule',
-        action: 'getUserInfo' 
-      });
-    }
-  };
-
-  return (
-    <>
-      <WebViewBridge
-        ref={bridgeRef}
-        from="MyRNWebModule"  // 必需：标识消息来源
-        onMessage={handleMessage}
-        initPayload={{ moduleName: 'MyModule', version: '1.0.0' }}
-        autoInit={true}
-        enableBase64={true}  // 默认启用 base64 加密
-      />
-      <button onClick={sendDataToTapasSys}>发送消息到 tapas-sys</button>
-    </>
-  );
-}
-```
-
-### 方式二：使用 Hook（推荐）
-
-```tsx
-import React from 'react';
-import { useWebViewBridge } from '@beppla/tapas-ui';
-
-function MyComponent() {
-  const { bridgeRef, sendMessage, handleMessage } = useWebViewBridge({
-    onMessage: (message) => {
-      console.log('收到消息:', message);
-      console.log('消息来源:', message.from);
-    },
-    messageHandlers: {
-      'userInfo': (message) => {
-        console.log('用户信息:', message.payload);
-      },
-      'config': (message) => {
-        console.log('配置信息:', message.payload);
-      },
-    },
-  });
-
-  const handleButtonClick = () => {
-    // 发送的消息会自动包含 from 字段并 base64 加密
-    sendMessage('requestData', { id: 123 });
-  };
-
-  return (
-    <>
-      <WebViewBridge
-        ref={bridgeRef}
-        from="MyRNWebModule"  // 必需：标识消息来源
-        onMessage={handleMessage}
-        initPayload={{ moduleName: 'MyModule' }}
-        enableBase64={true}  // 默认启用 base64 加密
-      />
-      <button onClick={handleButtonClick}>请求数据</button>
-    </>
-  );
-}
-```
-
-## API 参考
-
-### WebViewBridge Props
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `from` | `string` | - | **消息来源标识**（**必需**），用于标识 RN Web 模块，会作为消息的 from 字段发送给 tapas-sys |
-| `onMessage` | `(message: WebViewMessage) => void` | - | 消息监听回调 |
-| `onError` | `(error: Error, context?: { type: 'send' \| 'receive' \| 'parse' \| 'origin' }) => void` | - | **错误回调**，当发送/接收/解析消息或 origin 验证失败时触发 |
-| `initPayload` | `any` | - | 初始化消息的 payload |
-| `autoInit` | `boolean` | `true` | **是否自动发送初始化消息**（默认 true）。组件会在 window.onload 完成后自动发送初始化消息给 tapas-sys |
-| `initMessageType` | `string` | `'init'` | 初始化消息类型（默认 'init'） |
-| `enableBase64` | `boolean` | `true` | **是否启用 base64 加密**（默认 true，符合 tapas-sys 解析格式） |
-| `showPlaceholder` | `boolean` | `true` | 是否显示占位 DOM |
-| `style` | `StyleProp<ViewStyle>` | - | 自定义样式 |
-| `testID` | `string` | - | 测试 ID |
-| `allowedOrigins` | `string[]` | - | **安全性：允许的消息来源（origin）白名单**。在 iframe 环境中，只有来自这些 origin 的消息才会被处理。支持通配符（如 `'https://*.example.com'`） |
-| `strictOriginCheck` | `boolean` | `false` | **安全性：是否严格验证 origin**。`true`: 如果消息来源不在白名单中，直接拒绝；`false`: 仅警告，但仍处理消息（开发环境） |
-| `allowedFrom` | `string[]` | - | **安全性：只接收来自特定 from 的消息**。如果设置，只有 from 字段匹配的消息才会被处理 |
-| `messageFilter` | `(message: WebViewMessage) => boolean` | - | **消息过滤器函数**。返回 `true` 表示处理该消息，`false` 表示忽略 |
-| `debug` | `boolean` | `false` | **调试模式**。启用后会输出详细的日志信息 |
-| `logLevel` | `'none' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | **日志级别**。控制输出的日志详细程度 |
-
-### WebViewBridgeRef 方法
-
-| 方法 | 说明 |
-|------|------|
-| `sendMessage(type: string, payload?: any): boolean` | **发送消息到 tapas-sys 底座**（支持 WebView 和 iframe 两种环境）。返回 `true` 表示发送成功，`false` 表示失败 |
-| `getEnvironment(): 'webview' \| 'iframe' \| 'unknown'` | 获取当前运行环境 |
-| `cleanup(): void` | **清理所有监听器和资源**。组件卸载时会自动调用，也可手动调用 |
-
-### 发送消息到 tapas-sys
-
-组件提供了完整的消息发送功能，**RN Web 模块可以通过以下方式向 tapas-sys 发送消息**：
-
-```tsx
-// 方式一：通过 ref
-const bridgeRef = useRef<WebViewBridgeRef>(null);
-
-bridgeRef.current?.sendMessage('requestData', { id: 123 });
-
-// 方式二：通过 Hook
-const { sendMessage } = useWebViewBridge();
-
-sendMessage('requestData', { id: 123 });
-```
-
-**发送机制**：
-- **Android/iOS WebView**：使用 `window.ReactNativeWebView.postMessage()`
-- **Web iframe**：使用 `window.parent.postMessage()`
-- **自动降级**：如果主要方式失败，会自动尝试其他方式
-
-### WebViewMessage 类型
-
-```typescript
-interface WebViewMessage {
-  type: string;        // 消息类型
-  payload?: any;       // 消息数据
-  timestamp?: number;  // 时间戳
-  id?: string;         // 消息 ID
-  from?: string;       // 消息来源标识（RN Web 模块标识）
-}
-```
-
-## 原生 WebView 集成
-
-### React Native WebView
-
-如果使用 `react-native-webview`，需要配置如下：
-
-```tsx
-import { WebView } from 'react-native-webview';
-import { WebViewBridge, handleNativeWebViewMessage } from '@beppla/tapas-ui';
-
-function App() {
-  const handleWebViewMessage = (event: any) => {
-    handleNativeWebViewMessage(event, (message) => {
-      console.log('收到消息:', message);
-    });
-  };
-
-  return (
-    <WebView
-      source={{ uri: 'https://your-app.com' }}
-      onMessage={handleWebViewMessage}
-      injectedJavaScript={createWebViewInjectedScript()}
-    />
-  );
-}
-```
-
-### Expo WebView
-
-```tsx
-import { WebView } from 'react-native-webview';
-import { WebViewBridge, createWebViewInjectedScript } from '@beppla/tapas-ui';
-
-function App() {
-  return (
-    <WebView
-      source={{ uri: 'https://your-app.com' }}
-      injectedJavaScript={createWebViewInjectedScript()}
-    />
-  );
-}
-```
-
-## 消息格式
-
-### 发送消息
-
-```typescript
-// 使用 from 字段标识消息来源
-<WebViewBridge
-  from="MyRNWebModule"
-  enableBase64={true}
-/>
-
-// 发送消息
-sendMessage('requestData', { id: 123 });
-
-// 内部构建的消息对象（WebViewMessage 格式）：
-{
-  type: 'requestData',
-  payload: { id: 123 },
-  timestamp: 1234567890,
-  id: 'msg_1234567890_1',
-  from: 'MyRNWebModule'  // 自动添加
-}
-
-// 自动转换为 tapas-sys 格式后发送：
-{
-  operate: 'requestData',
-  action: 'requestData',  // 如果 payload 中没有 action，使用 operate
-  data: { id: 123 },
-  from: 'MyRNWebModule'
-}
-
-// 发送流程：
-// 1. 构建 WebViewMessage 对象（{ type, payload, from }）
-// 2. 转换为 tapas-sys 格式（{ operate, action, data, from }）
-// 3. JSON.stringify() → JSON 字符串
-// 4. Base64 编码 → base64 字符串
-// 5. 通过 postMessage 发送给 tapas-sys
-```
-
-### Base64 加密
-
-组件默认启用 base64 加密，符合 tapas-sys 的解析格式：
-
-```typescript
-// 启用 base64（默认）
-<WebViewBridge from="MyModule" enableBase64={true} />
-
-// 禁用 base64（仅用于调试）
-<WebViewBridge from="MyModule" enableBase64={false} />
-```
-
-**消息格式转换**：
-
-组件内部使用 `{ type, payload }` 格式（WebViewMessage），但会自动与 tapas-sys 的 `{ operate, action, data }` 格式进行转换：
-
-- **发送时**：`{ type, payload }` → `{ operate, action, data, from }`
-  - `type` → `operate`
-  - 如果 `payload` 是对象且包含 `action` 字段，则提取 `action`，其余字段作为 `data`
-  - 如果 `payload` 没有 `action` 字段，则 `action = operate`，整个 `payload` 作为 `data`
-  
-- **接收时**：`{ operate, action, data, from }` → `{ type, payload }`
-  - `operate` → `type`
-  - 如果 `action` 存在且不等于 `operate`，则 `payload = { action, ...data }`
-  - 否则 `payload = data`
-
-**消息加密流程**：
-1. 构建 WebViewMessage 对象（`{ type, payload, from }`）
-2. 转换为 tapas-sys 格式（`{ operate, action, data, from }`）
-3. `JSON.stringify()` → JSON 字符串
-4. Base64 编码 → base64 字符串
-5. 通过 `postMessage` 发送
-
-**消息解密流程**（接收时）：
-1. 接收 base64 字符串
-2. Base64 解码
-3. `JSON.parse()` 解析为 tapas-sys 格式（`{ operate, action, data, from }`）
-4. 转换为 WebViewMessage 格式（`{ type, payload, from }`）
-5. 触发 `onMessage` 回调
-
-### 接收消息
-
-组件会自动处理不同环境的消息格式差异，并自动进行 base64 解码：
-
-- **WebView 环境**：从 `event.nativeEvent.data` 或 `event.data` 解析（自动 base64 解码）
-- **iframe 环境**：从 `event.data` 解析（自动 base64 解码）
-
-**注意**：如果消息不是 base64 编码的，组件会自动降级为直接 JSON 解析
-
-### 自动初始化消息
-
-**组件会在 window.onload 完成后自动发送初始化消息给 tapas-sys**，这是组件的默认行为，无需手动调用：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"  // 必需：标识消息来源
-  autoInit={true}  // 默认 true，在 window.onload 完成后自动发送
-  initMessageType="init"  // 默认 'init'
-  initPayload={{ moduleName: 'MyModule', version: '1.0.0' }}
-  enableBase64={true}  // 默认 true，消息会进行 base64 编码
-/>
-```
-
-**初始化流程**：
-1. 组件挂载后，检测 `document.readyState`
-2. 如果文档已加载完成（`complete` 或 `interactive`），立即发送初始化消息
-3. 如果文档还在加载，等待 `window.onload` 事件
-4. 发送的消息格式：`{ type: 'init', payload: {...}, from: 'MyRNWebModule', ... }`
-5. 消息会自动进行 base64 编码后发送给 tapas-sys
-
-**重要说明**：
-- `from` 字段是**必需的**，用于标识 RN Web 模块，tapas-sys 需要此字段来识别消息来源
-- 初始化消息会在 RN web 项目完全加载后（window.onload）自动发送，确保所有资源都已就绪
-- 如果不需要自动初始化，可以设置 `autoInit={false}`，然后手动调用 `sendMessage('init', {...})`
-
-## 运行环境检测
-
-组件会自动检测运行环境：
-
-- **Android/iOS**：检测为 `'webview'`
-- **Web（iframe）**：检测为 `'iframe'`
-- **未知环境**：检测为 `'unknown'`
-
-```typescript
-const { getEnvironment } = useWebViewBridge();
-
-const env = getEnvironment();
-console.log('当前环境:', env); // 'webview' | 'iframe' | 'unknown'
-```
-
-## 最佳实践
-
-### 1. 使用 Hook 简化代码
-
-```tsx
-const { bridgeRef, sendMessage, handleMessage } = useWebViewBridge({
-  messageHandlers: {
-    'userInfo': handleUserInfo,
-    'config': handleConfig,
-  },
-});
-```
-
-### 2. 注册特定类型的处理器
-
-```tsx
-const { registerHandler } = useWebViewBridge();
-
-useEffect(() => {
-  const unregister = registerHandler('customType', (message) => {
-    // 处理特定类型的消息
-  });
-  
-  return unregister; // 清理
-}, []);
-```
-
-### 3. 错误处理
-
-```tsx
-const handleMessage = (message: WebViewMessage) => {
-  try {
-    // 处理消息
-  } catch (error) {
-    console.error('消息处理错误:', error);
-    sendMessage('error', { error: error.message });
-  }
-};
-```
-
-### 4. 消息确认机制
-
-```tsx
-const sendMessageWithAck = async (type: string, payload: any) => {
-  const messageId = `msg_${Date.now()}`;
-  
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      reject(new Error('消息超时'));
-    }, 5000);
-    
-    const handler = (message: WebViewMessage) => {
-      if (message.id === messageId) {
-        clearTimeout(timeout);
-        resolve(message);
-      }
-    };
-    
-    registerHandler('ack', handler);
-    sendMessage(type, { ...payload, messageId });
-  });
-};
-```
-
-## 安全性配置
-
-### Origin 验证
-
-在生产环境中，强烈建议配置 `allowedOrigins` 和 `strictOriginCheck` 来确保消息来源可信：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"
-  allowedOrigins={[
-    'https://tapas-sys.example.com',
-    'https://*.example.com',  // 支持通配符
-  ]}
-  strictOriginCheck={true}  // 生产环境建议设为 true
-  onError={(error, context) => {
-    if (context?.type === 'origin') {
-      console.error('消息来源验证失败:', error);
-      // 可以上报安全事件
-    }
-  }}
-/>
-```
-
-### 消息来源过滤
-
-可以限制只接收来自特定 `from` 的消息：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"
-  allowedFrom={['tapas-sys', 'other-module']}  // 只接收来自这些模块的消息
-  onMessage={handleMessage}
-/>
-```
-
-### 消息过滤器
-
-使用自定义过滤器函数来过滤消息：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"
-  messageFilter={(message) => {
-    // 只处理特定类型的消息
-    return message.type === 'userInfo' || message.type === 'config';
-  }}
-  onMessage={handleMessage}
-/>
-```
-
-## 调试和日志
-
-### 调试模式
-
-启用调试模式可以查看详细的日志信息：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"
-  debug={true}  // 启用调试模式
-  logLevel="debug"  // 输出所有日志
-  onMessage={handleMessage}
-/>
-```
-
-### 日志级别
-
-- `'none'`: 不输出任何日志
-- `'error'`: 仅输出错误
-- `'warn'`: 输出警告和错误（默认）
-- `'info'`: 输出信息、警告和错误
-- `'debug'`: 输出所有日志（包括调试信息）
-
-## 错误处理
-
-### 错误回调
-
-使用 `onError` 回调来处理各种错误：
-
-```tsx
-<WebViewBridge
-  from="MyRNWebModule"
-  onError={(error, context) => {
-    switch (context?.type) {
-      case 'send':
-        console.error('发送消息失败:', error);
-        // 可以重试或上报
-        break;
-      case 'receive':
-        console.error('接收消息失败:', error);
-        break;
-      case 'parse':
-        console.error('解析消息失败:', error);
-        break;
-      case 'origin':
-        console.error('Origin 验证失败:', error);
-        // 安全事件，应该上报
-        break;
-    }
-  }}
-/>
-```
-
-### 发送状态检查
-
-`sendMessage` 现在返回布尔值，表示是否发送成功：
-
-```tsx
-const bridgeRef = useRef<WebViewBridgeRef>(null);
-
-const handleSend = () => {
-  if (bridgeRef.current) {
-    const success = bridgeRef.current.sendMessage('requestData', { id: 123 });
-    if (!success) {
-      console.error('消息发送失败');
-      // 可以重试
-    }
-  }
-};
-```
-
-## 注意事项
-
-1. **安全性**：在生产环境中，**必须**配置 `allowedOrigins` 和 `strictOriginCheck={true}` 确保消息来源可信
-2. **性能**：避免在消息处理器中执行耗时操作
-3. **内存泄漏**：记得清理注册的处理器，组件卸载时会自动清理
-4. **兼容性**：确保父窗口/WebView 支持 postMessage API
-5. **调试**：开发环境可以使用 `debug={true}` 和 `logLevel="debug"` 来查看详细日志，生产环境建议使用 `logLevel="error"` 或 `"warn"`
-
-## 故障排查
-
-### 消息无法发送
-
-1. 检查运行环境是否正确检测
-2. 确认父窗口/WebView 存在
-3. 检查控制台是否有错误信息
-
-### 消息无法接收
-
-1. 确认已正确配置 `onMessage` 回调
-2. 检查消息格式是否正确
-3. 验证事件监听器是否已注册
-
-### 初始化消息未发送
-
-1. 确认 `autoInit` 为 `true`
-2. 检查组件是否已完全渲染
-3. 查看控制台是否有错误
-
-## 示例
-
-完整示例请参考 Storybook 中的 `WebViewBridge` 组件示例。
-