This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 36e5ad59f docs(core-features): migrate Android SplashScreen (#1249)
36e5ad59f is described below
commit 36e5ad59f8d696da141d0912b4465d1ddbc1c10d
Author: エリス <er...@users.noreply.github.com>
AuthorDate: Tue Jul 12 19:48:20 2022 +0900
docs(core-features): migrate Android SplashScreen (#1249)
* docs(core-features): migrate Android splash screen
* review: apply spelling corrections
* doc(android): update AndroidWindowSplashScreenBrandingImage warning
* doc(android): apply review suggestions
* doc(core-feature): splashscreen added page title
Co-authored-by: Norman Breau <nor...@nbsolutions.ca>
---
.../en/11.x/core/features/splashscreen/index.md | 215 ++++++++++++++++++---
.../en/dev/core/features/splashscreen/index.md | 215 ++++++++++++++++++---
2 files changed, 382 insertions(+), 48 deletions(-)
diff --git a/www/docs/en/11.x/core/features/splashscreen/index.md
b/www/docs/en/11.x/core/features/splashscreen/index.md
index 0c1d1c6d7..bbc9c8f13 100644
--- a/www/docs/en/11.x/core/features/splashscreen/index.md
+++ b/www/docs/en/11.x/core/features/splashscreen/index.md
@@ -21,34 +21,47 @@ title: Splash Screen
toc_title: Splash Screen
---
+# Splash Screen
+
This core feature gives the ability to configure and control the platform's
splash screen while your web application is launching.
-- [Supported Platforms](#supported-platforms)
-- [Platform Splash Screen Image
Configuration](#platform-splash-screen-image-configuration)
- - [Example Configuration](#example-configuration)
- - [iOS-specific Information](#ios-specific-information)
- - [Launch Storyboard Images](#launch-storyboard-images)
- - [Designing Launch Storyboard
Images](#designing-launch-storyboard-images)
- - [Scale](#scale)
- - [Idioms](#idioms)
- - [Size classes](#size-classes)
- - [Single-image launch screen](#single-image-launch-screen)
- - [Multi-image launch screen](#multi-image-launch-screen)
- - [Dark Mode](#dark-mode)
-- [config.xml Preferences](#configxml-preferences)
- - [`AutoHideSplashScreen`](#autohidesplashscreen)
- - [`FadeSplashScreen`](#fadesplashscreen)
- - [`FadeSplashScreenDuration`](#fadesplashscreenduration)
- - [`ShowSplashScreenSpinner`](#showsplashscreenspinner)
- - [`SplashScreenDelay`](#splashscreendelay)
-- [JavaScript Public APIs](#javascript-public-apis)
- - [`navigator.splashscreen.hide`](#navigatorsplashscreenhide)
- - [`navigator.splashscreen.show`](#navigatorsplashscreenshow)
-- [Quirks & Known Issues](#quirks--known-issues)
- - [iOS](#ios)
+- [Splash Screen](#splash-screen)
+ - [Supported Platforms](#supported-platforms)
+ - [Platform Splash Screen Image
Configuration](#platform-splash-screen-image-configuration)
+ - [Example Configuration](#example-configuration)
+ - [Android-specific Information](#android-specific-information)
+ - [Example Android Configuration](#example-android-configuration)
+ - [iOS-specific Information](#ios-specific-information)
+ - [Launch Storyboard Images](#launch-storyboard-images)
+ - [Designing Launch Storyboard
Images](#designing-launch-storyboard-images)
+ - [Scale](#scale)
+ - [Idioms](#idioms)
+ - [Size classes](#size-classes)
+ - [Single-image launch screen](#single-image-launch-screen)
+ - [Multi-image launch screen](#multi-image-launch-screen)
+ - [Dark Mode](#dark-mode)
+ - [config.xml Preferences](#configxml-preferences)
+ - [`AutoHideSplashScreen`](#autohidesplashscreen)
+ - [`FadeSplashScreen`](#fadesplashscreen)
+ - [`FadeSplashScreenDuration`](#fadesplashscreenduration)
+ - [`ShowSplashScreenSpinner`](#showsplashscreenspinner)
+ - [`SplashScreenDelay`](#splashscreendelay)
+ - [`AndroidPostSplashScreenTheme`](#androidpostsplashscreentheme)
+ -
[`AndroidWindowSplashScreenAnimatedIcon`](#androidwindowsplashscreenanimatedicon)
+ -
[`AndroidWindowSplashScreenAnimationDuration`](#androidwindowsplashscreenanimationduration)
+ -
[`AndroidWindowSplashScreenBackground`](#androidwindowsplashscreenbackground)
+ -
[`AndroidWindowSplashScreenBrandingImage`](#androidwindowsplashscreenbrandingimage)
+ -
[`AndroidWindowSplashScreenIconBackgroundColor`](#androidwindowsplashscreeniconbackgroundcolor)
+ - [JavaScript Public APIs](#javascript-public-apis)
+ - [`navigator.splashscreen.hide`](#navigatorsplashscreenhide)
+ - [`navigator.splashscreen.show`](#navigatorsplashscreenshow)
+ - [Quirks & Known Issues](#quirks--known-issues)
+ - [iOS](#ios)
+ - [Android](#android)
## Supported Platforms
+- Android
- iOS
For other platforms, check the `cordova-plugin-splashscreen` for support.
@@ -70,12 +83,17 @@ projectRoot
www
res
screen
+ android
ios
```
**Config.xml:**
```xml
+<platform name="android">
+ <preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+</platform>
+
<!--
Storyboard (supports all devices):
Note: images are determined by scale, idiom, and size traits. The following
@@ -91,6 +109,26 @@ projectRoot
</platform>
```
+### Android-specific Information
+
+Starting in Android 12, Google has implemented a new SplashScreen API to
controls the app launch animation which runs on a device with Android 12 and
higher. For backwards compatability, Cordova has included the
`core-splashscreen` compatability library which extends this features back to
Android API 21 and higher.
+
+To effectively create your own Android SplashScreen assets, it is important to
understand the requirements of an Adaptive Icon.
+
+**Resource:**
+
+- [Splash Screen
dimensions](https://developer.android.com/guide/topics/ui/splash-screen#splash_screen_dimensions)
+- [Adaptive
icons](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive)
+
+#### Example Android Configuration
+
+```xml
+<platform name="android">
+ <!-- Default -->
+ <preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+</platform>
+```
+
### iOS-specific Information
Launch storyboard images are sized based on scale, idiom, and size classes. It
supports all devices, and can be used with split-screen/slide-over multitasking.
@@ -262,6 +300,7 @@ Indicates whether to hide splash screen automatically or
not. The splash screen
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Boolean`
@@ -278,8 +317,11 @@ Indicates whether to hide splash screen automatically or
not. The splash screen
Controlls the ability of the fade in and out of the splash screen.
+For Android, it controlls only the fade out.
+
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Boolean`
@@ -298,6 +340,7 @@ Controlls the length of the the splash screen fade effect.
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Float`, in milliseconds
@@ -351,14 +394,18 @@ Amount of time in milliseconds to wait before
automatically hide splash screen.
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Number`, in milliseconds
**Default Value:** `true`
+- Android
+ `-1`: The splash screen will automatically hide when the `onPageFinished`
has been triggered.
+
- iOS
- `3000`: The splash screen will automatticly hide in 3 seconds.
+ `3000`: The splash screen will automatically hide in 3 seconds.
**Usage Example:**
@@ -366,6 +413,120 @@ Amount of time in milliseconds to wait before
automatically hide splash screen.
<preference name="SplashScreenDelay" value="3000" />
```
+### `AndroidPostSplashScreenTheme`
+
+Sets the post-theme of the activity after splash screen hides.
+
+_Note:_ This setting is available but use at your own risk.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`
+
+**Default Value:** `@style/Theme.AppCompat.NoActionBar`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidPostSplashScreenTheme"
value="@style/Theme.AppCompat.NoActionBar"/>
+```
+
+### `AndroidWindowSplashScreenAnimatedIcon`
+
+The splash screen image. This preference is used for both animated and
non-animated icons. The current acceptable asset files can either be an XML
Vector Drwable or PNG.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, file path to the asset file
+
+**Default Value:** If not supplied, the Cordova's default asset is used.
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+```
+
+### `AndroidWindowSplashScreenAnimationDuration`
+
+Defines the duration of the icon's animation if an Animated Vector Drwable is
supplied as the splash screen image.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `Number`, in milliseconds
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenAnimationDuration" value="3000"/>
+```
+
+### `AndroidWindowSplashScreenBackground`
+
+The splash screen background color.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, color hex code value.
+
+**Default Value:** `#ffffff`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenBackground" value="#ffffff" />
+```
+
+### `AndroidWindowSplashScreenBrandingImage`
+
+> :warning: this setting is currently unsupported by the Android's Splash
Screen compatability library. [See Google Android Issue
Tracker](https://issuetracker.google.com/issues/194301890)
+
+<!--
+The splash screen's branding image.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, file path to the asset file
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenBrandingImage"
value="res/screen/android/splashscreen_branding.xml" />
+```
+-->
+
+### `AndroidWindowSplashScreenIconBackgroundColor`
+
+The splash screen's icons background color. Useful to seperate increase the
contrast seperation between the background and icon.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, color hex code value.
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenIconBackgroundColor"
value="#c0c0c0" />
+```
+
## JavaScript Public APIs
### `navigator.splashscreen.hide`
@@ -374,6 +535,7 @@ Dismiss the splash screen.
**Supported Platforms:**
+- Android
- iOS
**Usage Example:**
@@ -429,3 +591,8 @@ screen visible for application startup.
4. **`anyany` must be provided for other variations to be used**
If you don't provide an `anyany` version of the launch image for a specific
scale and idiom, the other variations (like `anycom`, `comany`, and `comcom`)
will ignored.
+
+### Android
+
+1. **Simulator does not show the splash screen when launching the application
from Android Studio or Cordova CLI.**
+ This is a known Android simulator issue. After uploading the app to the
simulator, exiting and opening the app will display show the Splash Screen. If
changes are not showen, try also performing a clean build.
diff --git a/www/docs/en/dev/core/features/splashscreen/index.md
b/www/docs/en/dev/core/features/splashscreen/index.md
index 0c1d1c6d7..be35ddc93 100644
--- a/www/docs/en/dev/core/features/splashscreen/index.md
+++ b/www/docs/en/dev/core/features/splashscreen/index.md
@@ -21,34 +21,47 @@ title: Splash Screen
toc_title: Splash Screen
---
+# Splash Screen
+
This core feature gives the ability to configure and control the platform's
splash screen while your web application is launching.
-- [Supported Platforms](#supported-platforms)
-- [Platform Splash Screen Image
Configuration](#platform-splash-screen-image-configuration)
- - [Example Configuration](#example-configuration)
- - [iOS-specific Information](#ios-specific-information)
- - [Launch Storyboard Images](#launch-storyboard-images)
- - [Designing Launch Storyboard
Images](#designing-launch-storyboard-images)
- - [Scale](#scale)
- - [Idioms](#idioms)
- - [Size classes](#size-classes)
- - [Single-image launch screen](#single-image-launch-screen)
- - [Multi-image launch screen](#multi-image-launch-screen)
- - [Dark Mode](#dark-mode)
-- [config.xml Preferences](#configxml-preferences)
- - [`AutoHideSplashScreen`](#autohidesplashscreen)
- - [`FadeSplashScreen`](#fadesplashscreen)
- - [`FadeSplashScreenDuration`](#fadesplashscreenduration)
- - [`ShowSplashScreenSpinner`](#showsplashscreenspinner)
- - [`SplashScreenDelay`](#splashscreendelay)
-- [JavaScript Public APIs](#javascript-public-apis)
- - [`navigator.splashscreen.hide`](#navigatorsplashscreenhide)
- - [`navigator.splashscreen.show`](#navigatorsplashscreenshow)
-- [Quirks & Known Issues](#quirks--known-issues)
- - [iOS](#ios)
+- [Splash Screen](#splash-screen)
+ - [Supported Platforms](#supported-platforms)
+ - [Platform Splash Screen Image
Configuration](#platform-splash-screen-image-configuration)
+ - [Example Configuration](#example-configuration)
+ - [Android-specific Information](#android-specific-information)
+ - [Example Android Configuration](#example-android-configuration)
+ - [iOS-specific Information](#ios-specific-information)
+ - [Launch Storyboard Images](#launch-storyboard-images)
+ - [Designing Launch Storyboard
Images](#designing-launch-storyboard-images)
+ - [Scale](#scale)
+ - [Idioms](#idioms)
+ - [Size classes](#size-classes)
+ - [Single-image launch screen](#single-image-launch-screen)
+ - [Multi-image launch screen](#multi-image-launch-screen)
+ - [Dark Mode](#dark-mode)
+ - [config.xml Preferences](#configxml-preferences)
+ - [`AutoHideSplashScreen`](#autohidesplashscreen)
+ - [`FadeSplashScreen`](#fadesplashscreen)
+ - [`FadeSplashScreenDuration`](#fadesplashscreenduration)
+ - [`ShowSplashScreenSpinner`](#showsplashscreenspinner)
+ - [`SplashScreenDelay`](#splashscreendelay)
+ - [`AndroidPostSplashScreenTheme`](#androidpostsplashscreentheme)
+ -
[`AndroidWindowSplashScreenAnimatedIcon`](#androidwindowsplashscreenanimatedicon)
+ -
[`AndroidWindowSplashScreenAnimationDuration`](#androidwindowsplashscreenanimationduration)
+ -
[`AndroidWindowSplashScreenBackground`](#androidwindowsplashscreenbackground)
+ -
[`AndroidWindowSplashScreenBrandingImage`](#androidwindowsplashscreenbrandingimage)
+ -
[`AndroidWindowSplashScreenIconBackgroundColor`](#androidwindowsplashscreeniconbackgroundcolor)
+ - [JavaScript Public APIs](#javascript-public-apis)
+ - [`navigator.splashscreen.hide`](#navigatorsplashscreenhide)
+ - [`navigator.splashscreen.show`](#navigatorsplashscreenshow)
+ - [Quirks & Known Issues](#quirks--known-issues)
+ - [iOS](#ios)
+ - [Android](#android)
## Supported Platforms
+- Android
- iOS
For other platforms, check the `cordova-plugin-splashscreen` for support.
@@ -70,12 +83,17 @@ projectRoot
www
res
screen
+ android
ios
```
**Config.xml:**
```xml
+<platform name="android">
+ <preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+</platform>
+
<!--
Storyboard (supports all devices):
Note: images are determined by scale, idiom, and size traits. The following
@@ -91,6 +109,26 @@ projectRoot
</platform>
```
+### Android-specific Information
+
+Starting in Android 12, Google has implemented a new SplashScreen API to
controls the app launch animation which runs on a device with Android 12 and
higher. For backwards compatibility, Cordova has included the
`core-splashscreen` compatibility library which extends this features back to
Android API 21 and higher.
+
+To effectively create your own Android SplashScreen assets, it is important to
understand the requirements of an Adaptive Icon.
+
+**Resource:**
+
+- [Splash Screen
dimensions](https://developer.android.com/guide/topics/ui/splash-screen#splash_screen_dimensions)
+- [Adaptive
icons](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive)
+
+#### Example Android Configuration
+
+```xml
+<platform name="android">
+ <!-- Default -->
+ <preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+</platform>
+```
+
### iOS-specific Information
Launch storyboard images are sized based on scale, idiom, and size classes. It
supports all devices, and can be used with split-screen/slide-over multitasking.
@@ -262,6 +300,7 @@ Indicates whether to hide splash screen automatically or
not. The splash screen
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Boolean`
@@ -278,8 +317,11 @@ Indicates whether to hide splash screen automatically or
not. The splash screen
Controlls the ability of the fade in and out of the splash screen.
+For Android, it controlls only the fade out.
+
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Boolean`
@@ -298,6 +340,7 @@ Controlls the length of the the splash screen fade effect.
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Float`, in milliseconds
@@ -351,14 +394,18 @@ Amount of time in milliseconds to wait before
automatically hide splash screen.
**Supported Platforms:**
+- Android
- iOS
**Data Type:** `Number`, in milliseconds
**Default Value:** `true`
+- Android
+ `-1`: The splash screen will automatically hide when the `onPageFinished`
has been triggered.
+
- iOS
- `3000`: The splash screen will automatticly hide in 3 seconds.
+ `3000`: The splash screen will automatically hide in 3 seconds.
**Usage Example:**
@@ -366,6 +413,120 @@ Amount of time in milliseconds to wait before
automatically hide splash screen.
<preference name="SplashScreenDelay" value="3000" />
```
+### `AndroidPostSplashScreenTheme`
+
+Sets the post-theme of the activity after splash screen hides.
+
+_Note:_ This setting is available but use at your own risk.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`
+
+**Default Value:** `@style/Theme.AppCompat.NoActionBar`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidPostSplashScreenTheme"
value="@style/Theme.AppCompat.NoActionBar"/>
+```
+
+### `AndroidWindowSplashScreenAnimatedIcon`
+
+The splash screen image. This preference is used for both animated and
non-animated icons. The current acceptable asset files can either be a XML
Vector Drawable or PNG.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, file path to the asset file
+
+**Default Value:** If not supplied, the Cordova's default asset is used.
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenAnimatedIcon"
value="res/screen/android/splashscreen.xml" />
+```
+
+### `AndroidWindowSplashScreenAnimationDuration`
+
+Defines the duration of the icon's animation if an Animated Vector Drawable is
supplied as the splash screen image.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `Number`, in milliseconds
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenAnimationDuration" value="3000"/>
+```
+
+### `AndroidWindowSplashScreenBackground`
+
+The splash screen background color.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, color hex code value.
+
+**Default Value:** `#ffffff`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenBackground" value="#ffffff" />
+```
+
+### `AndroidWindowSplashScreenBrandingImage`
+
+> :warning: this setting is currently unsupported. The core-splashscreen
compatibility library, that Cordova Android relies on for providing backwards
support, has not implemented this functionality. [See Google Android Issue
Tracker](https://issuetracker.google.com/issues/194301890)
+
+<!--
+The splash screen's branding image.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, file path to the asset file
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenBrandingImage"
value="res/screen/android/splashscreen_branding.xml" />
+```
+-->
+
+### `AndroidWindowSplashScreenIconBackgroundColor`
+
+The splash screen's icons background color. Useful to seperate increase the
contrast seperation between the background and icon.
+
+**Supported Platforms:**
+
+- Android
+
+**Data Type:** `String`, color hex code value.
+
+**Default Value:** `undefined`
+
+**Usage Example:**
+
+```xml
+<preference name="AndroidWindowSplashScreenIconBackgroundColor"
value="#c0c0c0" />
+```
+
## JavaScript Public APIs
### `navigator.splashscreen.hide`
@@ -374,6 +535,7 @@ Dismiss the splash screen.
**Supported Platforms:**
+- Android
- iOS
**Usage Example:**
@@ -429,3 +591,8 @@ screen visible for application startup.
4. **`anyany` must be provided for other variations to be used**
If you don't provide an `anyany` version of the launch image for a specific
scale and idiom, the other variations (like `anycom`, `comany`, and `comcom`)
will ignored.
+
+### Android
+
+1. **Simulator does not show the splash screen when launching the application
from Android Studio or Cordova CLI.**
+ This is a known Android simulator issue. After uploading the app to the
simulator, exiting and opening the app will display show the Splash Screen. If
changes are not shown, try also performing a clean build.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org
For additional commands, e-mail: commits-h...@cordova.apache.org
