@beppla/tapas-ui 1.4.31 → 1.4.33

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 组合
+

package/package/module/Input/README.md

@@ -0,0 +1,157 @@
+# TapasInput 组件
+
+基于 `@rneui/themed` 的 Input 组件封装，提供了额外的功能和样式定制。
+
+## 功能特性
+
+- ✅ 自定义标签位置和样式
+- ✅ 支持必填标识
+- ✅ **RN 0.77 Bridgeless 模式兼容性修复**（Android 平台）
+
+## RN 0.77 Bridgeless 模式兼容性
+
+### 问题说明
+
+React Native 0.77 引入的 Bridgeless 模式在 Android 平台上可能导致输入框在点击后键盘弹出但立即失焦的问题。这是 RN 0.77 的已知问题。
+
+### 组件库修复
+
+`TapasInput` 组件已经内置了针对 Bridgeless 模式的兼容性修复：
+
+- **自动检测 Bridgeless 模式**：组件会自动检测是否运行在 Bridgeless 模式下
+- **延迟 blur 处理**：在 Android 上延迟处理 blur 事件，给键盘足够时间显示
+- **自动重新聚焦**：当键盘显示时，如果输入框失焦，会自动尝试重新聚焦
+- **智能延迟时间**：Bridgeless 模式下使用更长的延迟时间（800ms）来适应新架构
+
+### 使用方式
+
+默认情况下，兼容性修复是**自动启用**的：
+
+```tsx
+import { TapasInput } from '@beppla/tapas-ui';
+
+<TapasInput
+  label="用户名"
+  placeholder="请输入用户名"
+  // enableBridgelessFix={true} // 默认启用，无需手动设置
+/>
+```
+
+如果遇到问题，可以尝试禁用修复：
+
+```tsx
+<TapasInput
+  label="用户名"
+  enableBridgelessFix={false} // 禁用 Bridgeless 修复
+/>
+```
+
+### 应用端配置建议
+
+虽然组件库已经提供了修复，但应用端也可以进行一些配置来进一步优化体验：
+
+#### 1. AndroidManifest.xml 配置
+
+在 `android/app/src/main/AndroidManifest.xml` 中，确保 `windowSoftInputMode` 设置为 `adjustResize`：
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:windowSoftInputMode="adjustResize"
+  ...>
+</activity>
+```
+
+#### 2. ScrollView 配置
+
+如果输入框在 ScrollView 中，确保添加 `keyboardShouldPersistTaps`：
+
+```tsx
+<ScrollView
+  keyboardShouldPersistTaps="handled"
+  keyboardDismissMode="none"
+>
+  <TapasInput ... />
+</ScrollView>
+```
+
+#### 3. Layout 组件
+
+如果使用 `Layout` 组件，它已经自动配置了 `keyboardShouldPersistTaps`。
+
+## API
+
+### TapasInputProps
+
+继承自 `@rneui/themed` 的 `InputProps`，并添加了以下属性：
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `labelPosition` | `"top" \| "middle"` | `"top"` | 标签位置 |
+| `defaultShowLabel` | `boolean` | `false` | 是否默认显示标签 |
+| `labelBg` | `string` | - | 标签背景色 |
+| `labelColor` | `string` | - | 标签文字颜色 |
+| `required` | `boolean` | `false` | 是否必填（显示 * 标识） |
+| `enableBridgelessFix` | `boolean` | `true` | 是否启用 RN 0.77 Bridgeless 模式兼容性修复 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+<TapasInput
+  label="用户名"
+  placeholder="请输入用户名"
+  value={username}
+  onChangeText={setUsername}
+/>
+```
+
+### 必填字段
+
+```tsx
+<TapasInput
+  label="邮箱"
+  placeholder="请输入邮箱"
+  required
+  value={email}
+  onChangeText={setEmail}
+/>
+```
+
+### 自定义标签样式
+
+```tsx
+<TapasInput
+  label="密码"
+  labelBg="#ffffff"
+  labelColor="#333333"
+  secureTextEntry
+  value={password}
+  onChangeText={setPassword}
+/>
+```
+
+### 禁用 Bridgeless 修复
+
+```tsx
+<TapasInput
+  label="备注"
+  enableBridgelessFix={false}
+  value={notes}
+  onChangeText={setNotes}
+/>
+```
+
+## 注意事项
+
+1. **Bridgeless 模式检测**：组件会自动检测是否运行在 Bridgeless 模式下，无需手动配置
+2. **性能影响**：兼容性修复会添加一些延迟和监听器，但对性能影响很小
+3. **向后兼容**：修复不会影响非 Bridgeless 模式或 iOS 平台的正常使用
+4. **问题反馈**：如果遇到问题，可以尝试禁用 `enableBridgelessFix` 或联系组件库维护者
+
+## 相关链接
+
+- [React Native 0.77 发布说明](https://reactnative.dev/blog)
+- [Bridgeless 模式文档](https://reactnative.dev/docs/the-new-architecture/landing-page)
+

package/package/module/Loading/README.md

@@ -0,0 +1,160 @@
+# Loading 组件
+
+一个全屏加载组件，提供优雅的加载动画效果。
+
+## 功能特性
+
+- 全屏模态展示
+- 淡入淡出动画效果
+- 可自定义Logo和背景色
+- 支持自定义默认Logo和尺寸
+- 自动循环动画
+- 支持透明背景
+
+## 基本用法
+
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+
+// 基础用法
+<Loading visible={isLoading} />
+
+// 自定义背景色
+<Loading 
+  visible={isLoading} 
+  backgroundColor="rgba(0, 0, 0, 0.8)" 
+/>
+
+// 自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./custom-logo.png')} 
+/>
+```
+
+## 避免硬编码图片引用问题
+
+### 问题描述
+之前的版本中，Loading 组件内部硬编码了 `require("../../assets/logo.png")`，这会导致在使用组件库时出现模块解析错误。
+
+### 解决方案
+现在提供了多种方式来解决这个问题：
+
+#### 1. 使用 `defaultLogo` 属性（推荐）
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  defaultLogo={customLogo}
+/>
+```
+
+#### 2. 使用 `logo` 属性
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  logo={customLogo}
+/>
+```
+
+#### 3. 在应用初始化时设置全局默认Logo
+```tsx
+// 在应用入口处
+import { initTapasUI } from '@beppla/tapas-ui';
+import defaultLogo from './assets/default-logo.png';
+
+initTapasUI({
+  defaultLoadingLogo: defaultLogo
+});
+
+// 在组件中使用
+<Loading visible={isLoading} />
+```
+
+## API 参考
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `visible` | `boolean` | `false` | 是否显示加载状态 |
+| `logo` | `ImageSourcePropType` | `undefined` | 自定义Logo图片（最高优先级） |
+| `defaultLogo` | `ImageSourcePropType` | `undefined` | 默认Logo图片（优先级高于内置默认） |
+| `backgroundColor` | `string` | `theme.colors.grey1` | 背景颜色 |
+| `size` | `number` | `200` | Logo尺寸（像素） |
+
+### 图片优先级说明
+
+1. **`logo`** - 最高优先级，直接使用传入的图片
+2. **`defaultLogo`** - 中等优先级，使用传入的默认图片
+3. **内置默认图片** - 最低优先级，作为最后的回退选项
+
+## 使用场景
+
+- 应用启动加载
+- 数据请求等待
+- 页面切换过渡
+- 长时间操作提示
+
+## 注意事项
+
+1. **避免硬编码引用**：不要依赖组件内部的默认图片，建议使用 `defaultLogo` 属性
+2. **图片格式支持**：支持 PNG、JPG、SVG 等常见图片格式
+3. **性能考虑**：Logo 图片建议使用适当尺寸，避免过大的图片文件
+4. **主题适配**：背景色会自动适配主题，也可以手动覆盖
+
+## 迁移指南
+
+### 从旧版本迁移
+
+**旧版本（有问题）：**
+```tsx
+// 直接使用，可能报错
+<Loading visible={isLoading} />
+```
+
+**新版本（推荐）：**
+```tsx
+// 设置自定义默认Logo
+<Loading 
+  visible={isLoading} 
+  defaultLogo={require('./assets/logo.png')}
+/>
+
+// 或者使用自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./assets/logo.png')}
+/>
+```
+
+### 批量替换示例
+
+如果您的项目中有多个地方使用了 Loading 组件，可以创建一个包装组件：
+
+```tsx
+// components/AppLoading.tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import appLogo from '../assets/app-logo.png';
+
+export const AppLoading = (props) => (
+  <Loading 
+    {...props} 
+    defaultLogo={appLogo}
+  />
+);
+
+// 在项目中使用
+import { AppLoading } from './components/AppLoading';
+
+<AppLoading visible={isLoading} />
+```
+
+## 示例代码
+
+完整的示例项目可以参考 Storybook 中的演示，或者查看 `stories/Loading/Loading.stories.tsx` 文件。