Skip to content

Commit

Permalink
feat(splash-screen): Use Android 12 Splash Screen API (#1011)
Browse files Browse the repository at this point in the history 

Co-authored-by: Chace Daniels <chace@chaces-mbp.lan>
Co-authored-by: jcesarmobile <jcesarmobile@gmail.com>
  • Loading branch information
@ItsChaceD @jcesarmobile
3 people committed Jul 21, 2022
1 parent dc67e7b commit 79185ad
Show file tree
Hide file tree
Showing 4 changed files with 190 additions and 25 deletions.
67 changes: 49 additions & 18 deletions splash-screen/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ await SplashScreen.hide();

// Show the splash for an indefinite amount of time:
await SplashScreen.show({
autoHide: false
autoHide: false,
});

// Show the splash for two seconds and then automatically hide it:
await SplashScreen.show({
showDuration: 2000,
autoHide: true
autoHide: true,
});
```

Expand All @@ -37,7 +37,6 @@ If you want to be sure the splash screen never disappears before your app is rea

If, instead, you want to show the splash screen for a fixed amount of time, set `launchShowDuration` in your [Capacitor configuration file](https://capacitorjs.com/docs/config).


## Background Color

In certain conditions, especially if the splash screen does not fully cover the device screen, it might happen that the app screen is visible around the corners (due to transparency). Instead of showing a transparent color, you can set a `backgroundColor` to cover those areas.
Expand All @@ -51,6 +50,7 @@ If you want to show a spinner on top of the splash screen, set `showSpinner` to
You can customize the appearance of the spinner with the following configuration.

For Android, `androidSpinnerStyle` has the following options:

- `horizontal`
- `small`
- `large` (default)
Expand All @@ -59,6 +59,7 @@ For Android, `androidSpinnerStyle` has the following options:
- `largeInverse`

For iOS, `iosSpinnerStyle` has the following options:

- `large` (default)
- `small`

Expand All @@ -71,21 +72,21 @@ To set the color of the spinner use `spinnerColor`, values are either `#RRGGBB`

These config values are available:

| Prop | Type | Description | Default | Since |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----- |
| **`launchShowDuration`** | <code>number</code> | How long to show the launch splash screen when autoHide is enabled (in ms) | <code>500</code> | 1.0.0 |
| **`launchAutoHide`** | <code>boolean</code> | Whether to auto hide the splash after launchShowDuration. | <code>true</code> | 1.0.0 |
| **`backgroundColor`** | <code>string</code> | Color of the background of the Splash Screen in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if `useDialog` is true. | | 1.0.0 |
| **`androidSplashResourceName`** | <code>string</code> | Name of the resource to be used as Splash Screen. Only available on Android. | <code>splash</code> | 1.0.0 |
| **`androidScaleType`** | <code>'CENTER' \| 'CENTER_CROP' \| 'CENTER_INSIDE' \| 'FIT_CENTER' \| 'FIT_END' \| 'FIT_START' \| 'FIT_XY' \| 'MATRIX'</code> | The [ImageView.ScaleType](https://developer.android.com/reference/android/widget/ImageView.ScaleType) used to scale the Splash Screen image. Doesn't work if `useDialog` is true. Only available on Android. | <code>FIT_XY</code> | 1.0.0 |
| **`showSpinner`** | <code>boolean</code> | Show a loading spinner on the Splash Screen. Doesn't work if `useDialog` is true. | | 1.0.0 |
| **`androidSpinnerStyle`** | <code>'horizontal' \| 'small' \| 'large' \| 'inverse' \| 'smallInverse' \| 'largeInverse'</code> | Style of the Android spinner. Doesn't work if `useDialog` is true. | <code>large</code> | 1.0.0 |
| **`iosSpinnerStyle`** | <code>'small' \| 'large'</code> | Style of the iOS spinner. Doesn't work if `useDialog` is true. Only available on iOS. | <code>large</code> | 1.0.0 |
| **`spinnerColor`** | <code>string</code> | Color of the spinner in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if `useDialog` is true. | | 1.0.0 |
| **`splashFullScreen`** | <code>boolean</code> | Hide the status bar on the Splash Screen. Only available on Android. | | 1.0.0 |
| **`splashImmersive`** | <code>boolean</code> | Hide the status bar and the software navigation buttons on the Splash Screen. Only available on Android. | | 1.0.0 |
| **`layoutName`** | <code>string</code> | If `useDialog` is set to true, configure the Dialog layout. If `useDialog` is not set or false, use a layout instead of the ImageView. Only available on Android. | | 1.1.0 |
| **`useDialog`** | <code>boolean</code> | Use a Dialog instead of an ImageView. If `layoutName` is not configured, it will use a layout that uses the splash image as background. Only available on Android. | | 1.1.0 |
| Prop | Type | Description | Default | Since |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- |
| **`launchShowDuration`** | <code>number</code> | How long to show the launch splash screen when autoHide is enabled (in ms) | <code>500</code> | 1.0.0 |
| **`launchAutoHide`** | <code>boolean</code> | Whether to auto hide the splash after launchShowDuration. | <code>true</code> | 1.0.0 |
| **`backgroundColor`** | <code>string</code> | Color of the background of the Splash Screen in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if `useDialog` is true or on launch when using the Android 12 API. | | 1.0.0 |
| **`androidSplashResourceName`** | <code>string</code> | Name of the resource to be used as Splash Screen. Doesn't work on launch when using the Android 12 API. Only available on Android. | <code>splash</code> | 1.0.0 |
| **`androidScaleType`** | <code>'CENTER' \| 'CENTER_CROP' \| 'CENTER_INSIDE' \| 'FIT_CENTER' \| 'FIT_END' \| 'FIT_START' \| 'FIT_XY' \| 'MATRIX'</code> | The [ImageView.ScaleType](https://developer.android.com/reference/android/widget/ImageView.ScaleType) used to scale the Splash Screen image. Doesn't work if `useDialog` is true or on launch when using the Android 12 API. Only available on Android. | <code>FIT_XY</code> | 1.0.0 |
| **`showSpinner`** | <code>boolean</code> | Show a loading spinner on the Splash Screen. Doesn't work if `useDialog` is true on launch when using the Android 12 API. | | 1.0.0 |
| **`androidSpinnerStyle`** | <code>'horizontal' \| 'small' \| 'large' \| 'inverse' \| 'smallInverse' \| 'largeInverse'</code> | Style of the Android spinner. Doesn't work if `useDialog` is true on launch when using the Android 12 API. | <code>large</code> | 1.0.0 |
| **`iosSpinnerStyle`** | <code>'small' \| 'large'</code> | Style of the iOS spinner. Doesn't work if `useDialog` is true. Only available on iOS. | <code>large</code> | 1.0.0 |
| **`spinnerColor`** | <code>string</code> | Color of the spinner in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if `useDialog` is true on launch when using the Android 12 API. | | 1.0.0 |
| **`splashFullScreen`** | <code>boolean</code> | Hide the status bar on the Splash Screen. Doesn't work on launch when using the Android 12 API. Only available on Android. | | 1.0.0 |
| **`splashImmersive`** | <code>boolean</code> | Hide the status bar and the software navigation buttons on the Splash Screen. Doesn't work on launch when using the Android 12 API. Only available on Android. | | 1.0.0 |
| **`layoutName`** | <code>string</code> | If `useDialog` is set to true, configure the Dialog layout. If `useDialog` is not set or false, use a layout instead of the ImageView. Doesn't work on launch when using the Android 12 API. Only available on Android. | | 1.1.0 |
| **`useDialog`** | <code>boolean</code> | Use a Dialog instead of an ImageView. If `layoutName` is not configured, it will use a layout that uses the splash image as background. Doesn't work on launch when using the Android 12 API. Only available on Android. | | 1.1.0 |

### Examples

Expand Down Expand Up @@ -155,6 +156,36 @@ To use splash screen images named something other than `splash.png`, set `androi
</style>
```

### Android 12 Splash Screen API

_**This only affects the launch splash screen and is not used when utilizing the programmatic `show()` method.**_

To enable the new recommended **[Android 12 Splash Screen API](https://developer.android.com/guide/topics/ui/splash-screen)** in SDK Versions 30 or below:

_This is enabled by default and required for SDK version 31+._

- Add `$coreSplashScreenVersion` to the `variables.gradle` file.
_See Variables Section for more information_

- Add `implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"` in the dependencies section of `/android/app/build.gradle`.

- In `android/app/src/main/res/values/styles.xml`, edit the theme `parent` attribute on the Applications's MainActivity Theme to `Theme.SplashScreen` and add desired options to the theme.

```xml
<style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
<item name="android:background">@drawable/splash</item>
</style>
```

**NOTE**: Some issues may exist on SDK >= 31 when using the new API for the splash screen, which pertain to the splash screen only showing when launched from the launcher icon.
**[Google Issue Tracker](https://issuetracker.google.com/issues/205021357)**

## Variables

This plugin will use the following project variables (defined in your app's `variables.gradle` file):

`$coreSplashScreenVersion` version of `androidx.core:core-splashscreen:$coreSplashScreenVersion` (default: `1.0.0-rc01`)

## Example Guides

[Adding Your Own Icons and Splash Screen Images &#8250;](https://www.joshmorony.com/adding-icons-splash-screens-launch-images-to-capacitor-projects/)
Expand Down
2 changes: 2 additions & 0 deletions splash-screen/android/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ ext {
androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.4.2'
androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.3'
androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.4.0'
coreSplashScreenVersion = project.hasProperty('coreSplashScreenVersion') ? rootProject.ext.coreSplashScreenVersion : '1.0.0-rc01'
}

buildscript {
Expand Down Expand Up @@ -54,4 +55,5 @@ dependencies {
testImplementation "junit:junit:$junitVersion"
androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
}
Loading

0 comments on commit 79185ad

Please sign in to comment.