@beppla/tapas-ui 1.5.12 → 1.5.13

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

@@ -1,100 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,201 +0,0 @@
-# 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

@@ -1,188 +0,0 @@
-# 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 组合
-