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 d52d998 CB-13685 android: Added adaptive icon docs (#830) d52d998 is described below commit d52d9982ad737ec02e4374e09f6d75f454db60b0 Author: エリス <er...@users.noreply.github.com> AuthorDate: Wed Sep 12 10:45:12 2018 +0900 CB-13685 android: Added adaptive icon docs (#830) --- www/docs/en/dev/config_ref/images.md | 85 ++++++++++++++++++++++++++++++++---- 1 file changed, 76 insertions(+), 9 deletions(-) diff --git a/www/docs/en/dev/config_ref/images.md b/www/docs/en/dev/config_ref/images.md index 5520f9d..f499023 100644 --- a/www/docs/en/dev/config_ref/images.md +++ b/www/docs/en/dev/config_ref/images.md @@ -37,11 +37,10 @@ If you do not specify an icon, the Apache Cordova logo is used. Attributes | Description --------------|-------------------------------------------------------------------------------- -src | *Required* <br/> Location of the image file, relative to your project directory +src | *Required* <br/> Location of the image file, relative to your project directory. platform | *Optional* <br/> Target platform width | *Optional* <br/> Icon width in pixels height | *Optional* <br/> Icon height in pixels -density | *Optional* <br/> ==Android== <br/> Specified icon density target | *Optional* <br/> ==Windows== <br/> Destination filename for the image file and all its' MRT companions @@ -53,7 +52,74 @@ which will be used for all platforms. For each platform, you can also define a pixel-perfect icon set to fit different screen resolutions. -##Android +## Android + +On Android, instead of using a single image for an icon, you can use two images (background and foreground) to create an **Adaptive Icon**. + +Attributes | Description +--------------|-------------------------------------------------------------------------------- +background | *Required for Adaptive* <br/> Location of the image (png or vector) relative to your project directory, or color reference +foreground | *Required for Adaptive* <br/> Location of the image (png or vector) relative to your project directory, or color reference +density | *Optional* <br/> Specified icon density + +### Adaptive Icons + +To use the adaptive icons the `background` and `foreground` attributes must be defined in place of the `src` attribute. The `src` attribute is not used for adaptive icons. + +#### Adaptive Icon with Images: +```xml +<platform name="android"> + <icon background="res/icon/android/ldpi-background.png" density="ldpi" foreground="res/icon/android/ldpi-foreground.png" /> + <icon background="res/icon/android/mdpi-background.png" density="mdpi" foreground="res/icon/android/mdpi-foreground.png" /> + <icon background="res/icon/android/hdpi-background.png" density="hdpi" foreground="res/icon/android/hdpi-foreground.png" /> + <icon background="res/icon/android/xhdpi-background.png" density="xhdpi" foreground="res/icon/android/xhdpi-foreground.png" /> + <icon background="res/icon/android/xxhdpi-background.png" density="xxhdpi" foreground="res/icon/android/xxhdpi-foreground.png" /> + <icon background="res/icon/android/xxxhdpi-background.png" density="xxxhdpi" foreground="res/icon/android/xxxhdpi-foreground.png" /> +</platform> +``` + +**Note:** In this example, the foreground image will also be used as the fallback icon for Android devices that do not support the adaptive icons. The fallback icon can be overridden by setting the src attribute. + +#### Adaptive Icon with Vectors: +```xml +<platform name="android"> + <icon background="res/icon/android/ldpi-background.xml" density="ldpi" foreground="res/icon/android/ldpi-foreground.xml" src="res/android/ldpi.png" /> + <icon background="res/icon/android/mdpi-background.xml" density="mdpi" foreground="res/icon/android/mdpi-foreground.xml" src="res/android/mdpi.png" /> + <icon background="res/icon/android/hdpi-background.xml" density="hdpi" foreground="res/icon/android/hdpi-foreground.xml" src="res/android/hdpi.png" /> + <icon background="res/icon/android/xhdpi-background.xml" density="xhdpi" foreground="res/icon/android/xhdpi-foreground.xml" src="res/android/xhdpi.png" /> + <icon background="res/icon/android/xxhdpi-background.xml" density="xxhdpi" foreground="res/icon/android/xxhdpi-foreground.xml" src="res/android/xxhdpi.png" /> + <icon background="res/icon/android/xxxhdpi-background.xml" density="xxxhdpi" foreground="res/icon/android/xxxhdpi-foreground.xml" src="res/android/xxxhdpi.png" /> +</platform> +``` + +**Note:** In this example, the src attribute must be defined when then foreground attribute is defined with a vector or color. + +#### Adaptive Icon with Colors: +Create a `res/values/colors.xml` resource file in your project directory to store the app's color definitions. +```xml +<?xml version="1.0" encoding="utf-8"?> +<resources> + <color name="background">#FF0000</color> +</resources> +``` + +In the `config.xml`, we will add `resource-file` to copy the `colors.xml` into the approprate location so that the colors are available during build time. + +```xml +<platform name="android"> + <resource-file src="res/values/colors.xml" target="/app/src/main/res/values/colors.xml" /> + + <icon background="@color/background" density="ldpi" foreground="res/icon/android/ldpi-foreground.png" /> + <icon background="@color/background" density="mdpi" foreground="res/icon/android/mdpi-foreground.png" /> + <icon background="@color/background" density="hdpi" foreground="res/icon/android/hdpi-foreground.png" /> + <icon background="@color/background" density="xhdpi" foreground="res/icon/android/xhdpi-foreground.png" /> + <icon background="@color/background" density="xxhdpi" foreground="res/icon/android/xxhdpi-foreground.png" /> + <icon background="@color/background" density="xxxhdpi" foreground="res/icon/android/xxxhdpi-foreground.png" /> +</platform> +``` + +### Standard Icons + ```xml <platform name="android"> <!-- @@ -72,14 +138,15 @@ different screen resolutions. <icon src="res/android/xxxhdpi.png" density="xxxhdpi" /> </platform> ``` -###See Also + +### See Also - [Android icon guide](https://www.google.com/design/spec/style/icons.html) - [Android - Supporting multiple screens](http://developer.android.com/guide/practices/screens_support.html) -##Browser +## Browser Icons are not applicable to the Browser platform. -##iOS +## iOS ```xml <platform name="ios"> <!-- iOS 8.0+ --> @@ -114,10 +181,10 @@ Icons are not applicable to the Browser platform. <icon src="res/ios/icon-8...@2x.png" width="167" height="167" /> </platform> ``` -###See Also +### See Also - [App Icons on iPad and iPhone](https://developer.apple.com/library/content/qa/qa1686/_index.html) -##Windows +## Windows For Windows the recommended approach to define application icons is to use the `target` attribute. @@ -176,7 +243,7 @@ Although it is not recommended, it is also possible to define icons using the `w </platform> ``` -###See Also: +### See Also: - [Windows 10 platform guidelines for icons](https://msdn.microsoft.com/en-us/library/windows/apps/mt412102.aspx). - [Windows 8.1 tiles and icons sizes](https://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh781198.aspx) --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org