react-native-gradient-mask 0.1.0-beta.1

package/rn-gradient-mask-design.md

@@ -0,0 +1,657 @@
+# CharacterChatScreen 動畫與 Mask 系統分析
+
+> 此文檔是 `rn-gradient-mask` 原生套件重新設計的重要參考
+
+---
+
+## 一、現有架構概覽
+
+### 元件層級結構
+
+```
+CharacterChatScreen
+├── BackgroundImage (角色背景圖)
+├── Header (Animated.View, opacity: uiOpacity)
+├── overlayUI (Animated.View, opacity: uiOpacity)
+│   ├── Coin
+│   ├── Affinity
+│   └── RemainingFreeMessageBubble
+├── Animated.View (translateY 跟隨鍵盤)
+│   ├── messagesContainer (Animated.View, opacity: uiOpacity)
+│   │   └── MaskedView
+│   │       ├── maskElement: AnimatedMaskGradient
+│   │       │   ├── LinearGradient (漸層)
+│   │       │   └── Animated.View (白色覆蓋層)
+│   │       └── children: FlashList (訊息列表)
+│   └── InputArea (Animated.View, opacity: uiOpacity)
+```
+
+---
+
+## 二、主要動畫系統
+
+### 1. uiOpacity - 整體 UI 淡入/淡出
+
+| 項目 | 說明 |
+|-----|------|
+| **來源** | `useUIState.ts:28` |
+| **類型** | `Animated.Value` (React Native 原生動畫) |
+| **驅動方式** | `Animated.timing()` with `useNativeDriver: true` |
+| **用途** | 控制整體 UI 元素的顯示/隱藏 |
+
+**影響範圍**：
+- Header (`opacity: uiOpacity`)
+- overlayUI (Coin, Affinity 等)
+- messagesContainer
+- InputArea 區域
+
+**動畫程式碼**：
+```typescript
+// 檔案: index.tsx:1105, 1903
+Animated.timing(uiOpacity, {
+  toValue: 1,
+  duration: 300,
+  useNativeDriver: true,
+}).start();
+```
+
+---
+
+### 2. maskOpacity - 漸層遮罩效果 ⭐ 重點
+
+| 項目 | 說明 |
+|-----|------|
+| **來源** | `useMaskedView.ts:12` |
+| **類型** | `SharedValue<number>` (Reanimated) |
+| **驅動方式** | `withTiming()` |
+| **用途** | 控制 MaskedView 的漸層透明效果強度 |
+
+**動畫程式碼**：
+```typescript
+// 檔案: useMaskedView.ts:25-28
+maskOpacity.value = withTiming(want ? 1 : 0, {
+  duration: want ? 600 : 400,  // 顯示 600ms, 隱藏 400ms
+  easing: want ? Easing.in(Easing.quad) : Easing.out(Easing.quad),
+});
+```
+
+**AnimatedMaskGradient 內部實作**：
+```typescript
+// 檔案: AnimatedMaskGradient.tsx:28-30
+const overlayAnimatedStyle = useAnimatedStyle(() => ({
+  opacity: 1 - maskOpacity.value,
+}));
+
+// 結構
+<View>
+  <LinearGradient colors={BASE_MASK_COLORS} locations={MASK_GRADIENT_LOCATIONS} />
+  <Animated.View style={[{ backgroundColor: "white" }, overlayAnimatedStyle]} />
+</View>
+```
+
+**漸層配置**：
+```typescript
+// 檔案: AnimatedMaskGradient.tsx:9-13
+const MASK_GRADIENT_ALPHA_STOPS = [0, 0, 0.2, 0.6, 0.9, 1];
+const MASK_GRADIENT_LOCATIONS = [0, 0.42, 0.45, 0.48, 0.5, 1];
+const BASE_MASK_COLORS = MASK_GRADIENT_ALPHA_STOPS.map(
+  stop => `rgba(255,255,255,${stop})`  // 注意：使用白色
+);
+```
+
+---
+
+### 3. translateY - 鍵盤跟隨動畫
+
+| 項目 | 說明 |
+|-----|------|
+| **來源** | `useKeyboardAnimations.ts:45` |
+| **類型** | `Animated.Value` |
+| **驅動方式** | `Animated.timing()` with `useNativeDriver: true` |
+| **用途** | 讓訊息區域和輸入框跟隨鍵盤移動 |
+
+---
+
+## 三、使用者旅程與動畫觸發時機
+
+### 場景 1: 進入聊天畫面
+
+```
+使用者動作: 點擊角色進入聊天
+─────────────────────────────────────
+1. 畫面載入
+   └─ uiOpacity: 0 → 1 (300ms 淡入)
+   └─ maskOpacity: 0 (無遮罩效果，訊息完全可見)
+
+2. 歷史訊息載入完成
+   └─ maskOpacity 維持 0
+```
+
+### 場景 2: 滾動訊息列表
+
+```
+使用者動作: 開始滾動訊息
+─────────────────────────────────────
+1. onScrollBeginDrag 觸發
+   └─ setMaskTargetVisible(true)
+   └─ maskOpacity: 0 → 1 (600ms, ease-in-quad)
+   └─ 效果: 頂部漸變透明，露出背景圖
+
+2. 滾動結束 (onMomentumScrollEnd)
+   └─ 延遲後 setMaskTargetVisible(false)
+   └─ maskOpacity: 1 → 0 (400ms, ease-out-quad)
+   └─ 效果: 漸層消失，訊息完全可見
+```
+
+### 場景 3: 點擊背景隱藏 UI
+
+```
+使用者動作: 點擊背景區域
+─────────────────────────────────────
+1. tapGesture 觸發
+   └─ uiOpacity: 1 → 0 (隱藏所有 UI)
+   └─ maskOpacity: 0 (重置)
+
+2. 再次點擊
+   └─ uiOpacity: 0 → 1 (顯示所有 UI)
+```
+
+### 場景 4: 離開聊天畫面
+
+```
+使用者動作: 點擊返回按鈕
+─────────────────────────────────────
+1. handleBackPress 觸發
+   └─ cancelAnimation(maskOpacity)
+   └─ maskOpacity.value = 0 (立即重置)
+   └─ navigation.goBack()
+```
+
+---
+
+## 四、效能瓶頸分析
+
+| 動畫 | 類型 | 效能評估 | 問題 |
+|-----|------|---------|------|
+| **uiOpacity** | RN Animated | ✅ 好 | `useNativeDriver: true`，在原生層執行 |
+| **translateY** | RN Animated | ✅ 好 | `useNativeDriver: true`，在原生層執行 |
+| **maskOpacity** | Reanimated | ⚠️ 有問題 | 需要更深入分析 |
+
+### maskOpacity 效能問題詳解
+
+```
+現有架構:
+┌─────────────────────────────────────────────────────────┐
+│  JS Thread                                               │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │ useMaskedView                                    │    │
+│  │   maskOpacity = useSharedValue(0)               │    │
+│  │   maskOpacity.value = withTiming(1, {...})      │    │
+│  └─────────────────────────────────────────────────┘    │
+│                           │                              │
+│                           ▼                              │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │ AnimatedMaskGradient                             │    │
+│  │   useAnimatedStyle(() => ({                     │    │
+│  │     opacity: 1 - maskOpacity.value  ◄── 每幀執行 │    │
+│  │   }))                                            │    │
+│  └─────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────┐
+│  Native (MaskedView - JS 元件)                          │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │ maskElement 每幀重新渲染？                        │    │
+│  │ FlashList 可能受影響                             │    │
+│  └─────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────┘
+```
+
+**問題點**:
+1. `MaskedView` 是 JS 元件，不是純原生
+2. `useAnimatedStyle` 雖然在 UI thread 執行，但 MaskedView 的 re-render 可能在 JS thread
+3. 動畫期間可能影響 FlashList 的滾動效能
+
+---
+
+## 五、相關檔案清單
+
+### 核心檔案
+
+| 檔案 | 用途 |
+|-----|------|
+| `src/screens/CharacterChatScreen/index.tsx` | 主畫面，整合所有動畫 |
+| `src/hooks/useMaskedView.ts` | maskOpacity 狀態與動畫控制 |
+| `src/screens/CharacterChatScreen/hooks/useUIState.ts` | uiOpacity 狀態 |
+| `src/screens/CharacterChatScreen/hooks/useKeyboardAnimations.ts` | translateY 鍵盤動畫 |
+| `src/screens/CharacterChatScreen/components/AnimatedMaskGradient.tsx` | MaskedView 的 maskElement |
+
+### 第三方依賴
+
+| 套件 | 用途 |
+|-----|------|
+| `@react-native-masked-view/masked-view` | 提供 MaskedView 元件 |
+| `react-native-linear-gradient` | 提供 LinearGradient 元件 |
+| `react-native-reanimated` | 提供 SharedValue 和 worklet 動畫 |
+
+---
+
+## 六、rn-gradient-mask 目標
+
+將以下結構：
+```
+MaskedView (JS)
+├── maskElement: AnimatedMaskGradient (JS + Reanimated)
+│   ├── LinearGradient
+│   └── Animated.View (白色覆蓋層)
+└── children: FlashList
+```
+
+替換為：
+```
+RNGradientMask (純原生)
+├── 原生漸層 mask 渲染
+├── 原生 maskOpacity 控制
+└── children: FlashList
+```
+
+### 設計原則
+
+1. **原生層處理所有 mask 渲染** - 不再依賴 MaskedView + LinearGradient
+2. **maskOpacity 透過 Reanimated 驅動原生 prop** - 使用 `useAnimatedProps`
+3. **保持相同的 API 介面** - 讓遷移成本最低
+4. **保持相同的動畫時序** - 600ms 顯示, 400ms 隱藏
+
+---
+
+## 七、rn-gradient-mask 功能需求
+
+### 目標用法
+
+```tsx
+// 取代 MaskedView + AnimatedMaskGradient
+<RNGradientMask
+  style={{ flex: 1 }}
+  maskOpacity={maskOpacity}  // SharedValue<number> 或 number
+  colors={GRADIENT_COLORS}
+  locations={GRADIENT_LOCATIONS}
+  direction="top"
+>
+  <FlashList ... />
+</RNGradientMask>
+```
+
+### Props 規格
+
+| Prop | 類型 | 預設值 | 說明 |
+|-----|------|-------|------|
+| `colors` | `string[]` | 必填 | 漸層顏色陣列 (black alpha 格式) |
+| `locations` | `number[]` | 均勻分布 | 顏色位置 (0-1) |
+| `direction` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | 漸層方向 |
+| `maskOpacity` | `SharedValue<number>` 或 `number` | `0` | 漸層效果強度 (0-1) |
+| `style` | `ViewStyle` | - | 容器樣式 |
+| `children` | `ReactNode` | - | 子元件 |
+
+### maskOpacity 行為定義
+
+```
+maskOpacity = 0
+├── 無漸層效果
+├── 子元件完全可見（不透明）
+└── 使用情境：一般瀏覽狀態
+
+maskOpacity = 1
+├── 完整漸層效果
+├── 頂部透明，露出背景圖
+└── 使用情境：滾動時顯示背景
+```
+
+### 漸層配置（對應 AnimatedMaskGradient）
+
+```typescript
+// 原有配置 (白色格式，用於 MaskedView)
+const MASK_GRADIENT_ALPHA_STOPS = [0, 0, 0.2, 0.6, 0.9, 1];
+const MASK_GRADIENT_LOCATIONS = [0, 0.42, 0.45, 0.48, 0.5, 1];
+const BASE_MASK_COLORS = MASK_GRADIENT_ALPHA_STOPS.map(
+  stop => `rgba(255,255,255,${stop})`
+);
+
+// 轉換為原生格式 (黑色格式，用於 RNGradientMask)
+const NATIVE_GRADIENT_COLORS = [
+  "rgba(0,0,0,0)",    // 0% - 透明
+  "rgba(0,0,0,0)",    // 42% - 透明
+  "rgba(0,0,0,0.2)",  // 45% - 20% 不透明
+  "rgba(0,0,0,0.6)",  // 48% - 60% 不透明
+  "rgba(0,0,0,0.9)",  // 50% - 90% 不透明
+  "rgba(0,0,0,1)",    // 100% - 不透明
+];
+const NATIVE_GRADIENT_LOCATIONS = [0, 0.42, 0.45, 0.48, 0.5, 1];
+```
+
+---
+
+## 八、動畫驅動方案比較
+
+### 方案 A：JS 層驅動（useAnimatedProps）✅ 採用（主要方案）
+
+```
+JS 層 (useMaskedView)
+├── maskOpacity = useSharedValue(0)
+├── setMaskTargetVisible(true/false) 觸發動畫
+└── withTiming() 控制動畫時序
+         │
+         ▼
+    useAnimatedProps
+         │
+         ▼
+    原生層接收 prop 變化，只做渲染
+```
+
+**優點**：
+- JS 完全控制動畫時序、easing
+- 可以隨時 cancelAnimation
+- 可以根據業務邏輯動態調整
+
+**缺點**：
+- 需要 JS ↔ Native 通訊
+- Reanimated worklet 仍在執行
+
+---
+
+### 方案 B：原生層驅動（Native Animation）🔄 備用方案
+
+```
+JS 層
+├── 呼叫原生方法：showMask() / hideMask()
+└── 不管動畫細節
+         │
+         ▼
+原生層
+├── iOS: CABasicAnimation
+├── Android: ValueAnimator
+└── 完全在原生層執行動畫
+```
+
+**優點**：
+- 動畫完全在原生層，效能最佳
+- 不需要 Reanimated
+
+**缺點**：
+- JS 無法即時控制動畫進度
+- 難以實現 cancelAnimation
+- 動畫時序寫死在原生層，修改需要重新編譯
+- 無法根據業務邏輯動態調整
+
+**備用原因**：
+- 如果方案 A 的效能無法滿足需求，可考慮切換到此方案
+- 需要實作原生方法：`showMask(duration: number)` 和 `hideMask(duration: number)`
+
+---
+
+### 方案 C：混合模式（記錄但不採用）
+
+```
+JS 層
+├── maskOpacity prop (靜態值或 SharedValue)
+├── 簡單情況：直接傳數值
+└── 動畫情況：用 useAnimatedProps
+         │
+         ▼
+原生層
+├── 接收 maskOpacity prop
+├── 如果需要，可選擇性內建簡單動畫
+└── 但主要依賴 JS 驅動
+```
+
+**說明**：
+- 此方案結合了方案 A 和 B 的優點
+- 目前不採用，但保留作為未來可能的優化方向
+
+---
+
+### 決定：採用方案 A（JS 層驅動 + useAnimatedProps）
+
+**狀態**：✅ 已決定採用，待實作
+
+**考量因素**：
+1. **效能**：useAnimatedProps 在 UI thread 執行，效能已經很好
+2. **靈活性**：JS 完全控制動畫，可隨時調整
+3. **維護性**：改動在 JS 層，不需重新編譯原生
+4. **現有架構**：`useMaskedView` 已經用 Reanimated，遷移成本最低
+5. **必要功能**：`cancelAnimation` 是必要的（離開畫面時需要立即停止）
+
+**備用方案**：方案 B（原生層驅動）
+- 如果方案 A 的效能無法滿足需求，可考慮切換到方案 B
+- 方案 B 的實作細節已記錄，可作為未來優化方向
+
+---
+
+## 九、實作設計
+
+### 架構圖
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  JS 層                                                       │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ useMaskedView (保留不變)                              │    │
+│  │   maskOpacity = useSharedValue(0)                   │    │
+│  │   setMaskTargetVisible(true/false)                  │    │
+│  │   withTiming() 控制動畫                              │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                           │                                  │
+│                           ▼                                  │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ AnimatedGradientMask (新元件)                        │    │
+│  │   useAnimatedProps(() => ({                         │    │
+│  │     maskOpacity: maskOpacity.value                  │    │
+│  │   }))                                               │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼ (prop 變化直接更新原生層)
+┌─────────────────────────────────────────────────────────────┐
+│  原生層 (RNGradientMask)                                     │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ iOS: CAGradientLayer + solidMaskLayer               │    │
+│  │ Android: LinearGradient + PorterDuff.Mode.DST_IN    │    │
+│  │                                                     │    │
+│  │ maskOpacity prop 變化 → 更新 solidMaskLayer opacity │    │
+│  │ (不觸發 JS re-render)                               │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                           │                                  │
+│                           ▼                                  │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ children: FlashList (不受動畫影響)                   │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 元件 API
+
+```tsx
+// 靜態用法
+<GradientMask
+  colors={GRADIENT_COLORS}
+  locations={GRADIENT_LOCATIONS}
+  direction="top"
+  maskOpacity={1}  // 固定值
+>
+  <FlashList ... />
+</GradientMask>
+
+// 動畫用法 (搭配 useMaskedView)
+const { maskOpacity } = useMaskedView();
+
+<AnimatedGradientMask
+  colors={GRADIENT_COLORS}
+  locations={GRADIENT_LOCATIONS}
+  direction="top"
+  maskOpacity={maskOpacity}  // SharedValue<number>
+>
+  <FlashList ... />
+</AnimatedGradientMask>
+```
+
+---
+
+## 十、檔案修改清單
+
+### 需要修改的檔案
+
+| 檔案 | 修改內容 |
+|-----|---------|
+| `ios/RNGradientMask/RNGradientMask.swift` | 確認 maskOpacity prop 正確運作 |
+| `ios/RNGradientMask/RNGradientMaskManager.m` | 確認導出 maskOpacity |
+| `android/.../RNGradientMaskView.kt` | 確認 maskOpacity prop 正確運作 |
+| `android/.../RNGradientMaskManager.kt` | 確認導出 maskOpacity |
+| `src/native-modules/rn-gradient-mask/index.tsx` | 簡化，移除多餘的 hook |
+
+### 需要刪除的檔案
+
+| 檔案 | 原因 |
+|-----|------|
+| `src/native-modules/rn-gradient-mask/hooks/index.ts` | 多餘，直接使用 useMaskedView |
+
+### CharacterChatScreen 遷移
+
+```tsx
+// 移除
+import MaskedView from "@react-native-masked-view/masked-view";
+import AnimatedMaskGradient from "./components/AnimatedMaskGradient";
+
+// 新增
+import { AnimatedGradientMask, GRADIENT_PRESETS } from "@/native-modules/rn-gradient-mask";
+
+// 移除 maskElement
+const maskElement = useMemo(() => (
+  <AnimatedMaskGradient maskOpacity={maskOpacity} style={styles.gradientMask} />
+), [maskOpacity]);
+
+// 替換 MaskedView
+<MaskedView style={{ flex: 1 }} maskElement={maskElement}>
+  <FlashList ... />
+</MaskedView>
+
+// 改為
+<AnimatedGradientMask
+  style={{ flex: 1 }}
+  colors={GRADIENT_PRESETS.CHAT_MASK.colors}
+  locations={GRADIENT_PRESETS.CHAT_MASK.locations}
+  direction="top"
+  maskOpacity={maskOpacity}
+>
+  <FlashList ... />
+</AnimatedGradientMask>
+```
+
+---
+
+## 十一、實作步驟
+
+### 階段 1：驗證現有原生實作
+
+1. 確認 iOS `RNGradientMask.swift` 的 maskOpacity 行為正確
+2. 確認 Android `RNGradientMaskView.kt` 的 maskOpacity 行為正確
+3. 使用 `CharacterChatScreenV3DTestNative` 測試頁面驗證
+
+### 階段 2：簡化 JS 層
+
+1. 移除 `hooks/index.ts`（useGradientMaskAnimation）
+2. 更新 `index.tsx`：
+   - `GradientMask`: 接受 `maskOpacity: number`
+   - `AnimatedGradientMask`: 接受 `maskOpacity: SharedValue<number>`
+3. 確認 `useAnimatedProps` 正確驅動原生 prop
+
+### 階段 3：整合測試
+
+1. 更新 `CharacterChatScreenV3DTestNative` 使用 `useMaskedView`
+2. 比較效能與原有 MaskedView 方案
+3. 確認所有使用情境正常：
+   - 滾動顯示/隱藏 mask
+   - 離開畫面時 cancelAnimation
+   - 點擊背景重置 mask
+
+### 階段 4：正式遷移（如果測試通過）
+
+1. 在 `CharacterChatScreen` 替換 MaskedView
+2. 移除 `AnimatedMaskGradient.tsx` 元件
+3. 更新相關 import
+
+---
+
+## 十二、預設漸層配置
+
+```typescript
+// src/native-modules/rn-gradient-mask/index.tsx
+
+export const GRADIENT_PRESETS = {
+  /**
+   * 聊天畫面遮罩 - 對應 AnimatedMaskGradient 的配置
+   * 頂部 42% 透明，漸層過渡到不透明
+   */
+  CHAT_MASK: {
+    colors: [
+      "rgba(0,0,0,0)",    // 0% - 透明
+      "rgba(0,0,0,0)",    // 42% - 透明
+      "rgba(0,0,0,0.2)",  // 45% - 20% 不透明
+      "rgba(0,0,0,0.6)",  // 48% - 60% 不透明
+      "rgba(0,0,0,0.9)",  // 50% - 90% 不透明
+      "rgba(0,0,0,1)",    // 100% - 不透明
+    ],
+    locations: [0, 0.42, 0.45, 0.48, 0.5, 1],
+  },
+} as const;
+```
+
+---
+
+## 十三、實作狀態與待辦事項
+
+### 當前實作狀態
+
+| 功能 | 狀態 | 說明 |
+|-----|------|------|
+| 基本漸層遮罩 | ✅ 已完成 | iOS 和 Android 原生實作完成 |
+| maskOpacity 靜態控制 | ✅ 已完成 | 支援 0-1 數值控制 |
+| 漸層方向支援 | ✅ 已完成 | top/bottom/left/right |
+| 顏色和位置配置 | ✅ 已完成 | colors 和 locations props |
+| **maskOpacity 動畫** | ⏳ **待實作** | 使用方案 A（JS 層驅動） |
+| AnimatedGradientMask 元件 | ⏳ **待實作** | 支援 SharedValue 動畫 |
+| useAnimatedProps 整合 | ⏳ **待實作** | Reanimated 動畫驅動 |
+
+### 動畫方案決定
+
+- **主要方案**：方案 A（JS 層驅動 + useAnimatedProps）
+  - 狀態：✅ 已決定採用，待實作
+  - 實作方式：使用 `useAnimatedProps` 將 Reanimated `SharedValue` 傳遞給原生層
+  - 動畫時序：顯示 600ms (ease-in-quad)，隱藏 400ms (ease-out-quad)
+
+- **備用方案**：方案 B（原生層驅動）
+  - 狀態：🔄 備用方案，暫不實作
+  - 使用時機：如果方案 A 效能無法滿足需求時考慮
+  - 實作方式：原生層內建 CABasicAnimation (iOS) / ValueAnimator (Android)
+
+### 待實作項目
+
+1. **AnimatedGradientMask 元件**
+   - 創建支援 `SharedValue<number>` 的動畫版本元件
+   - 使用 `useAnimatedProps` 將動畫值傳遞給原生層
+   - 保持與靜態 `GradientMask` 元件相同的 API
+
+2. **動畫時序配置**
+   - 顯示動畫：600ms，ease-in-quad
+   - 隱藏動畫：400ms，ease-out-quad
+   - 支援 `cancelAnimation` 功能
+
+3. **測試與驗證**
+   - 驗證動畫流暢度
+   - 測試與 FlashList 的相容性
+   - 效能對比測試（與原有 MaskedView 方案）
+
+### 備註
+
+- 當前版本已符合基本需求（靜態 maskOpacity 控制）
+- 動畫功能待後續實作，不影響基本使用
+- 方案 B 的實作細節已記錄，可作為未來優化方向