@beppla/tapas-ui 1.5.13 → 1.5.15

package/components/WebViewBridge/WebViewBridge.tsx

@@ -0,0 +1,1147 @@
+/**
+ * WebViewBridge - WebView/iframe 通信桥接组件
+ * 
+ * 用于 RN Web 模块与 tapas-sys 底座之间的通信
+ * - Android/iOS: 使用 WebView postMessage/onMessage
+ * - Web: 使用 iframe window.postMessage/onMessage
+ * 
+ * 自动检测运行环境并适配相应的通信方式
+ */
+import React, { useEffect, useRef, useCallback, useImperativeHandle, forwardRef } from 'react';
+import { Platform, View, StyleSheet } from 'react-native';
+
+/** Extended Window interface for React Native WebView bridge */
+interface BridgeWindow extends Window {
+  ReactNativeWebView?: {
+    postMessage: (message: string) => void;
+  };
+}
+
+export interface WebViewMessage {
+  type: string;
+  payload?: any;
+  timestamp?: number;
+  id?: string;
+  from?: string;  // 消息来源标识
+}
+
+/**
+ * tapas-sys 消息格式
+ */
+export interface TapasSysMessage {
+  operate: string;  // 对应 WebViewMessage.type
+  action?: string;  // 从 payload.action 提取，如果没有则使用 operate
+  data?: any;       // 对应 WebViewMessage.payload
+  from?: string;   // 消息来源标识
+}
+
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+export interface WebViewBridgeProps {
+  /**
+   * 消息来源标识（用于标识 RN Web 模块）
+   * 这个值会作为消息的 from 字段发送给 tapas-sys
+   * 必需：RN web 向 tapas-sys 发送消息时必须提供此字段
+   */
+  from: string;
+  
+  /**
+   * 消息监听回调
+   */
+  onMessage?: (message: WebViewMessage) => void;
+  
+  /**
+   * 错误回调
+   * @param error 错误对象
+   * @param context 错误上下文（发送/接收/解析）
+   */
+  onError?: (error: Error, context?: { type: 'send' | 'receive' | 'parse' | 'origin' }) => void;
+  
+  /**
+   * 初始化消息的 payload
+   */
+  initPayload?: any;
+  
+  /**
+   * 是否自动发送初始化消息（默认 true）
+   */
+  autoInit?: boolean;
+  
+  /**
+   * 初始化消息类型（默认 'init'）
+   */
+  initMessageType?: string;
+  
+  /**
+   * 是否启用 base64 加密（默认 true，符合 tapas-sys 解析格式）
+   */
+  enableBase64?: boolean;
+  
+  /**
+   * 是否显示占位 DOM（默认 true，用于确保组件有实体）
+   */
+  showPlaceholder?: boolean;
+  
+  /**
+   * 自定义样式
+   */
+  style?: any;
+  
+  /**
+   * 测试 ID
+   */
+  testID?: string;
+  
+  /**
+   * 安全性：允许的消息来源（origin）白名单
+   * 在 iframe 环境中，只有来自这些 origin 的消息才会被处理
+   * 如果为空数组，则不进行 origin 验证（仅开发环境推荐）
+   */
+  allowedOrigins?: string[];
+  
+  /**
+   * 安全性：是否严格验证 origin（默认 false）
+   * true: 如果消息来源不在 allowedOrigins 中，直接拒绝
+   * false: 仅警告，但仍处理消息（开发环境）
+   */
+  strictOriginCheck?: boolean;
+  
+  /**
+   * 安全性：只接收来自特定 from 的消息
+   * 如果设置，只有 from 字段匹配的消息才会被处理
+   */
+  allowedFrom?: string[];
+  
+  /**
+   * 消息过滤器函数
+   * 返回 true 表示处理该消息，false 表示忽略
+   */
+  messageFilter?: (message: WebViewMessage) => boolean;
+  
+  /**
+   * 调试模式（默认 false）
+   * 启用后会输出详细的日志信息
+   */
+  debug?: boolean;
+  
+  /**
+   * 日志级别（默认 'warn'）
+   * 'none': 不输出任何日志
+   * 'error': 仅输出错误
+   * 'warn': 输出警告和错误
+   * 'info': 输出信息、警告和错误
+   * 'debug': 输出所有日志（包括调试信息）
+   */
+  logLevel?: LogLevel;
+}
+
+export type WebViewBridgeRef = {
+  /**
+   * 发送消息到父窗口/WebView
+   * @param type 消息类型
+   * @param payload 消息数据
+   * @returns 是否发送成功
+   */
+  sendMessage: (type: string, payload?: any) => boolean;
+  
+  /**
+   * 获取当前运行环境
+   */
+  getEnvironment: () => 'webview' | 'iframe' | 'unknown';
+  
+  /**
+   * 清理所有监听器和资源
+   */
+  cleanup: () => void;
+}
+
+/**
+ * 检测当前运行环境
+ */
+const detectEnvironment = (): 'webview' | 'iframe' | 'unknown' => {
+  if (typeof window === 'undefined') {
+    return 'unknown';
+  }
+  
+  try {
+    // 🔧 修复：使用与 checkRunningPlatform 完全一致的逻辑
+    // 1. 首先检查是否是 iframe
+    const isIframe = window.self !== window.top;
+    if (isIframe) {
+      return 'iframe';
+    }
+    
+    // 2. 然后检查是否是 WebView（通过 userAgent）
+    const isWebView = /WebView|wv/i.test(navigator.userAgent);
+    if (isWebView) {
+      return 'webview';
+    }
+    
+    // 3. 如果是 React Native 环境（非 Web），默认是 webview
+    if (Platform.OS !== 'web') {
+      return 'webview';
+    }
+    
+    // 4. 默认 Web 环境视为 browser，但这里我们返回 'iframe' 以保持兼容性
+    return 'iframe';
+  } catch (e) {
+    // 错误时，如果是 React Native 环境，默认是 webview
+    if (Platform.OS !== 'web') {
+      return 'webview';
+    }
+    return 'iframe';
+  }
+};
+
+/**
+ * WebViewBridge 组件
+ */
+/**
+ * Base64 编码/解码工具函数
+ * 符合 tapas-sys 的解析格式
+ */
+const encodeBase64 = (str: string): string => {
+  try {
+    // 浏览器环境：使用 btoa
+    if (typeof window !== 'undefined') {
+      // 处理 Unicode 字符
+      return window.btoa(unescape(encodeURIComponent(str)));
+    }
+    // Node.js 环境：使用 Buffer
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(str, 'utf-8').toString('base64');
+    }
+    // 降级方案：尝试全局 btoa
+    if (typeof btoa !== 'undefined') {
+      return btoa(unescape(encodeURIComponent(str)));
+    }
+    throw new Error('Base64 编码不可用');
+  } catch (e) {
+    console.warn('WebViewBridge: Base64 编码失败，使用原始字符串', e);
+    return str;
+  }
+};
+
+const decodeBase64 = (str: string): string => {
+  try {
+    // 浏览器环境：使用 atob
+    if (typeof window !== 'undefined') {
+      // 处理 Unicode 字符
+      return decodeURIComponent(escape(window.atob(str)));
+    }
+    // Node.js 环境：使用 Buffer
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(str, 'base64').toString('utf-8');
+    }
+    // 降级方案：尝试全局 atob
+    if (typeof atob !== 'undefined') {
+      return decodeURIComponent(escape(atob(str)));
+    }
+    throw new Error('Base64 解码不可用');
+  } catch (e) {
+    console.warn('WebViewBridge: Base64 解码失败，返回原始字符串', e);
+    return str;
+  }
+};
+
+/**
+ * 日志工具函数
+ */
+const createLogger = (debug: boolean, logLevel: LogLevel) => {
+  const levels: LogLevel[] = ['none', 'error', 'warn', 'info', 'debug'];
+  const currentLevelIndex = levels.indexOf(logLevel);
+
+  const shouldLog = (level: LogLevel) => {
+    const levelIndex = levels.indexOf(level);
+    return levelIndex >= 0 && levelIndex <= currentLevelIndex;
+  };
+
+  return {
+    error: (...args: any[]) => {
+      if (shouldLog('error')) {
+        console.error('[WebViewBridge]', ...args);
+      }
+    },
+    warn: (...args: any[]) => {
+      if (shouldLog('warn')) {
+        console.warn('[WebViewBridge]', ...args);
+      }
+    },
+    info: (...args: any[]) => {
+      if (shouldLog('info')) {
+        console.log('[WebViewBridge]', ...args);
+      }
+    },
+    debug: (...args: any[]) => {
+      if (debug && shouldLog('debug')) {
+        console.log('[WebViewBridge DEBUG]', ...args);
+      }
+    },
+  };
+};
+
+/**
+ * 验证消息来源（origin）
+ */
+const validateOrigin = (
+  origin: string | undefined,
+  allowedOrigins: string[] | undefined,
+  strictOriginCheck: boolean,
+  logger: ReturnType<typeof createLogger>
+): boolean => {
+  // 如果没有设置 allowedOrigins，不进行验证（开发环境）
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    logger.debug('Origin 验证已禁用（allowedOrigins 为空）');
+    return true;
+  }
+
+  // 如果没有 origin（某些环境可能没有），根据 strictOriginCheck 决定
+  if (!origin) {
+    if (strictOriginCheck) {
+      logger.warn('消息没有 origin 信息，且 strictOriginCheck=true，拒绝消息');
+      return false;
+    }
+    logger.warn('消息没有 origin 信息，但 strictOriginCheck=false，允许消息');
+    return true;
+  }
+
+  // 检查 origin 是否在白名单中
+  const isAllowed = allowedOrigins.some(allowed => {
+    // 支持通配符匹配（如 'https://*.example.com'）
+    if (allowed.includes('*')) {
+      const pattern = allowed.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(origin);
+    }
+    return origin === allowed;
+  });
+
+  if (!isAllowed) {
+    if (strictOriginCheck) {
+      logger.error(`消息来源 ${origin} 不在白名单中，拒绝消息。白名单:`, allowedOrigins);
+      return false;
+    }
+    logger.warn(`消息来源 ${origin} 不在白名单中，但 strictOriginCheck=false，允许消息。白名单:`, allowedOrigins);
+    return true;
+  }
+
+  logger.debug(`消息来源 ${origin} 验证通过`);
+  return true;
+};
+
+/**
+ * 验证消息的 from 字段
+ */
+const validateFrom = (
+  messageFrom: string | undefined,
+  allowedFrom: string[] | undefined,
+  logger: ReturnType<typeof createLogger>
+): boolean => {
+  if (!allowedFrom || allowedFrom.length === 0) {
+    return true;
+  }
+
+  if (!messageFrom) {
+    logger.warn('消息没有 from 字段，但设置了 allowedFrom，拒绝消息');
+    return false;
+  }
+
+  const isAllowed = allowedFrom.includes(messageFrom);
+  if (!isAllowed) {
+    logger.warn(`消息 from 字段 ${messageFrom} 不在白名单中，拒绝消息。白名单:`, allowedFrom);
+    return false;
+  }
+
+  logger.debug(`消息 from 字段 ${messageFrom} 验证通过`);
+  return true;
+};
+
+export const WebViewBridge = forwardRef<WebViewBridgeRef, WebViewBridgeProps>(
+  (
+    {
+      from,
+      onMessage,
+      onError,
+      initPayload,
+      autoInit = true,
+      initMessageType = 'init',
+      enableBase64 = true,
+      showPlaceholder = true,
+      style,
+      testID,
+      allowedOrigins,
+      strictOriginCheck = false,
+      allowedFrom,
+      messageFilter,
+      debug = false,
+      logLevel = 'warn',
+    },
+    ref
+  ) => {
+    const environmentRef = useRef<'webview' | 'iframe' | 'unknown'>(detectEnvironment());
+    const messageIdCounterRef = useRef(0);
+    const initSentRef = useRef(false);
+    const messageHandlersRef = useRef<Map<string, (message: WebViewMessage) => void>>(new Map());
+    const loggerRef = useRef(createLogger(debug, logLevel));
+    const cleanupFunctionsRef = useRef<Array<() => void>>([]);
+
+    // 更新 logger 当 debug 或 logLevel 改变时
+    useEffect(() => {
+      loggerRef.current = createLogger(debug, logLevel);
+    }, [debug, logLevel]);
+
+    // 🔧 组件挂载时立即输出日志，确认组件已加载
+    useEffect(() => {
+      loggerRef.current.info('🚀 [WebViewBridge] 组件已挂载', {
+        from,
+        environment: environmentRef.current,
+        autoInit,
+        debug,
+        logLevel,
+        hasWindow: typeof window !== 'undefined',
+        hasReactNativeWebView: typeof window !== 'undefined' && !!(window as BridgeWindow).ReactNativeWebView,
+      });
+    }, []);
+
+    // 生成唯一消息 ID
+    const generateMessageId = useCallback(() => {
+      messageIdCounterRef.current += 1;
+      return `msg_${Date.now()}_${messageIdCounterRef.current}`;
+    }, []);
+
+    // 将 WebViewMessage 转换为 tapas-sys 格式
+    const convertToTapasSysFormat = useCallback((message: WebViewMessage): TapasSysMessage => {
+      const tapasMessage: TapasSysMessage = {
+        operate: message.type,
+        from: message.from,
+      };
+
+      // 处理 payload
+      if (message.payload !== undefined && message.payload !== null) {
+        // 如果 payload 是对象且包含 action 字段，提取 action
+        if (typeof message.payload === 'object' && !Array.isArray(message.payload) && 'action' in message.payload) {
+          tapasMessage.action = message.payload.action;
+          // data 包含 payload 的其他字段（排除 action）
+          const { action: _action, ...rest } = message.payload;
+          tapasMessage.data = Object.keys(rest).length > 0 ? rest : undefined;
+        } else {
+          // 否则，整个 payload 作为 data，action 使用 operate
+          tapasMessage.action = message.type;
+          tapasMessage.data = message.payload;
+        }
+      } else {
+        // 如果没有 payload，action 使用 operate
+        tapasMessage.action = message.type;
+      }
+
+      return tapasMessage;
+    }, []);
+
+    // 将 tapas-sys 格式转换为 WebViewMessage
+    const convertFromTapasSysFormat = useCallback((tapasMessage: TapasSysMessage): WebViewMessage => {
+      const message: WebViewMessage = {
+        type: tapasMessage.operate,
+        from: tapasMessage.from,
+      };
+
+      // 构建 payload
+      if (tapasMessage.data !== undefined) {
+        // 如果有 action 且 action 不等于 operate，将 action 合并到 payload
+        if (tapasMessage.action && tapasMessage.action !== tapasMessage.operate) {
+          message.payload = {
+            action: tapasMessage.action,
+            ...(typeof tapasMessage.data === 'object' && tapasMessage.data !== null && !Array.isArray(tapasMessage.data)
+              ? tapasMessage.data
+              : { data: tapasMessage.data }),
+          };
+        } else {
+          // 否则直接使用 data 作为 payload
+          message.payload = tapasMessage.data;
+        }
+      } else if (tapasMessage.action && tapasMessage.action !== tapasMessage.operate) {
+        // 只有 action，没有 data
+        message.payload = { action: tapasMessage.action };
+      }
+
+      return message;
+    }, []);
+
+    // 解析消息（支持 base64 解码）
+    const parseMessage = useCallback((data: string): WebViewMessage | null => {
+      try {
+        // 尝试 base64 解码
+        let decodedData = data;
+        if (enableBase64) {
+          try {
+            decodedData = decodeBase64(data);
+            loggerRef.current.debug('Base64 解码成功');
+          } catch (e) {
+            // 如果 base64 解码失败，尝试直接解析 JSON
+            // 可能是未加密的消息
+            loggerRef.current.debug('Base64 解码失败，尝试直接解析 JSON', e);
+          }
+        }
+        
+        // 解析 JSON
+        const parsed = typeof decodedData === 'string' 
+          ? JSON.parse(decodedData) 
+          : decodedData;
+        
+        // 判断是 tapas-sys 格式还是 WebViewMessage 格式
+        let message: WebViewMessage;
+        if (parsed.operate !== undefined) {
+          // tapas-sys 格式：{ operate, action, data, from }
+          message = convertFromTapasSysFormat(parsed as TapasSysMessage);
+        } else {
+          // WebViewMessage 格式：{ type, payload, from }
+          message = {
+            type: parsed.type || 'unknown',
+            payload: parsed.payload !== undefined ? parsed.payload : parsed,
+            timestamp: parsed.timestamp || Date.now(),
+            id: parsed.id,
+            from: parsed.from,
+          };
+        }
+
+        loggerRef.current.debug('消息解析成功:', message);
+        return message;
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        loggerRef.current.error('消息解析失败', error, '原始数据:', data);
+        if (onError) {
+          onError(error, { type: 'parse' });
+        }
+        return null;
+      }
+    }, [enableBase64, onError, convertFromTapasSysFormat]);
+
+    // 统一消息格式
+    const normalizeMessage = useCallback((rawMessage: any): WebViewMessage => {
+      let data: string | null = null;
+
+      // 🔧 修复：优先检查是否是 tapas-sys 格式（{ operate, action, data }）
+      // 这对于 webviewmessage 事件特别重要，因为 event.detail 直接是 tapas-sys 格式
+      if (rawMessage && typeof rawMessage === 'object' && rawMessage.operate !== undefined) {
+        loggerRef.current.debug('检测到 tapas-sys 格式消息，直接转换:', rawMessage);
+        return convertFromTapasSysFormat(rawMessage as TapasSysMessage);
+      }
+
+      // WebView 环境：消息通常在 data 字段中
+      if (environmentRef.current === 'webview') {
+        if (typeof rawMessage === 'string') {
+          data = rawMessage;
+        } else if (rawMessage?.nativeEvent?.data) {
+          data = rawMessage.nativeEvent.data;
+        } else if (rawMessage?.data) {
+          data = rawMessage.data;
+        } else {
+          // 直接是对象：检查是 WebViewMessage 格式
+          return {
+            type: rawMessage?.type || 'unknown',
+            payload: rawMessage?.payload || rawMessage,
+            timestamp: rawMessage?.timestamp || Date.now(),
+            id: rawMessage?.id,
+            from: rawMessage?.from,
+          };
+        }
+      } else if (environmentRef.current === 'iframe') {
+        // iframe 环境：消息在 event.data.payload 中（tapas-sys 返回格式：{ source, target, payload }）
+        // 如果 rawMessage 是字符串，说明已经提取了 payload（在 messageHandler 中已处理）
+        if (typeof rawMessage === 'string') {
+          data = rawMessage;
+        } else if (rawMessage?.data?.payload) {
+          // 处理 { source, target, payload } 格式（降级情况）
+          data = rawMessage.data.payload;
+        } else if (rawMessage?.data) {
+          // 降级：直接使用 event.data
+          data = rawMessage.data;
+        } else {
+          // 直接是对象：检查是 WebViewMessage 格式
+          return {
+            type: rawMessage?.type || 'unknown',
+            payload: rawMessage?.payload || rawMessage,
+            timestamp: rawMessage?.timestamp || Date.now(),
+            id: rawMessage?.id,
+            from: rawMessage?.from,
+          };
+        }
+      } else {
+        // 未知环境：尝试通用解析
+        return {
+          type: rawMessage?.type || 'unknown',
+          payload: rawMessage?.payload || rawMessage,
+          timestamp: Date.now(),
+          from: rawMessage?.from,
+        };
+      }
+
+      // 解析字符串数据
+      if (data) {
+        const parsed = parseMessage(data);
+        if (parsed) {
+          return parsed;
+        }
+      }
+
+      // 降级：返回原始数据
+      return {
+        type: 'raw',
+        payload: data || rawMessage,
+        timestamp: Date.now(),
+      };
+    }, [parseMessage, convertFromTapasSysFormat]);
+
+    // 发送消息
+    const sendMessage = useCallback((type: string, payload?: any): boolean => {
+      try {
+        const message: WebViewMessage = {
+          type,
+          payload,
+          timestamp: Date.now(),
+          id: generateMessageId(),
+          from: from,  // 添加 from 字段
+        };
+
+        loggerRef.current.debug('准备发送消息（内部格式）:', message);
+
+        // 转换为 tapas-sys 格式
+        const tapasMessage = convertToTapasSysFormat(message);
+        loggerRef.current.debug('转换为 tapas-sys 格式:', tapasMessage);
+
+        // 将消息对象转为 JSON 字符串
+        const messageJson = JSON.stringify(tapasMessage);
+        
+        // 根据配置决定是否进行 base64 编码
+        const messageToSend = enableBase64 
+          ? encodeBase64(messageJson) 
+          : messageJson;
+
+        if (typeof window === 'undefined') {
+          const error = new Error('window 对象不存在，无法发送消息');
+          loggerRef.current.error(error.message);
+          if (onError) {
+            onError(error, { type: 'send' });
+          }
+          return false;
+        }
+
+        let sent = false;
+
+        // 优先尝试 React Native WebView 的 postMessage（适用于 Android/iOS WebView）
+        if ((window as BridgeWindow).ReactNativeWebView) {
+          try {
+            (window as BridgeWindow).ReactNativeWebView!.postMessage(messageToSend);
+            loggerRef.current.debug('通过 ReactNativeWebView.postMessage 发送成功');
+            sent = true;
+            return true;
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            loggerRef.current.warn('ReactNativeWebView.postMessage 失败', error);
+            if (onError) {
+              onError(error, { type: 'send' });
+            }
+          }
+        }
+
+        // 降级：使用 window.parent.postMessage（适用于 iframe 和 Web WebView）
+        if (!sent && window.parent && window.parent !== window) {
+          try {
+            window.parent.postMessage(messageToSend, '*');
+            loggerRef.current.debug('通过 window.parent.postMessage 发送成功');
+            sent = true;
+            return true;
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            loggerRef.current.warn('window.parent.postMessage 失败', error);
+            if (onError) {
+              onError(error, { type: 'send' });
+            }
+          }
+        }
+
+        // 最后尝试：直接使用 window.postMessage（某些特殊场景）
+        if (!sent && typeof window.postMessage === 'function') {
+          try {
+            // 注意：某些浏览器可能不支持直接调用 window.postMessage
+            // 这里仅作为最后的降级方案
+            (window as BridgeWindow).postMessage(messageToSend, '*');
+            loggerRef.current.debug('通过 window.postMessage 发送成功');
+            sent = true;
+            return true;
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            loggerRef.current.warn('window.postMessage 失败', error);
+            if (onError) {
+              onError(error, { type: 'send' });
+            }
+          }
+        }
+
+        if (!sent) {
+          const error = new Error(`所有消息发送方式都失败，当前环境: ${environmentRef.current}`);
+          loggerRef.current.error(error.message);
+          if (onError) {
+            onError(error, { type: 'send' });
+          }
+          return false;
+        }
+
+        return true;
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        loggerRef.current.error('发送消息时发生未知错误', error);
+        if (onError) {
+          onError(error, { type: 'send' });
+        }
+        return false;
+      }
+    }, [generateMessageId, from, enableBase64, onError, convertToTapasSysFormat]);
+
+    // 消息处理函数
+    const handleMessage = useCallback((rawMessage: any, eventOrigin?: string) => {
+      try {
+        // Origin 验证（仅 iframe 环境）
+        if (environmentRef.current === 'iframe' && eventOrigin !== undefined) {
+          const isValidOrigin = validateOrigin(
+            eventOrigin,
+            allowedOrigins,
+            strictOriginCheck,
+            loggerRef.current
+          );
+
+          if (!isValidOrigin) {
+            const error = new Error(`消息来源 ${eventOrigin} 验证失败`);
+            loggerRef.current.error(error.message);
+            if (onError) {
+              onError(error, { type: 'origin' });
+            }
+            return;
+          }
+        }
+
+        const normalizedMessage = normalizeMessage(rawMessage);
+        
+        if (!normalizedMessage) {
+          loggerRef.current.warn('消息标准化失败，忽略消息');
+          return;
+        }
+
+        // 验证 from 字段
+        if (!validateFrom(normalizedMessage.from, allowedFrom, loggerRef.current)) {
+          loggerRef.current.warn('消息 from 字段验证失败，忽略消息');
+          return;
+        }
+
+        // 消息过滤器
+        if (messageFilter && !messageFilter(normalizedMessage)) {
+          loggerRef.current.debug('消息被过滤器拒绝，忽略消息');
+          return;
+        }
+
+        loggerRef.current.debug('处理消息:', normalizedMessage);
+        
+        // 调用外部监听器
+        if (onMessage) {
+          try {
+            onMessage(normalizedMessage);
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            loggerRef.current.error('onMessage 回调执行错误', error);
+            if (onError) {
+              onError(error, { type: 'receive' });
+            }
+          }
+        }
+
+        // 调用注册的处理器
+        messageHandlersRef.current.forEach((handler) => {
+          try {
+            handler(normalizedMessage);
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            loggerRef.current.error('消息处理器执行错误', error);
+            if (onError) {
+              onError(error, { type: 'receive' });
+            }
+          }
+        });
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        loggerRef.current.error('处理消息时发生未知错误', error);
+        if (onError) {
+          onError(error, { type: 'receive' });
+        }
+      }
+    }, [onMessage, normalizeMessage, allowedOrigins, strictOriginCheck, allowedFrom, messageFilter, onError]);
+
+    // 清理函数
+    const cleanup = useCallback(() => {
+      loggerRef.current.debug('清理所有监听器和资源');
+      cleanupFunctionsRef.current.forEach(cleanupFn => {
+        try {
+          cleanupFn();
+        } catch (e) {
+          loggerRef.current.error('清理函数执行错误', e);
+        }
+      });
+      cleanupFunctionsRef.current = [];
+      messageHandlersRef.current.clear();
+    }, []);
+
+    // 注册消息监听（优化：基于验证通过的 demo 实现）
+    useEffect(() => {
+      loggerRef.current.info('🔧 [WebViewBridge] 开始注册消息监听器', {
+        environment: environmentRef.current,
+        hasWindow: typeof window !== 'undefined',
+        hasReactNativeWebView: typeof window !== 'undefined' && !!(window as BridgeWindow).ReactNativeWebView,
+      });
+      
+      if (typeof window === 'undefined') {
+        loggerRef.current.warn('⚠️ [WebViewBridge] window 不存在，无法注册监听器');
+        return;
+      }
+
+      const cleanupFunctions: Array<() => void> = [];
+
+      // ✅ 优化：基于验证通过的 demo，所有环境都需要注册以下监听器
+      // 1. webviewmessage 自定义事件（Bridgeless 兼容，tapas-sys 优先使用）
+      // 2. message 标准事件（官方标准方式）
+      
+      // 1. 监听 webviewmessage 自定义事件（优先方式，Bridgeless 兼容）
+      const customEventHandler = (event: CustomEvent) => {
+        loggerRef.current.info('🔔 [WebViewBridge] 收到 webviewmessage 自定义事件', {
+          detail: event.detail,
+          type: typeof event.detail,
+        });
+        
+        // event.detail 是消息对象（tapas-sys 发送的格式）
+        // 直接传递给 handleMessage，normalizeMessage 会处理格式转换
+        try {
+          handleMessage(event.detail, window.location.origin);
+        } catch (e) {
+          loggerRef.current.error('处理 webviewmessage 事件失败', e);
+        }
+      };
+      
+      window.addEventListener('webviewmessage', customEventHandler as EventListener);
+      cleanupFunctions.push(() => {
+        window.removeEventListener('webviewmessage', customEventHandler as EventListener);
+      });
+      loggerRef.current.info('✅ [WebViewBridge] webviewmessage 事件监听器已注册');
+
+      // 2. 监听 message 标准事件（官方标准方式）
+      const messageHandler = (event: MessageEvent) => {
+        loggerRef.current.info('🔔 [WebViewBridge] 收到 message 事件', {
+          data: event.data,
+          type: typeof event.data,
+          origin: event.origin,
+        });
+        
+        try {
+          // ✅ 优化：根据 demo 验证，event.data 是字符串（JSON.stringify 后的结果）
+          // tapas-sys 使用 window.postMessage(JSON.stringify(message), '*') 发送
+          if (event.data && typeof event.data === 'string') {
+            // 直接传递字符串给 handleMessage，parseMessage 会处理解析
+            loggerRef.current.debug('🔔 [WebViewBridge] 提取 event.data（字符串）', event.data);
+            handleMessage(event.data, event.origin);
+          } else if (event.data && typeof event.data === 'object') {
+            // iframe 环境可能收到对象格式 { source, target, payload }
+            if (environmentRef.current === 'iframe' && event.data.payload) {
+              loggerRef.current.debug('🔔 [WebViewBridge] iframe 环境：提取 payload', event.data.payload);
+              handleMessage(event.data.payload, event.origin);
+            } else {
+              // 降级：传递整个 event.data
+              handleMessage(event.data, event.origin);
+            }
+          } else {
+            // 降级：传递整个 event
+            handleMessage(event, event.origin);
+          }
+        } catch (e) {
+          loggerRef.current.error('处理 message 事件失败', e);
+        }
+      };
+
+      // 根据环境注册 message 事件监听器
+      if (environmentRef.current === 'iframe') {
+        // iframe 环境：使用 window.addEventListener("message")
+        window.addEventListener('message', messageHandler);
+        cleanupFunctions.push(() => {
+          window.removeEventListener('message', messageHandler);
+        });
+        loggerRef.current.info('✅ [WebViewBridge] iframe message 事件监听器已注册 (window)');
+      } else if (environmentRef.current === 'webview') {
+        // WebView 环境：根据平台注册
+        const isIOS =
+          /iPad|iPhone|iPod/.test(navigator.platform) ||
+          (navigator.userAgent.includes('Mac') && 'ontouchend' in document);
+        
+        if (isIOS) {
+          // iOS: 使用 window.addEventListener("message")
+          window.addEventListener('message', messageHandler);
+          cleanupFunctions.push(() => {
+            window.removeEventListener('message', messageHandler);
+          });
+          loggerRef.current.info('✅ [WebViewBridge] iOS message 事件监听器已注册 (window)');
+        } else {
+          // Android: 同时监听 window 和 document（双重保障）
+          // 1. window.document.addEventListener("message") - tapas-sys 可能使用
+          // 2. window.addEventListener("message") - React Native WebView 标准方式
+          
+          if (window.document && typeof window.document.addEventListener === 'function') {
+            window.document.addEventListener('message', messageHandler as EventListener);
+            cleanupFunctions.push(() => {
+              if (window.document && typeof window.document.removeEventListener === 'function') {
+                window.document.removeEventListener('message', messageHandler as EventListener);
+              }
+            });
+            loggerRef.current.info('✅ [WebViewBridge] Android message 事件监听器已注册 (document)');
+          }
+          
+          // 同时监听 window（备用）
+          window.addEventListener('message', messageHandler);
+          cleanupFunctions.push(() => {
+            window.removeEventListener('message', messageHandler);
+          });
+          loggerRef.current.info('✅ [WebViewBridge] Android message 事件监听器已注册 (window, 备用)');
+        }
+      } else {
+        // 未知环境：使用 window.addEventListener("message") 作为降级
+        window.addEventListener('message', messageHandler);
+        cleanupFunctions.push(() => {
+          window.removeEventListener('message', messageHandler);
+        });
+        loggerRef.current.info('✅ [WebViewBridge] 未知环境 message 事件监听器已注册 (window, 降级)');
+      }
+
+      // 保存清理函数
+      const cleanupFn = () => {
+        cleanupFunctions.forEach(fn => {
+          try {
+            fn();
+          } catch (e) {
+            loggerRef.current.error('清理监听器失败', e);
+          }
+        });
+      };
+      
+      cleanupFunctionsRef.current.push(cleanupFn);
+      loggerRef.current.info('✅ [WebViewBridge] 所有消息监听器已注册完成');
+
+      return cleanupFn;
+    }, [handleMessage]);
+
+    // 发送初始化消息（在 window.onload 完成后自动发送）
+    useEffect(() => {
+      if (autoInit && !initSentRef.current && from) {
+        const sendInitMessage = () => {
+          if (!initSentRef.current) {
+            loggerRef.current.info('🚀 [WebViewBridge] 自动发送初始化消息', { 
+              type: initMessageType, 
+              from,
+              environment: environmentRef.current 
+            });
+            sendMessage(initMessageType, initPayload);
+            initSentRef.current = true;
+          }
+        };
+
+        // 🔧 改进：优先检测 React Native WebView 环境
+        const isReactNativeWebView = typeof window !== 'undefined' && 
+          (window as BridgeWindow).ReactNativeWebView !== undefined;
+        
+        if (isReactNativeWebView) {
+          // React Native WebView 环境：延迟发送，确保 WebView 完全加载
+          loggerRef.current.debug('🔍 [WebViewBridge] 检测到 React Native WebView 环境，延迟发送 INIT');
+          setTimeout(sendInitMessage, 500); // 延迟 500ms 确保 WebView 完全加载
+        } else if (typeof window !== 'undefined') {
+          // Web 环境（iframe 或浏览器）
+          if (typeof document !== 'undefined' && 
+              (document.readyState === 'complete' || document.readyState === 'interactive')) {
+            // 文档已经加载完成，使用 setTimeout 确保在下一个事件循环中执行
+            loggerRef.current.debug('🔍 [WebViewBridge] 文档已加载完成，立即发送 INIT');
+            setTimeout(sendInitMessage, 0);
+          } else if (typeof document !== 'undefined') {
+            // 等待 window.onload 事件
+            loggerRef.current.debug('🔍 [WebViewBridge] 等待文档加载完成');
+            const handleLoad = () => {
+              sendInitMessage();
+              window.removeEventListener('load', handleLoad);
+            };
+            window.addEventListener('load', handleLoad);
+            
+            // 也监听 DOMContentLoaded 作为备选（某些情况下可能更快）
+            const handleDOMContentLoaded = () => {
+              // 延迟一点确保所有初始化完成
+              setTimeout(sendInitMessage, 10);
+              document.removeEventListener('DOMContentLoaded', handleDOMContentLoaded);
+            };
+            if (document.readyState === 'loading') {
+              document.addEventListener('DOMContentLoaded', handleDOMContentLoaded);
+            }
+
+            return () => {
+              window.removeEventListener('load', handleLoad);
+              if (typeof document !== 'undefined') {
+                document.removeEventListener('DOMContentLoaded', handleDOMContentLoaded);
+              }
+            };
+          } else {
+            // document 不存在，但 window 存在（某些特殊环境）
+            loggerRef.current.debug('🔍 [WebViewBridge] document 不存在，延迟发送 INIT');
+            setTimeout(sendInitMessage, 100);
+          }
+        } else {
+          // 非 Web 环境（纯 React Native），直接发送
+          loggerRef.current.debug('🔍 [WebViewBridge] 非 Web 环境，延迟发送 INIT');
+          setTimeout(sendInitMessage, 100);
+        }
+      }
+      return undefined;
+    }, [autoInit, initMessageType, initPayload, sendMessage, from]);
+
+    // 组件卸载时清理
+    useEffect(() => {
+      return () => {
+        cleanup();
+      };
+    }, [cleanup]);
+
+    // 暴露方法给父组件
+    useImperativeHandle(ref, () => ({
+      sendMessage,
+      getEnvironment: () => environmentRef.current,
+      cleanup,
+    }), [sendMessage, cleanup]);
+
+    // 渲染占位 DOM（确保组件有实体）
+    if (!showPlaceholder) {
+      return null;
+    }
+
+    return (
+      <View 
+        style={[styles.container, style]} 
+        testID={testID}
+        pointerEvents="none"
+      />
+    );
+  }
+);
+
+WebViewBridge.displayName = 'WebViewBridge';
+
+/**
+ * 原生 WebView 消息注入辅助函数
+ * 在 WebView 的 injectedJavaScript 中使用，用于接收原生消息
+ */
+export const createWebViewInjectedScript = () => {
+  return `
+    (function() {
+      // 创建全局事件总线（如果不存在）
+      if (typeof window.__WebViewBridgeEventBus === 'undefined') {
+        window.__WebViewBridgeEventBus = {
+          listeners: {},
+          on: function(event, handler) {
+            if (!this.listeners[event]) {
+              this.listeners[event] = [];
+            }
+            this.listeners[event].push(handler);
+          },
+          off: function(event, handler) {
+            if (this.listeners[event]) {
+              this.listeners[event] = this.listeners[event].filter(h => h !== handler);
+            }
+          },
+          emit: function(event, data) {
+            if (this.listeners[event]) {
+              this.listeners[event].forEach(handler => {
+                try {
+                  handler(data);
+                } catch (e) {
+                  console.error('WebViewBridge: 事件处理器错误', e);
+                }
+              });
+            }
+          }
+        };
+      }
+
+      // 监听 React Native WebView 的消息
+      // Android: 使用 window.document.addEventListener("message")
+      // iOS: 使用 window.addEventListener("message")
+      // 为了兼容性，同时监听两个事件
+      
+      // 判断是否运行在 iOS 下
+      const isIOS = /iPad|iPhone|iPod/.test(navigator.platform) ||
+        (navigator.userAgent.includes('Mac') && 'ontouchend' in document);
+      
+      if (window.ReactNativeWebView) {
+        if (isIOS) {
+          // iOS: 使用 window.addEventListener("message")
+          window.addEventListener('message', function(event) {
+            if (window.__WebViewBridgeEventBus) {
+              window.__WebViewBridgeEventBus.emit('message', event);
+            }
+          });
+        } else {
+          // Android: 使用 window.document.addEventListener("message")（tapas-sys 使用）
+          if (window.document && typeof window.document.addEventListener === 'function') {
+            window.document.addEventListener('message', function(event) {
+              if (window.__WebViewBridgeEventBus) {
+                window.__WebViewBridgeEventBus.emit('message', event);
+              }
+            });
+          }
+          // 同时监听 window.addEventListener("message") 作为备用
+          window.addEventListener('message', function(event) {
+            if (window.__WebViewBridgeEventBus) {
+              window.__WebViewBridgeEventBus.emit('message', event);
+            }
+          });
+        }
+      } else {
+        // 非 ReactNativeWebView 环境：监听 postMessage（备用方案）
+        window.addEventListener('message', function(event) {
+          if (window.__WebViewBridgeEventBus) {
+            window.__WebViewBridgeEventBus.emit('message', event);
+          }
+        });
+      }
+    })();
+    true; // 确保脚本返回 true
+  `;
+};
+
+/**
+ * 处理原生 WebView 消息
+ * 在 WebView 的 onMessage 回调中调用此函数
+ */
+export const handleNativeWebViewMessage = (
+  event: any,
+  onMessage: (message: WebViewMessage) => void
+) => {
+  try {
+    const data = event.nativeEvent?.data || event.data || event;
+    const message: WebViewMessage = typeof data === 'string' 
+      ? JSON.parse(data) 
+      : data;
+    
+    onMessage(message);
+  } catch (e) {
+    console.error('WebViewBridge: 解析原生消息失败', e);
+  }
+};
+
+const styles = StyleSheet.create({
+  container: {
+    width: 0,
+    height: 0,
+    position: 'absolute',
+    opacity: 0,
+    pointerEvents: 'none',
+  },
+});
+
+export default WebViewBridge;
+