@beppla/tapas-ui 1.5.14 → 1.5.15

package/package/module/UserSwitcher/README.md

@@ -0,0 +1,334 @@
+# TapasUserSwitcher
+
+一个用户切换组件，支持最多3个用户头像的叠加显示，带有精美的动画效果，适用于多用户环境的快速切换场景。
+
+## 功能特性
+
+- ✅ 支持最多3个用户头像的重叠显示
+- ✅ 智能宽度调整（根据用户数量自动调整）
+- ✅ 双头像类型支持（SVG和图片）
+- ✅ 流畅的淡入淡出和缩放动画
+- ✅ 登录/未登录状态处理
+- ✅ 当前用户自动前置显示
+- ✅ 默认头像回退机制
+- ✅ 完全可定制的回调和样式
+
+## 安装使用
+
+```tsx
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasUserSwitcher
+  isLoggedIn={true}
+  userList={users}
+  currentUserId={1}
+  onUserSwitcherPress={() => openUserModal()}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `userList` | `UserData[]` | `[]` | 用户列表，最多显示3个 |
+| `isLoggedIn` | `boolean` | `false` | 是否处于登录状态 |
+| `height` | `number` | `40` | 组件高度 |
+| `currentUserId` | `number` | - | 当前用户ID，该用户会显示在最前面 |
+| `avatarType` | `'svg' \| 'image'` | `'svg'` | 头像类型 |
+| `loginButtonText` | `string` | `'Login'` | 登录按钮文本 |
+| `onUserSwitcherPress` | `() => void` | - | 点击用户切换器的回调 |
+| `onLoginPress` | `() => void` | - | 点击登录按钮的回调 |
+| `onUserListChange` | `(userList: UserData[]) => void` | - | 用户列表改变时的回调 |
+| `animationDuration` | `number` | `500` | 动画持续时间（毫秒） |
+
+## UserData 接口
+
+```tsx
+interface UserData {
+  id: number;           // 用户唯一标识
+  name: string;         // 用户名称
+  avatar: string;       // 头像数据（base64编码的SVG或图片URL）
+  key: string;          // 用户键值
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import React, { useState } from 'react';
+import { TapasUserSwitcher, UserData } from '@beppla/tapas-ui';
+
+const UserSwitcherDemo = () => {
+  const [isLoggedIn, setIsLoggedIn] = useState(true);
+  const [currentUserId, setCurrentUserId] = useState(1);
+
+  const users: UserData[] = [
+    { id: 1, name: 'John Doe', avatar: 'base64-svg-data', key: 'john' },
+    { id: 2, name: 'Jane Smith', avatar: 'https://example.com/avatar.jpg', key: 'jane' },
+    { id: 3, name: 'Bob Johnson', avatar: '', key: 'bob' }, // 无头像，显示默认图标
+  ];
+
+  const handleUserSwitcherPress = () => {
+    // 打开用户选择模态框
+    console.log('Open user selection modal');
+  };
+
+  const handleLoginPress = () => {
+    setIsLoggedIn(true);
+    setCurrentUserId(1);
+  };
+
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={isLoggedIn}
+      currentUserId={currentUserId}
+      onUserSwitcherPress={handleUserSwitcherPress}
+      onLoginPress={handleLoginPress}
+    />
+  );
+};
+```
+
+### SVG 头像使用
+
+```tsx
+import React from 'react';
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+// 将SVG转换为base64
+const svgToBase64 = (svgString: string) => {
+  return btoa(svgString);
+};
+
+const svgAvatar = svgToBase64(`
+  <svg viewBox="0 0 180 180" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="90" cy="90" r="80" fill="#FF6B6B"/>
+    <circle cx="90" cy="70" r="25" fill="white"/>
+    <ellipse cx="90" cy="130" rx="35" ry="25" fill="white"/>
+  </svg>
+`);
+
+const SvgAvatarDemo = () => {
+  const users = [
+    { id: 1, name: 'User 1', avatar: svgAvatar, key: 'user1' },
+    // ... 更多用户
+  ];
+
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={true}
+      avatarType="svg"
+      currentUserId={1}
+    />
+  );
+};
+```
+
+### 图片头像使用
+
+```tsx
+import React from 'react';
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+const ImageAvatarDemo = () => {
+  const users = [
+    { id: 1, name: 'John', avatar: 'https://randomuser.me/api/portraits/men/1.jpg', key: 'john' },
+    { id: 2, name: 'Jane', avatar: 'https://randomuser.me/api/portraits/women/1.jpg', key: 'jane' },
+    { id: 3, name: 'Bob', avatar: 'https://randomuser.me/api/portraits/men/2.jpg', key: 'bob' },
+  ];
+
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={true}
+      avatarType="image"
+      currentUserId={2}
+      height={50}
+    />
+  );
+};
+```
+
+### 登录状态处理
+
+```tsx
+import React, { useState } from 'react';
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+const LoginStateDemo = () => {
+  const [isLoggedIn, setIsLoggedIn] = useState(false);
+
+  const handleLogin = () => {
+    // 执行登录逻辑
+    setIsLoggedIn(true);
+  };
+
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={isLoggedIn}
+      loginButtonText="Sign In"
+      onLoginPress={handleLogin}
+    />
+  );
+};
+```
+
+### 动态用户切换
+
+```tsx
+import React, { useState } from 'react';
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+const DynamicSwitcherDemo = () => {
+  const [currentUserId, setCurrentUserId] = useState(1);
+  const [users, setUsers] = useState(initialUsers);
+
+  const handleUserSwitcherPress = () => {
+    // 循环切换用户
+    const nextUserId = currentUserId === users[users.length - 1].id 
+      ? users[0].id 
+      : users.find(u => u.id > currentUserId)?.id || users[0].id;
+    
+    setCurrentUserId(nextUserId);
+  };
+
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={true}
+      currentUserId={currentUserId}
+      onUserSwitcherPress={handleUserSwitcherPress}
+      animationDuration={300}
+    />
+  );
+};
+```
+
+### 自定义尺寸和动画
+
+```tsx
+import React from 'react';
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+const CustomSizeDemo = () => {
+  return (
+    <TapasUserSwitcher
+      userList={users}
+      isLoggedIn={true}
+      height={60}              // 更大的高度
+      animationDuration={800}  // 更慢的动画
+      currentUserId={1}
+    />
+  );
+};
+```
+
+## 头像叠加效果说明
+
+组件会根据用户数量自动调整显示效果：
+
+- **1个用户**: 宽度40px，单个头像居中显示
+- **2个用户**: 宽度56px，两个头像部分重叠
+- **3个或更多用户**: 宽度68px，三个头像依次重叠，后面的头像有透明度渐变
+
+头像尺寸按层级递减：
+- 第一层（最前面）: 40px
+- 第二层: 32px  
+- 第三层: 24px
+
+## 动画效果
+
+- **淡入动画**: 透明度从0到1
+- **缩放动画**: 缩放从0.9到1.0
+- **触发时机**: 当`currentUserId`改变时
+- **持续时间**: 可通过`animationDuration`自定义
+
+## 回调事件详解
+
+### onUserSwitcherPress
+用户点击头像区域时触发，通常用于打开用户选择模态框：
+
+```tsx
+const handleUserSwitcherPress = () => {
+  // 显示用户选择模态框
+  setModalVisible(true);
+};
+```
+
+### onLoginPress
+用户点击登录按钮时触发：
+
+```tsx
+const handleLoginPress = () => {
+  // 跳转到登录页面或显示登录模态框
+  navigation.navigate('Login');
+};
+```
+
+### onUserListChange
+当用户列表发生变化时触发（可选）：
+
+```tsx
+const handleUserListChange = (newUserList: UserData[]) => {
+  // 保存用户列表变化到状态管理或本地存储
+  saveUserList(newUserList);
+};
+```
+
+## 最佳实践
+
+1. **用户数量控制**: 虽然组件只显示前3个用户，但建议传入的用户列表不超过5个，以保持性能
+2. **头像数据**: SVG头像建议使用base64编码，图片头像建议使用可靠的CDN链接
+3. **当前用户管理**: 确保`currentUserId`始终对应`userList`中的有效用户
+4. **回调处理**: 在`onUserSwitcherPress`中实现完整的用户选择逻辑
+5. **错误处理**: 为头像加载失败提供默认头像回退
+
+## 样式自定义
+
+组件支持通过`style`属性进行样式自定义：
+
+```tsx
+<TapasUserSwitcher
+  style={{
+    backgroundColor: 'rgba(255, 255, 255, 0.9)',
+    borderRadius: 25,
+    paddingHorizontal: 8,
+  }}
+  userList={users}
+  isLoggedIn={true}
+/>
+```
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasUserSwitcher } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { UserSwitcher } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- 多租户系统的用户快速切换
+- 团队协作工具的成员显示
+- 客服系统的坐席切换
+- 家庭应用的成员选择
+- 游戏中的角色/账号切换
+
+## 注意事项
+
+1. 组件内部会自动将`currentUserId`对应的用户移动到显示列表的第一位
+2. 当`userList`为空时，组件仍会正常渲染（显示为空的容器）
+3. 头像加载失败时会自动显示默认的人物图标
+4. 动画效果在React Native和React Native Web环境下表现一致
+5. 组件的宽度会根据用户数量自动调整，无需手动设置

package/package/module/WebViewBridge/OPTIMIZATION_SUMMARY.md

@@ -0,0 +1,187 @@
+# WebViewBridge 组件优化总结
+
+## 优化时间
+2025-01-XX
+
+## 优化依据
+基于验证通过的 `webview-communication-demo` 实现，确保监听器注册和消息通信的正确性。
+
+---
+
+## 主要优化内容
+
+### 1. 简化监听器注册逻辑 ✅
+
+**优化前**:
+- 复杂的条件判断（iframe/webview/web）
+- 不同环境使用不同的注册方式
+- 代码重复，难以维护
+
+**优化后**:
+- 统一注册逻辑：所有环境都注册 `webviewmessage` 和 `message` 事件监听器
+- 清晰的代码结构，易于理解和维护
+- 双重保障机制，确保消息不丢失
+
+### 2. 优化消息接收处理 ✅
+
+**优化前**:
+- 不同环境使用不同的消息提取方式
+- 消息格式处理不统一
+
+**优化后**:
+- 统一处理 `event.data`（字符串格式，tapas-sys 发送的格式）
+- 正确处理 `webviewmessage` 自定义事件（`event.detail` 是消息对象）
+- 支持 iframe 环境的特殊格式 `{ source, target, payload }`
+
+### 3. 改进日志记录 ✅
+
+**优化前**:
+- 日志记录不完整
+- 难以追踪消息接收流程
+
+**优化后**:
+- 完整的日志记录（监听器注册、消息接收、消息处理）
+- 清晰的日志级别（info/debug/error）
+- 便于调试和问题排查
+
+---
+
+## 关键改进点
+
+### ✅ 监听器注册（双重保障）
+
+```typescript
+// 1. webviewmessage 自定义事件（Bridgeless 兼容，tapas-sys 优先使用）
+window.addEventListener('webviewmessage', customEventHandler);
+
+// 2. message 标准事件（官方标准方式）
+window.addEventListener('message', messageHandler);
+```
+
+**优势**:
+- ✅ 双重保障，确保消息不丢失
+- ✅ 兼容 Bridgeless 模式（CustomEvent）
+- ✅ 兼容标准方式（window.postMessage）
+
+### ✅ 消息接收处理
+
+```typescript
+// webviewmessage 事件：event.detail 是消息对象
+handleMessage(event.detail, window.location.origin);
+
+// message 事件：event.data 是字符串（JSON.stringify 后的结果）
+if (event.data && typeof event.data === 'string') {
+  handleMessage(event.data, event.origin);
+}
+```
+
+**优势**:
+- ✅ 正确处理两种消息格式
+- ✅ 自动提取和解析消息
+- ✅ 支持 iframe 环境的特殊格式
+
+### ✅ 平台特定处理
+
+```typescript
+// iOS: window.addEventListener("message")
+// Android: window.document.addEventListener("message") + window.addEventListener("message")
+```
+
+**优势**:
+- ✅ 根据平台使用最合适的注册方式
+- ✅ Android 双重保障（document + window）
+- ✅ 兼容不同的实现方式
+
+---
+
+## 与 Demo 的一致性
+
+### ✅ 监听器注册时机
+- Demo: 组件挂载时立即注册
+- WebViewBridge: ✅ 组件挂载时立即注册（useEffect）
+
+### ✅ 监听器类型
+- Demo: `webviewmessage` + `message`
+- WebViewBridge: ✅ `webviewmessage` + `message`
+
+### ✅ 消息接收处理
+- Demo: 提取 `event.data`（字符串）或 `event.detail`（对象）
+- WebViewBridge: ✅ 正确处理两种格式
+
+### ✅ 错误处理
+- Demo: try-catch + 日志记录
+- WebViewBridge: ✅ try-catch + 日志记录
+
+---
+
+## 测试建议
+
+### 1. 监听器注册验证
+
+**预期日志**:
+```
+🔧 [WebViewBridge] 开始注册消息监听器
+✅ [WebViewBridge] webviewmessage 事件监听器已注册
+✅ [WebViewBridge] iOS/Android message 事件监听器已注册
+✅ [WebViewBridge] 所有消息监听器已注册完成
+```
+
+### 2. 消息接收验证
+
+**tapas-sys 发送消息时**:
+- ✅ 应该看到 `🔔 [WebViewBridge] 收到 webviewmessage 自定义事件`
+- ✅ 或 `🔔 [WebViewBridge] 收到 message 事件`
+
+**消息处理验证**:
+- ✅ 消息应该被正确解析和处理
+- ✅ `onMessage` 回调应该被触发
+
+### 3. 双向通信验证
+
+**WebView → Native**:
+- ✅ 使用 `window.ReactNativeWebView.postMessage` 发送
+- ✅ Native 端 `onMessage` 应该收到消息
+
+**Native → WebView**:
+- ✅ tapas-sys 使用 `injectJavaScript` + `CustomEvent` 发送
+- ✅ WebViewBridge 应该收到并处理消息
+
+---
+
+## 兼容性
+
+### ✅ 环境支持
+- ✅ iframe 环境
+- ✅ WebView 环境（iOS/Android）
+- ✅ Bridgeless 模式
+
+### ✅ 消息格式支持
+- ✅ tapas-sys 格式：`{ operate, action, data, from }`
+- ✅ WebViewMessage 格式：`{ type, payload, from }`
+- ✅ Base64 编码/解码（可选）
+
+---
+
+## 总结
+
+### ✅ 优化成果
+
+1. **监听器注册**: 简化逻辑，双重保障，确保消息不丢失
+2. **消息接收**: 统一处理，支持多种格式
+3. **日志记录**: 完整详细，便于调试
+4. **兼容性**: 支持所有环境和消息格式
+
+### 📋 下一步
+
+1. 在 tapas-sys 中添加 `injectedJavaScriptBeforeContentLoaded`（双重保障）
+2. 在 tapas-sys 中添加 `onConsoleMessage`（便于调试）
+3. 测试验证优化后的实现
+
+---
+
+## 相关文档
+
+- `WEBVIEW_IMPLEMENTATION_COMPARISON.md` - 详细对比分析
+- `WEBVIEW_FIX_RECOMMENDATIONS.md` - 修复建议
+- `WEBVIEW_DEMO_CONNECTION_VERIFICATION.md` - Demo 验证结果
+