expo-splash-screen2 1.0.0 → 1.1.0

package/README.md

@@ -15,6 +15,7 @@
   - [WebView Mode](#webview-mode)
   - [ResponsiveImage Mode](#responsiveimage-mode)
   - [Normal Mode](#normal-mode)
+  - [Blend Mode](#blend-mode)
   - [Dark Mode Support](#dark-mode-support)
 - [📱 Platform-Specific Details](#-platform-specific-details)
   - [iOS Configuration](#-ios-configuration)
@@ -143,7 +144,7 @@ Your app now has a custom WebView-based splash screen. For more advanced configu
 
 ### Display Modes
 
-`expo-splash-screen2` provides three splash screen modes to fit different use cases:
+`expo-splash-screen2` provides four splash screen modes to fit different use cases:
 
 #### `webview` Mode
 
@@ -171,6 +172,16 @@ Display a centered image with fixed width (default 100px), maintaining aspect ra
 - **Supports dark mode** with separate image and background color
 - Best for logo-centric splash screens
 
+#### `blend` Mode
+
+Combine a `.9.png` background image with WebView HTML content for enhanced splash screen experience.
+
+- Uses `.9.png` image as system splash screen background
+- WebView container uses transparent background (recommended) for seamless transition
+- Full HTML/JavaScript/CSS support in WebView overlay
+- Perfect for achieving smooth transition from system splash to custom animated splash
+- Best for apps requiring both native performance and rich animations
+
 ### Dark Mode Support (Normal Mode)
 
 `expo-splash-screen2` supports per-appearance splash screens that respond to system appearance changes on iOS 13+ and Android 10+.
@@ -397,6 +408,12 @@ Display a centered image with fixed width, maintaining aspect ratio. Supports da
   </tbody>
 </table>
 
+#### `blend` Mode
+
+Combine a `.9.png` background image with WebView HTML content for enhanced splash screen experience. The system splash screen uses the `.9.png` image as background, and the WebView container uses transparent background (recommended) for seamless transition.
+
+**Note**: Blend mode combines the visual appearance of `responsiveImage` mode (`.9.png` background) with the functionality of `webview` mode (HTML content overlay). This creates a smooth transition from the system splash screen to the custom animated splash screen.
+
 ## 💻 Installation
 
 ### Installation in managed Expo projects
@@ -508,6 +525,15 @@ Display HTML content with full JavaScript/CSS support:
 }
 ```
 
+> **Note**: For `webview` and `blend` modes, you must install `react-native-web` to build web files:
+> ```bash
+> npm install react-native-web
+> # or
+> pnpm add react-native-web
+> # or
+> yarn add react-native-web
+> ```
+
 #### WebView Mode Options
 
 | Option | Type | Required | Description |
@@ -577,6 +603,55 @@ Display a centered image with fixed width:
 | `imageWidth` | `number` | No | Image width in dp/pt (default: `100`) |
 | `dark` | `object` | No | Dark mode configuration |
 
+### Blend Mode
+
+Combine a `.9.png` background image with WebView HTML content for enhanced splash screen experience:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-splash-screen2",
+        {
+          "mode": "blend",
+          "image": "./assets/splash-background.9.png"
+        }
+      ]
+    ]
+  }
+}
+```
+
+> **Note**: For `webview` and `blend` modes, you must install `react-native-web` to build web files:
+> ```bash
+> npm install react-native-web
+> # or
+> pnpm add react-native-web
+> # or
+> yarn add react-native-web
+> ```
+
+#### Blend Mode Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `mode` | `"blend"` | Yes | Enable blend mode (`.9.png` background + WebView) |
+| `image` | `string` | Yes | Path to background image (supports `.9.png`) |
+| `localHtmlPath` | `string` | No | Path to custom HTML file |
+
+**How Blend Mode Works:**
+
+- **System Splash Screen**: Uses `.9.png` image as background (Android 12+ system splash screen)
+- **WebView Container**: Uses transparent background (recommended) to show the system splash screen background for seamless visual continuity
+- **HTML Overlay**: Displays custom HTML content in WebView on top of the background
+- **Transition**: Smooth transition from system splash to WebView splash without visual gaps
+
+This mode is ideal when you want:
+- Native performance of system splash screen
+- Rich animations and interactivity from HTML/WebView
+- Seamless visual transition between system and custom splash screens
+
 ### Dark Mode Support
 
 Enable dark mode support in `normal` mode by adding the `dark` configuration:
@@ -694,6 +769,28 @@ For Normal mode, the plugin:
    - Add width constraint (default 100pt) to Image View
 4. Modify `AppDelegate.swift` to add image container view with width constraints
 
+#### Blend Mode
+
+For Blend mode, the plugin:
+
+1. **Copies background image**: Places `.9.png` image file as `splash_background_image.{ext}` in `ios/{projectName}/` directory
+2. **Copies HTML files**: Places HTML files from `expo-splash-web/dist` or `localHtmlPath` to `ios/{projectName}/` directory
+3. **Modifies `SplashScreen.storyboard`**: Sets full-screen background image with `scaleAspectFill` content mode (same as ResponsiveImage mode)
+4. **Modifies `AppDelegate.swift`**: Adds WebView overlay code with transparent background (recommended)
+
+**Manual steps** (if needed):
+
+1. Copy `.9.png` background image to `ios/{projectName}/splash_background_image.{ext}`
+2. Copy HTML file to `ios/{projectName}/index.html`
+3. Modify `SplashScreen.storyboard`:
+   - Set Image View to use `splash_background_image` image
+   - Set Content Mode to `Aspect Fill` for full-screen coverage
+   - Set background color (fallback)
+4. Modify `AppDelegate.swift`:
+   - Add WebView container code (see plugin source for template)
+   - Set WebView container background to transparent (recommended) for seamless transition
+5. Add image and HTML files to Xcode project file references
+
 ### 🤖 Android Configuration
 
 The plugin automatically:
@@ -815,6 +912,45 @@ For Normal mode, the plugin:
    ```
 7. Modify `MainActivity.kt` to add image container view with fixed width (default 100dp)
 
+#### Blend Mode
+
+For Blend mode, the plugin:
+
+1. **Copies background image**: Places `.9.png` image as `splash_background_image.{ext}` in `android/app/src/main/res/drawable/`
+2. **Copies HTML file**: Places HTML file from `expo-splash-web/dist/index.html` or `localHtmlPath` to `android/app/src/main/assets/index.html`
+3. **Creates CustomSplashActivity**: Generates `SplashScreen2Activity.kt` with transparent WebView container background (recommended)
+4. **Modifies AndroidManifest.xml**: Adds `SplashScreen2Activity` as launcher activity, sets `MainActivity` theme to `Theme.App.SplashScreen`
+5. **Modifies MainActivity.kt**: Adds WebView container code with transparent background (recommended)
+6. **Modifies styles.xml**: Updates `Theme.App.SplashScreen` to use `.9.png` background image
+7. **Creates colors.xml**: Creates `splashscreen_background` color resource
+8. **Updates build.gradle**: Adds `androidx.core:core-splashscreen` dependency
+
+**Manual steps** (if needed):
+
+1. Copy `.9.png` background image to `android/app/src/main/res/drawable/splash_background_image.{ext}`
+2. Copy HTML file to `android/app/src/main/assets/index.html`
+3. Create `SplashScreen2Activity.kt` in `android/app/src/main/java/{packageName}/`:
+   - Set WebView container background to transparent (recommended, see plugin templates)
+4. Modify `AndroidManifest.xml`:
+   - Add `SplashScreen2Activity` as launcher activity
+   - Set `MainActivity` theme to `Theme.App.SplashScreen` (same as splash screen theme)
+5. Modify `MainActivity.kt`:
+   - Add WebView container code
+   - Set WebView container background to transparent (recommended) for seamless transition
+6. Update `res/values/styles.xml`:
+   ```xml
+   <style name="Theme.App.SplashScreen" parent="Theme.SplashScreen">
+     <item name="android:windowBackground">@drawable/splash_background_image</item>
+   </style>
+   ```
+7. Create `res/values/colors.xml`:
+   ```xml
+   <resources>
+     <color name="splashscreen_background">#FFFFFF</color>
+   </resources>
+   ```
+8. Add `androidx.core:core-splashscreen:1.0.1` dependency to `build.gradle`
+
 ### Manual Regeneration
 
 If you need to regenerate native projects with the latest plugin changes:

package/README.zh.md

@@ -15,6 +15,7 @@
   - [WebView 模式](#webview-模式)
   - [ResponsiveImage 模式](#responsiveimage-模式)
   - [Normal 模式](#normal-模式)
+  - [Blend 模式](#blend-模式)
   - [深色模式支持](#深色模式支持)
 - [📱 平台特定详情](#-平台特定详情)
   - [iOS 配置](#-ios-配置)
@@ -143,7 +144,7 @@ npx expo prebuild
 
 ### 显示模式
 
-`expo-splash-screen2` 提供三种启动屏幕模式以适应不同的使用场景：
+`expo-splash-screen2` 提供四种启动屏幕模式以适应不同的使用场景：
 
 #### `webview` 模式
 
@@ -171,6 +172,16 @@ npx expo prebuild
 - **支持深色模式**，具有独立的图片和背景颜色
 - 最适合以 Logo 为中心的启动屏幕
 
+#### `blend` 模式
+
+结合 `.9.png` 背景图片和 WebView HTML 内容，增强开屏体验。
+
+- 使用 `.9.png` 图片作为系统启动屏幕背景
+- WebView 容器使用透明背景（推荐），实现无缝过渡
+- WebView 覆盖层支持完整的 HTML/JavaScript/CSS
+- 完美实现从系统启动屏幕到自定义动画启动屏幕的平滑过渡
+- 最适合需要原生性能和丰富动画的应用
+
 ### 深色模式支持（Normal 模式）
 
 `expo-splash-screen2` 支持根据系统外观变化而响应的启动屏幕，适用于 iOS 13+ 和 Android 10+。
@@ -397,6 +408,12 @@ export default function RootLayout() {
   </tbody>
 </table>
 
+#### `blend` 模式
+
+结合 `.9.png` 背景图片和 WebView HTML 内容，增强开屏体验。系统启动屏幕使用 `.9.png` 图片作为背景，WebView 容器使用透明背景（推荐），实现无缝过渡。
+
+**注意**：Blend 模式结合了 `responsiveImage` 模式的视觉效果（`.9.png` 背景）和 `webview` 模式的功能（HTML 内容覆盖层）。这实现了从系统启动屏幕到自定义动画启动屏幕的平滑过渡。
+
 ## 💻 安装
 
 ### 在托管 Expo 项目中安装
@@ -508,6 +525,15 @@ npx expo prebuild
 }
 ```
 
+> **注意**：对于 `webview` 和 `blend` 模式，必须安装 `react-native-web` 来打包 web 文件：
+> ```bash
+> npm install react-native-web
+> # 或
+> pnpm add react-native-web
+> # 或
+> yarn add react-native-web
+> ```
+
 #### WebView 模式选项
 
 | 选项 | 类型 | 必需 | 描述 |
@@ -577,6 +603,55 @@ npx expo prebuild
 | `imageWidth` | `number` | 否 | 图片宽度（单位：dp/pt，默认：`100`） |
 | `dark` | `object` | 否 | 深色模式配置 |
 
+### Blend 模式
+
+结合 `.9.png` 背景图片和 WebView HTML 内容，增强开屏体验：
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-splash-screen2",
+        {
+          "mode": "blend",
+          "image": "./assets/splash-background.9.png"
+        }
+      ]
+    ]
+  }
+}
+```
+
+> **注意**：对于 `webview` 和 `blend` 模式，必须安装 `react-native-web` 来打包 web 文件：
+> ```bash
+> npm install react-native-web
+> # 或
+> pnpm add react-native-web
+> # 或
+> yarn add react-native-web
+> ```
+
+#### Blend 模式选项
+
+| 选项 | 类型 | 必需 | 描述 |
+|--------|------|----------|-------------|
+| `mode` | `"blend"` | 是 | 启用混合模式（`.9.png` 背景 + WebView） |
+| `image` | `string` | 是 | 背景图片路径（支持 `.9.png`） |
+| `localHtmlPath` | `string` | 否 | 自定义 HTML 文件路径 |
+
+**Blend 模式工作原理：**
+
+- **系统启动屏幕**：使用 `.9.png` 图片作为背景（Android 12+ 系统启动屏幕）
+- **WebView 容器**：使用透明背景（推荐），以显示系统启动屏幕背景，实现视觉连续性
+- **HTML 覆盖层**：在背景之上显示自定义 HTML 内容
+- **过渡效果**：从系统启动屏幕到 WebView 启动屏幕的平滑过渡，无视觉间隙
+
+此模式适用于以下场景：
+- 需要系统启动屏幕的原生性能
+- 需要 HTML/WebView 的丰富动画和交互性
+- 需要系统启动屏幕和自定义启动屏幕之间的无缝视觉过渡
+
 ### 深色模式支持
 
 通过在 `normal` 模式中添加 `dark` 配置来启用深色模式支持：
@@ -694,6 +769,28 @@ npx expo prebuild
    - 为 Image View 添加宽度约束（默认 100pt）
 4. 修改 `AppDelegate.swift` 以添加带有宽度约束的图片容器视图
 
+#### Blend 模式
+
+对于 Blend 模式，插件：
+
+1. **复制背景图片**：将 `.9.png` 图片文件作为 `splash_background_image.{ext}` 放置在 `ios/{projectName}/` 目录
+2. **复制 HTML 文件**：将 HTML 文件从 `expo-splash-web/dist` 或 `localHtmlPath` 放置到 `ios/{projectName}/` 目录
+3. **修改 `SplashScreen.storyboard`**：设置全屏背景图片，使用 `scaleAspectFill` 内容模式（与 ResponsiveImage 模式相同）
+4. **修改 `AppDelegate.swift`**：添加 WebView 覆盖层代码，使用透明背景（推荐）
+
+**手动步骤**（如需要）：
+
+1. 将 `.9.png` 背景图片复制到 `ios/{projectName}/splash_background_image.{ext}`
+2. 将 HTML 文件复制到 `ios/{projectName}/index.html`
+3. 修改 `SplashScreen.storyboard`：
+   - 将 Image View 设置为使用 `splash_background_image` 图片
+   - 将 Content Mode 设置为 `Aspect Fill` 以实现全屏覆盖
+   - 设置背景颜色（备用）
+4. 修改 `AppDelegate.swift`：
+   - 添加 WebView 容器代码（参见插件源代码中的模板）
+   - 将 WebView 容器背景设置为透明（推荐），实现无缝过渡
+5. 将图片和 HTML 文件添加到 Xcode 项目文件引用
+
 ### 🤖 Android 配置
 
 插件自动：
@@ -815,6 +912,45 @@ npx expo prebuild
    ```
 7. 修改 `MainActivity.kt` 以添加带有固定宽度（默认 100dp）的图片容器视图
 
+#### Blend 模式
+
+对于 Blend 模式，插件：
+
+1. **复制背景图片**：将 `.9.png` 图片作为 `splash_background_image.{ext}` 放置在 `android/app/src/main/res/drawable/`
+2. **复制 HTML 文件**：将 HTML 文件从 `expo-splash-web/dist/index.html` 或 `localHtmlPath` 放置到 `android/app/src/main/assets/index.html`
+3. **创建 CustomSplashActivity**：生成 `SplashScreen2Activity.kt`，使用透明 WebView 容器背景（推荐）
+4. **修改 AndroidManifest.xml**：将 `SplashScreen2Activity` 添加为启动活动，将 `MainActivity` 主题设置为 `Theme.App.SplashScreen`
+5. **修改 MainActivity.kt**：添加 WebView 容器代码，使用透明背景（推荐）
+6. **修改 styles.xml**：更新 `Theme.App.SplashScreen` 以使用 `.9.png` 背景图片
+7. **创建 colors.xml**：创建 `splashscreen_background` 颜色资源
+8. **更新 build.gradle**：添加 `androidx.core:core-splashscreen` 依赖
+
+**手动步骤**（如需要）：
+
+1. 将 `.9.png` 背景图片复制到 `android/app/src/main/res/drawable/splash_background_image.{ext}`
+2. 将 HTML 文件复制到 `android/app/src/main/assets/index.html`
+3. 在 `android/app/src/main/java/{packageName}/` 中创建 `SplashScreen2Activity.kt`：
+   - 将 WebView 容器背景设置为透明（推荐，参见插件模板）
+4. 修改 `AndroidManifest.xml`：
+   - 将 `SplashScreen2Activity` 添加为启动活动
+   - 将 `MainActivity` 主题设置为 `Theme.App.SplashScreen`（与启动屏幕主题相同）
+5. 修改 `MainActivity.kt`：
+   - 添加 WebView 容器代码
+   - 将 WebView 容器背景设置为透明（推荐），实现无缝过渡
+6. 更新 `res/values/styles.xml`：
+   ```xml
+   <style name="Theme.App.SplashScreen" parent="Theme.SplashScreen">
+     <item name="android:windowBackground">@drawable/splash_background_image</item>
+   </style>
+   ```
+7. 创建 `res/values/colors.xml`：
+   ```xml
+   <resources>
+     <color name="splashscreen_background">#FFFFFF</color>
+   </resources>
+   ```
+8. 在 `build.gradle` 中添加 `androidx.core:core-splashscreen:1.0.1` 依赖
+
 ### 手动重新生成
 
 如果您需要使用最新的插件更改重新生成原生项目：