@beppla/tapas-ui 1.4.32 → 1.4.34

package/package/module/WebViewBridge/README.md

@@ -0,0 +1,564 @@
+# 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` 组件示例。
+