@beppla/tapas-ui 1.5.13 → 1.5.15

package/package/module/Image/PreviewImg/README.md

@@ -0,0 +1,100 @@
+# PreviewImg
+
+图片预览覆盖层组件，用于全屏展示图片集合，支持缩略图导航和前后切换。
+
+## 功能特性
+
+- ✅ 全屏图片预览
+- ✅ 缩略图导航
+- ✅ 前后切换功能
+- ✅ 点击缩略图快速跳转
+- ✅ 背景蒙层支持
+- ✅ 响应式尺寸
+
+## 安装使用
+
+```tsx
+import PreviewImg from '@beppla/tapas-ui/components/Image/PreviewImg';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | boolean | false | 是否显示预览层 |
+| data | IFileState[] | - | 图片数据数组 |
+| defaultIndex | number | 0 | 默认显示的图片索引 |
+| onClose | () => void | - | 关闭预览时的回调 |
+| onSelect | (index: number) => void | - | 选择图片时的回调 |
+
+## IFileState 结构
+
+```tsx
+interface IFileState {
+  fileId?: string;
+  fileName?: string;
+  fileUrl?: string;
+}
+```
+
+## 使用示例
+
+### 基础用法
+```tsx
+import PreviewImg from '@beppla/tapas-ui/components/Image/PreviewImg';
+import { useState } from 'react';
+
+export default function App() {
+  const [visible, setVisible] = useState(false);
+
+  const images = [
+    { fileUrl: "https://example.com/image1.jpg", fileName: "Image 1" },
+    { fileUrl: "https://example.com/image2.jpg", fileName: "Image 2" },
+  ];
+
+  return (
+    <PreviewImg
+      isVisible={visible}
+      data={images}
+      onClose={() => setVisible(false)}
+    />
+  );
+}
+```
+
+### 带选择回调
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={0}
+  onClose={() => setVisible(false)}
+  onSelect={(index) => {
+    console.log(`Selected image at index: ${index}`);
+  }}
+/>
+```
+
+### 多张图片预览
+```tsx
+const images = [
+  { fileId: "1", fileUrl: "https://example.com/photo1.jpg", fileName: "Photo 1" },
+  { fileId: "2", fileUrl: "https://example.com/photo2.jpg", fileName: "Photo 2" },
+  { fileId: "3", fileUrl: "https://example.com/photo3.jpg", fileName: "Photo 3" },
+];
+
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={1}
+  onClose={() => setVisible(false)}
+/>
+```
+
+## 注意事项
+
+- 单张图片时不显示前后导航按钮
+- 点击背景蒙层会关闭预览
+- 点击关闭按钮（X 图标）会关闭预览
+- 缩略图边框颜色为橙色（#F55523）表示当前选中
+- 仅支持 web 平台的 HTML img 标签

package/package/module/Image/README.md

@@ -0,0 +1,88 @@
+# PreviewImg
+
+图片预览组件，支持全屏遮罩层展示图片，提供缩略图列表导航和左右切换功能。适合商品图片、订单附件等多图预览场景。
+
+## 功能特性
+
+- ✅ 全屏遮罩层预览（Overlay）
+- ✅ 多图浏览：底部缩略图列表导航
+- ✅ 左右切换按钮（chevron_left / chevron_right）
+- ✅ 首张/末张图片自动禁用对应切换按钮
+- ✅ 点击缩略图快速跳转
+- ✅ 当前选中缩略图高亮边框
+- ✅ 点击遮罩或关闭按钮关闭预览
+- ✅ 自定义默认展示图片索引（defaultIndex）
+
+## 安装使用
+
+```tsx
+import { PreviewImg } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | `false` | 是否显示预览 |
+| data | `IFileState[]` | - | 图片数据数组（必填） |
+| defaultIndex | `number` | `0` | 默认展示的图片索引 |
+| onClose | `() => void` | - | 关闭回调（必填） |
+| onSelect | `(index: number) => void` | - | 图片选择回调（预留） |
+
+### IFileState
+
+```tsx
+interface IFileState {
+  fileId?: string;
+  fileName?: string;
+  fileUrl?: string;
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [visible, setVisible] = useState(false);
+const images = [
+  { fileId: '1', fileName: 'photo1.jpg', fileUrl: 'https://example.com/1.jpg' },
+  { fileId: '2', fileName: 'photo2.jpg', fileUrl: 'https://example.com/2.jpg' },
+];
+
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 指定默认图片
+
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={images}
+  defaultIndex={2}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 单张图片（无切换按钮）
+
+```tsx
+<PreviewImg
+  isVisible={visible}
+  data={[{ fileUrl: 'https://example.com/single.jpg' }]}
+  onClose={() => setVisible(false)}
+/>
+```
+
+## 注意事项
+
+- 组件使用 HTML `<img>` 标签渲染，仅适用于 Web 平台
+- 主图高度自适应：`window.innerHeight - 200`
+- 缩略图固定尺寸 84x84，选中态边框色 `#F55523`
+- 单张图片时不显示左右切换按钮
+- 预览层使用 `@rneui/themed` 的 Overlay 组件
+- 需在 `ThemeProvider` 内使用

package/package/module/Input/FOCUS_FIX_SUMMARY.md

@@ -0,0 +1,201 @@
+# Android Input 焦点跳动问题修复总结
+
+## 修复时间
+2025-12-04
+
+## 修复方案
+采用**方案 1 + 方案 3 组合**：添加焦点状态检查 + 改进延迟 blur 逻辑
+
+## 修复内容
+
+### 方案 1：添加焦点状态检查
+
+#### 1. 添加焦点状态跟踪
+- 新增 `isFocusedRef`：使用 ref 存储 `isFocused` 的最新值，避免在 useEffect 中需要依赖
+- 新增 `lastFocusTimeRef`：记录最后一次 focus 的时间戳
+- 新增 `FOCUS_SWITCH_PROTECTION_PERIOD`：焦点切换保护期（200ms）
+
+### 2. 改进 `handleFocus` 逻辑（方案 3）
+
+```typescript
+const handleFocus = useCallback((e: any) => {
+  // 清除可能存在的 blur 延迟
+  if (blurTimeoutRef.current) {
+    clearTimeout(blurTimeoutRef.current);
+    blurTimeoutRef.current = null;
+  }
+  
+  // 方案 3：清除所有其他 Input 的重新聚焦标记
+  // 当当前 Input 获得焦点时，清除其他 Input 的 shouldRefocusRef，防止焦点跳动
+  inputInstancesRef.forEach((ref) => {
+    if (ref !== shouldRefocusRef) {
+      ref.current = false;
+    }
+  });
+  
+  // 清除当前组件的重新聚焦标记，因为当前组件已经获得焦点
+  shouldRefocusRef.current = false;
+  // 记录 focus 时间戳，用于焦点切换保护期判断
+  lastFocusTimeRef.current = Date.now();
+  // 更新 ref 和 state
+  isFocusedRef.current = true;
+  setIsFocused(true);
+  onFocus?.(e);
+}, [onFocus]);
+```
+
+**改进点**（方案 3）：
+- **全局实例管理**：使用全局 `inputInstancesRef` Set 存储所有 Input 实例的 `shouldRefocusRef`
+- **主动清除其他 Input 标记**：当当前 Input 获得焦点时，立即清除所有其他 Input 的 `shouldRefocusRef`，防止它们错误地重新聚焦
+- 记录 focus 时间戳，用于后续保护期判断
+- 同步更新 `isFocusedRef` 和 `isFocused` state
+
+#### 4. 改进 `handleBlur` 逻辑
+```typescript
+// 在 blur 时同步更新 ref
+isFocusedRef.current = false;
+setIsFocused(false);
+```
+
+**改进点**：
+- 确保 ref 和 state 同步更新
+
+### 方案 3：改进延迟 blur 逻辑
+
+#### 1. 全局 Input 实例管理
+
+```typescript
+// 方案 3：全局 Input 实例管理器，用于清除其他 Input 的重新聚焦标记
+const inputInstancesRef = new Set<React.MutableRefObject<boolean>>();
+
+// 注册当前 Input 实例到全局管理器
+useEffect(() => {
+  if (Platform.OS === 'android' && enableBridgelessFix) {
+    inputInstancesRef.add(shouldRefocusRef);
+    return () => {
+      inputInstancesRef.delete(shouldRefocusRef);
+    };
+  }
+}, [enableBridgelessFix]);
+```
+
+**作用**：
+- 维护所有 Input 实例的引用，用于在 focus 时清除其他 Input 的重新聚焦标记
+- 组件卸载时自动清理，避免内存泄漏
+
+#### 2. 在 `handleFocus` 中清除其他 Input 的标记
+
+见上面的 `handleFocus` 逻辑部分。
+
+### 方案 1：核心修复 - `keyboardDidShow` 监听器
+
+添加了三层检查机制：
+
+#### 检查 1：当前组件是否已聚焦
+```typescript
+if (isFocusedRef.current) {
+  // 当前组件已经聚焦，清除重新聚焦标记，避免后续误操作
+  shouldRefocusRef.current = false;
+  return;
+}
+```
+**作用**：如果当前组件已经聚焦，说明键盘是由当前组件触发的，不需要重新聚焦。
+
+#### 检查 2：焦点切换保护期
+```typescript
+const timeSinceLastFocus = Date.now() - lastFocusTimeRef.current;
+if (timeSinceLastFocus < FOCUS_SWITCH_PROTECTION_PERIOD) {
+  // 在保护期内，说明可能有其他 Input 正在获得焦点，不执行重新聚焦
+  shouldRefocusRef.current = false;
+  return;
+}
+```
+**作用**：如果在 200ms 内有 focus 事件（可能是其他 Input 获得焦点），不执行重新聚焦，避免焦点跳动。
+
+#### 检查 3：异步执行时的状态再次检查
+```typescript
+if (shouldRefocusRef.current && !isFocusedRef.current && inputRef.current) {
+  // 执行重新聚焦逻辑
+}
+```
+**作用**：在异步执行时再次检查状态，避免在异步执行期间状态已改变。
+
+## 方案组合优势
+
+**方案 1 + 方案 3 组合**提供了双重保障机制：
+
+1. **方案 3（主动清除）**：在 Input B focus 时立即清除 Input A 的标记，从源头阻止焦点跳动
+2. **方案 1（状态检查）**：即使标记未被清除，也会通过状态检查阻止重新聚焦，作为备用保障
+
+这种组合方式确保了：
+- ✅ **更快的响应**：方案 3 在 focus 时立即清除，不需要等待键盘事件
+- ✅ **更强的保障**：方案 1 提供额外的状态检查，即使方案 3 失效也能阻止焦点跳动
+- ✅ **更好的兼容性**：两种机制互补，适应不同的时序场景
+
+## 修复原理
+
+### 问题根源
+当两个 Input 切换焦点时：
+1. Input A blur → 设置 `shouldRefocusRef.current = true`
+2. Input B focus → 触发键盘显示
+3. 键盘显示 → 所有 Input 的 `keyboardDidShow` 监听器都被触发
+4. Input A 的监听器检测到标记 → 错误地重新聚焦 Input A
+
+### 修复机制
+
+**方案 1：三层检查机制**
+通过三层检查，确保只有在以下条件**全部满足**时才执行重新聚焦：
+1. ✅ 当前组件**未聚焦**（`!isFocusedRef.current`）
+2. ✅ 不在焦点切换保护期内（最近 200ms 内没有 focus 事件）
+3. ✅ 确实需要重新聚焦（`shouldRefocusRef.current === true`）
+
+**方案 3：主动清除机制**
+当 Input B 获得焦点时，立即清除 Input A 的 `shouldRefocusRef`，双重保障：
+1. ✅ Input B focus → 立即清除 Input A 的 `shouldRefocusRef.current = false`
+2. ✅ 即使 Input A 的 `keyboardDidShow` 被触发，也会因为标记已被清除而不执行重新聚焦
+
+## 修复效果
+
+### 修复前
+```
+Input A blur → Input B focus → 键盘显示 → Input A 错误重新聚焦 → 焦点跳动
+```
+
+### 修复后（方案 1 + 方案 3 组合）
+```
+Input A blur → Input B focus → 立即清除 Input A 的标记 → 键盘显示 → Input A 检测到标记已清除 → 不执行重新聚焦 → 焦点正常切换
+```
+
+**双重保障**：
+1. **方案 3 主动清除**：Input B focus 时立即清除 Input A 的标记
+2. **方案 1 状态检查**：即使标记未被清除，也会通过状态检查阻止重新聚焦
+
+## 测试场景
+
+修复后需要测试以下场景：
+
+1. ✅ **单个 Input 聚焦**：点击单个 Input，键盘正常显示，无焦点跳动
+2. ✅ **两个 Input 切换**：在 Input A 和 Input B 之间切换，焦点正常切换，无跳动
+3. ✅ **快速连续切换**：快速连续点击多个 Input，焦点正常切换
+4. ✅ **点击外部区域**：点击 Input 外部区域，键盘正常隐藏
+5. ✅ **ScrollView 中的 Input**：在 ScrollView 中的 Input 正常聚焦
+
+## 兼容性
+
+- ✅ 保持对 RN 0.77 Bridgeless 模式的兼容
+- ✅ 不影响 iOS 平台（仅在 Android 上生效）
+- ✅ 可以通过 `enableBridgelessFix` 禁用修复
+- ✅ 向后兼容，不影响现有功能
+
+## 代码变更文件
+
+- `components/Input/Input.tsx`
+
+## 相关文档
+
+- `components/Input/FOCUS_ISSUE_ANALYSIS.md` - 问题分析文档
+
+---
+
+**修复完成** ✅
+

package/package/module/Input/FOCUS_ISSUE_ANALYSIS.md

@@ -0,0 +1,188 @@
+# Android Input 组件焦点跳动问题分析
+
+## 问题描述
+
+在 Android 平台上，当两个 Input 组件切换焦点时，出现焦点来回跳动的问题：
+
+1. **第一个 Input** 失去焦点（blur）
+2. **第二个 Input** 获取焦点（focus）
+3. 焦点又**跳回第一个 Input**
+4. 形成来回跳动的循环
+
+## 问题场景重现
+
+```
+用户操作流程：
+1. 点击 Input A → Input A 获得焦点
+2. 点击 Input B → Input A 触发 blur，Input B 触发 focus
+3. 键盘显示 → 触发 keyboardDidShow 事件
+4. ❌ Input A 的 keyboardDidShow 监听器被触发
+5. ❌ Input A 检测到 shouldRefocusRef.current === true
+6. ❌ Input A 自动重新聚焦
+7. ❌ 焦点从 Input B 跳回 Input A
+```
+
+## 根本原因分析
+
+### 1. 全局键盘事件监听器冲突
+
+**问题代码位置**：`components/Input/Input.tsx:140-188`
+
+```typescript
+const keyboardDidShowListener = Keyboard.addListener('keyboardDidShow', () => {
+  if (shouldRefocusRef.current) {
+    // 尝试重新聚焦
+    inputRef.current.focus();
+  }
+});
+```
+
+**问题分析**：
+- `keyboardDidShow` 是**全局事件**，所有 Input 组件实例都会收到
+- 当第二个 Input 获得焦点并触发键盘显示时，**第一个 Input 的监听器也会被触发**
+- 第一个 Input 检测到 `shouldRefocusRef.current === true`（在 blur 时设置的），就会尝试重新聚焦
+- 这导致焦点被错误地抢回第一个 Input
+
+### 2. 缺少焦点状态检查
+
+**问题代码位置**：`components/Input/Input.tsx:143-187`
+
+当前逻辑只检查 `shouldRefocusRef.current`，但没有检查：
+- 当前是否有其他 Input 已经获得焦点
+- 当前组件是否真的需要重新聚焦
+- 是否正在切换焦点到其他 Input
+
+### 3. 延迟 blur 与键盘事件的时序问题
+
+**问题代码位置**：`components/Input/Input.tsx:90-123`
+
+```typescript
+const handleBlur = useCallback((e: any) => {
+  if (Platform.OS === 'android' && enableBridgelessFix) {
+    shouldRefocusRef.current = true;  // ⚠️ 问题：立即设置标记
+    blurTimeoutRef.current = setTimeout(() => {
+      // 延迟 500-800ms 后才真正执行 blur
+    }, delay);
+  }
+}, [onBlur, enableBridgelessFix]);
+```
+
+**时序问题**：
+1. Input A blur → 设置 `shouldRefocusRef.current = true`
+2. Input B focus → 触发键盘显示
+3. 键盘显示 → 触发 `keyboardDidShow`（所有 Input 都收到）
+4. Input A 的监听器检测到标记 → 重新聚焦 Input A
+5. 此时 Input B 刚获得焦点，就被 Input A 抢走了
+
+### 4. 缺少组件实例标识
+
+当前实现中，每个 Input 组件实例都是独立的，但它们共享同一个全局键盘事件。当多个 Input 同时存在时，无法区分：
+- 哪个 Input 应该响应键盘事件
+- 哪个 Input 正在失去焦点
+- 哪个 Input 正在获得焦点
+
+## 问题流程图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 用户点击 Input B（Input A 当前有焦点）                        │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Input A 触发 handleBlur                                  │
+│    - shouldRefocusRef.current = true                        │
+│    - 设置延迟 blur（500-800ms）                             │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. Input B 触发 handleFocus                                 │
+│    - 清除 Input B 的 blurTimeout                            │
+│    - setIsFocused(true)                                      │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. 键盘显示 → 触发全局 keyboardDidShow 事件                 │
+│    - 所有 Input 组件的监听器都被触发                         │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 4. Input A 的 keyboardDidShow 监听器执行                    │
+│    - 检测到 shouldRefocusRef.current === true              │
+│    - ❌ 错误地重新聚焦 Input A                              │
+└─────────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 5. 焦点从 Input B 跳回 Input A                             │
+│    - 形成焦点跳动问题                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 解决方案设计
+
+### 方案 1：添加焦点状态检查（推荐）
+
+**核心思路**：在 `keyboardDidShow` 监听器中，检查当前组件是否真的需要重新聚焦。
+
+**实现要点**：
+1. 检查 `isFocused` 状态，如果已经是聚焦状态，不执行重新聚焦
+2. 检查是否有其他 Input 正在获得焦点（通过事件时间戳判断）
+3. 添加短暂的"焦点切换保护期"，在保护期内不执行重新聚焦
+
+### 方案 2：使用全局焦点管理器
+
+**核心思路**：创建一个全局的焦点管理器，统一管理所有 Input 的焦点状态。
+
+**实现要点**：
+1. 创建一个全局的焦点管理器 Context
+2. 记录当前聚焦的 Input 实例 ID
+3. 只有当前聚焦的 Input 才能响应键盘事件
+
+### 方案 3：改进延迟 blur 逻辑
+
+**核心思路**：在 blur 时，如果检测到有新的 focus 事件，立即取消重新聚焦标记。
+
+**实现要点**：
+1. 在 `handleFocus` 中，清除所有其他 Input 的 `shouldRefocusRef` 标记
+2. 使用全局事件或 Context 来通知其他 Input 组件
+
+## 推荐方案：方案 1 + 方案 3 组合
+
+结合两种方案的优点：
+1. **在 `handleFocus` 中清除其他 Input 的重新聚焦标记**
+2. **在 `keyboardDidShow` 中检查 `isFocused` 状态**
+3. **添加焦点切换保护期**
+
+## 修复要点
+
+1. ✅ 在 `handleFocus` 中，通过全局机制清除其他 Input 的 `shouldRefocusRef`
+2. ✅ 在 `keyboardDidShow` 中，检查 `isFocused` 状态，如果已聚焦则不执行
+3. ✅ 添加焦点切换保护期（例如 200ms），在保护期内不执行重新聚焦
+4. ✅ 改进事件时序处理，确保 blur 和 focus 事件正确处理
+
+## 测试场景
+
+修复后需要测试以下场景：
+
+1. ✅ 单个 Input 点击后键盘正常显示
+2. ✅ 两个 Input 之间正常切换焦点
+3. ✅ 快速连续切换多个 Input
+4. ✅ 点击 Input 外部区域，键盘正常隐藏
+5. ✅ 在 ScrollView 中的 Input 正常聚焦
+
+## 风险评估
+
+- **低风险**：方案 1 和方案 3 都是对现有逻辑的改进，不会破坏现有功能
+- **兼容性**：修复后仍然保持对 RN 0.77 Bridgeless 模式的兼容
+- **性能影响**：几乎无影响，只是添加了状态检查
+
+---
+
+**分析完成时间**：2025-12-04
+**问题优先级**：高
+**建议修复方案**：方案 1 + 方案 3 组合
+