cordova-plugin-splashscreen

Этот плагин необходим для работы со splash-экранами. Этот плагин отображает и скрывает splash-экран во время запуска приложения.

Сообщайте о проблемах с этим плагином на форуме отслеживания проблем Apache Cordova.

Установка

// npm hosted (new) id
cordova plugin add cordova-plugin-splashscreen

// you may also install directly from this repo
cordova plugin add https://github.com/apache/cordova-plugin-splashscreen.git

Поддерживаемые платформы

• Amazon Fire OS
• Android
• BlackBerry 10
• iOS
• Windows Phone 7 и 8
• Windows (cordova-windows требуется версия >= 4.4.0)
• Браузер

Примечание: Расширенный splash-экран не требует плагина в Windows (в отличие от Android и iOS), если вы не используете API плагина, т.е. программирование скрытия/отображения.

Информация, специфичная для iOS

Существует два механизма отображения стартового экрана в iOS:

1. Запуск изображений (legacy): изображения имеют размер, точно соответствующий размеру экрана устройства. Не поддерживает родное разрешение iPad Pro 12.9 или многозадачность в режиме разделенного экрана/слайдов.

2. Изображения стартовой истории (storyboard): изображения имеют размер, основанный на масштабе, языке и классах размеров. Поддерживает все устройства и может использоваться с многозадачностью в режиме разделенного экрана/слайдов.

Apple переходит от старых изображений стартового экрана. Нет официальной поддержки предоставления изображения стартового экрана с родным разрешением для iPad Pro 12.9 или для предоставления изображений стартового экрана, работающих с многозадачностью в режиме разделенного экрана или слайдов. Если ваше приложение не должно поддерживать эти контексты, то вы можете продолжать использовать старые изображения стартового экрана так долго, как захотите.

Предпочтительный метод предоставления изображений стартового экрана — использование стартового storyboard. Для разработчиков приложений с родным кодом идеальный стартовый storyboard — это неоконченный вариант пользовательского интерфейса приложения при запуске. Для разработчиков приложений, не написанных на родном коде, которые не хотят изучать Interface Builder, однако, этот плагин моделирует метод старых изображений стартового экрана, насколько это возможно.

Старые изображения стартового экрана

Если вы решите использовать старые изображения стартового экрана, вы будете использовать следующий синтаксис в config.xml:

<splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>
<splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
<splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
<splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/>
<splash src="res/screen/ios/Default-Landscape~ipad.png" width="1024" height="768"/>
<splash src="res/screen/ios/Default-Landscape@2x~ipad.png" width="2048" height="1536"/>
<splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
<splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/>
<splash src="res/screen/ios/Default-736h.png" width="1242" height="2208"/>

Технически имя файла для атрибута src может быть любым; имена файлов используются, потому что они соответствуют тому, что будет использоваться при компиляции вашего проекта. Атрибуты width и height определяют, какие изображения стартового экрана отображаются на каких устройствах следующим образом:

Примечание: Крайне важно, чтобы исходное изображение фактически соответствовало размеру, указанному в атрибутах width и height. В противном случае устройство может не отобразить его должным образом или вообще не отобразить.

Изображения стартового storyboard

Для поддержки новых форм факторов и многозадачности в режиме разделенного экрана/слайдов вы должны использовать изображения стартового storyboard. Они похожи на старые изображения стартового экрана, но существуют важные различия:

• изображения не зависят от конкретного устройства.

• изображения масштабируются для заполнения доступного области просмотра (при сохранении соотношения сторон).

• края изображений будут обрезаны, а объем будет меняться в зависимости от устройства и области просмотра.

• нет необходимости предоставлять изображение для каждого возможного устройства, области просмотра и ориентации; iOS автоматически выберет лучшее изображение для ситуации.

Создание изображений стартового storyboard

Ключ к созданию изображения стартового storyboard заключается в понимании того, что края изображения, почти наверняка, будут обрезаны. Поэтому не следует помещать важную информацию рядом с краями предоставляемых изображений. Безопасная область только в центре, и это практически гарантирует, что следование совету Apple о представлении неоконченного пользовательского интерфейса не будет хорошо работать.

Вместо этого следующие советы должны помочь вам создать изображение стартового экрана, которое работает на множестве форм факторов, областей просмотра и ориентаций:

• Важные графические элементы (логотипы, значки, заголовки) должны быть центрированы. Безопасная граница будет разной, поэтому вам необходимо протестировать, чтобы убедиться, что важные графические элементы никогда не обрезаются. Еще лучше — не предоставлять важные графические элементы вообще.

  • Вы можете уточнить размещение и размер этих графических элементов, но вы не имеете такого же тонкого контроля, как и с изображениями стартового экрана (legacy).

• Используйте простой цветовой фон. Если вы используете два цвета, вам нужно, чтобы один цвет заполнял верхнюю половину изображения, а второй — нижнюю половину. Если вы используете градиент, вам, вероятно, нужно убедиться, что середина градиента совпадает с центром изображения.

• Не беспокойтесь о точности пикселей — поскольку изображения масштабируются, почти нет шансов, что изображения идеально впишутся в сетку пикселей. Поскольку все поддерживаемые устройства iOS используют экраны Retina, пользователи вряд ли это заметят.

Важно понимать понятия масштаба, типа устройства и классов размеров для эффективного использования изображений стартового storyboard. Из предоставленных изображений стартового storyboard iOS выберет изображение, которое лучше всего соответствует устройству и области просмотра, и отобразит это изображение. Можно предоставить только одно изображение стартового экрана, если это необходимо, но также можно уточнить отображаемое изображение стартового экрана на основе свойств. При уточнении можно игнорировать свойства, которые не являются целевыми или не поддерживаются приложением.

Примечание: Если вы используете изображения стартового storyboard, нет необходимости включать старые изображения. Если вы это сделаете, старые изображения будут скопированы, но не будут использоваться.

Масштаб

В целом, вы захотите предоставить изображения с масштабом 2x и 3x. Cordova сейчас поддерживает только устройства с Retina, поэтому нет смысла предоставлять изображения с масштабом 1x.

Типы устройств

Вам нужно предоставить только универсальные изображения, если вам не нужно настраивать их для определённого типа устройства.

Классы размеров

Существует два класса размеров, применимые к обеим осям экрана. Узкие области просмотра считаются классом размеров «компактный», а оставшиеся области просмотра — «стандартный». При предоставлении изображений в Xcode, однако, необходимо выбрать «любой & компактый» и «любой & стандартный». Для согласованности с родной терминологией эта функция будет соответствовать областям просмотра «любой» и «компактный». any будет соответствовать областям просмотра стандартного размера.

Примечание: эта функция использует com как сокращение для классов «компактный».

Данная функция поддерживает следующие классы:

Полный список классов размеров, связанных с устройствами и областями просмотра, см. на http://www.sizeclasses.com.

Стартовый экран с одним изображением

Если изображение стартового экрана простое, вы можете избежать создания множества различных изображений и предоставить только одно. Изображение стартового экрана должно соответствовать следующим требованиям:

• изображение должно быть квадратным

• изображение должно быть достаточно большим, чтобы уместиться на iPad Pro 12.9": 2732x2732

• любая важная информация должна располагаться в центре

Помните, что изображение будет обрезано, возможно, довольно сильно, в зависимости от области просмотра.

После создания изображения вы можете включить его в свой проект, добавив следующее в config.xml:

<splash src="res/screen/ios/Default@2x~universal~anyany.png" />

Поскольку предоставляется только одно изображение, iOS будет использовать его во всех контекстах.

Стартовый экран с несколькими изображениями

Если одного изображения стартового экрана недостаточно, вам, вероятно, потребуется предоставить как минимум шесть изображений, если не больше. Кроме того, помните, что настройка изображения для конкретного устройства невозможна, но только для класса устройства, фактора отображения и размера области просмотра.

Если вам не нужно настраивать изображения для определённого типа устройства, вы должны создать шесть изображений, как показано ниже:

* это изображение необходимо для того, чтобы iOS использовало другие изображения в этом масштабе и идиоме.

Примечание: Если размеры 3x кажутся вам слишком маленькими, это потому, что в настоящее время существует только один класс устройств с плотностью 3x: iPhone 6+/6s+/7+.

Вышеприведенный фрагмент выглядит следующим образом в config.xml:

<splash src="res/screen/ios/Default@2x~universal~anyany.png" />
<splash src="res/screen/ios/Default@2x~universal~comany.png" />
<splash src="res/screen/ios/Default@2x~universal~comcom.png" />
<splash src="res/screen/ios/Default@3x~universal~anyany.png" />
<splash src="res/screen/ios/Default@3x~universal~anycom.png" />
<splash src="res/screen/ios/Default@3x~universal~comany.png" />

Если требуется дальнейшая настройка на основе идиомы устройства, это можно сделать. Это может выглядеть так:

* это изображение необходимо для того, чтобы iOS использовало другие изображения в этом масштабе и идиоме.

Вышеприведенный фрагмент выглядит следующим образом в config.xml:

<splash src="res/screen/ios/Default@2x~iphone~anyany.png" />
<splash src="res/screen/ios/Default@2x~iphone~comany.png" />
<splash src="res/screen/ios/Default@2x~iphone~comcom.png" />
<splash src="res/screen/ios/Default@3x~iphone~anyany.png" />
<splash src="res/screen/ios/Default@3x~iphone~anycom.png" />
<splash src="res/screen/ios/Default@3x~iphone~comany.png" />
<splash src="res/screen/ios/Default@2x~ipad~anyany.png" />
<splash src="res/screen/ios/Default@2x~ipad~comany.png" />

Особенности и известные проблемы

1. Приложение на целевом устройстве может не отражать изменения в изображениях После запуска приложения на целевом устройстве iOS кеширует изображение запуска. К сожалению, при изменении изображений iOS не аннулирует кеш, что означает, что вы по-прежнему будете видеть старое изображение запуска. Вы можете либо: удалить приложение, либо сбросить содержимое и настройки (симулятор).

2. Сиミュレーターは、CLIから起動した場合、期待される画像を表示しない可能性があります Xcodeが特定のシミュレーターにデプロイすると、シミュレーターの特性と一致するアセットのみがコピーされます。たとえば、iPhone 6s Plusシミュレーターでアプリを実行しようとすると、@3xの起動画像のみがコピーされます。ただし、CLIからコンパイルする場合、デフォルトでiPhone 5sを想定するため、@2xの起動画像のみがコピーされます。起動画像が大きく異なる場合を除き、違いは気づかれにくい可能性がありますが、これは、テストの唯一の正確な方法は物理的なデバイスでテストすることであることを意味します。

3. anyanyが必要です。他のバリエーションを使用するには。特定のスケールとイディオムの起動画像のanyanyバージョンを提供しないと、他のバリエーション（anycom, comany, comcomなど）が無視されます。

Информация, специфичная для Windows

Изображения экрана загрузки можно определить, используя концепцию MRT.
Если вы указываете src="res/windows/splashscreen.png", следующие файлы будут скопированы в папку изображений приложения:
res/windows/splashscreen.png | res/windows/splashscreen.scale-100.png, res/windows/splashscreen.scale-125.png, и т.д.
Поддерживаются следующие значения:

Примечание: Размер экрана загрузки для проекта Windows 10 не должен превышать 200 КБ.
Примечание: Поддерживаемые форматы .png, .jpg, .jpeg. Смешивание расширений в одном целевом файле не поддерживается. То есть, вы можете иметь splashscreen.jpg и splashscreenphone.png, но не splashscreen.scale-100.png, splashscreen.scale-400.jpg.
Примечание: Возможно, потребуется перезапустить Visual Studio решение после изменения изображений и выполнения cordova prepare для того, чтобы изменения вступили в силу.

Пример конфигурации

В файле config.xml верхнего уровня (не тот, что в platforms), добавьте элементы конфигурации, как указано здесь.

Обратите внимание, что значение атрибута "src" является относительным к корневому каталогу проекта, а не к каталогу www (см. Directory structure ниже). Вы можете назвать исходное изображение как угодно. Внутреннее имя в приложении определяется Cordova.

Структура каталогов:

projectRoot
    hooks
    platforms
    plugins
    www
        css
        img
        js
    res
        screen
            android
            ios
            windows

<platform name="android">
    <!-- you can use any density that exists in the Android project -->
    <splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi"/>
    <splash src="res/screen/android/splash-land-ldpi.png" density="land-ldpi"/>
    <splash src="res/screen/android/splash-land-mdpi.png" density="land-mdpi"/>
    <splash src="res/screen/android/splash-land-xhdpi.png" density="land-xhdpi"/>

    <splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi"/>
    <splash src="res/screen/android/splash-port-ldpi.png" density="port-ldpi"/>
    <splash src="res/screen/android/splash-port-mdpi.png" density="port-mdpi"/>
    <splash src="res/screen/android/splash-port-xhdpi.png" density="port-xhdpi"/>
</platform>

<platform name="ios">
    <!-- There are two mechanisms for showing launch images.
      -- Legacy method (supports all devices except iPad Pro 12.9):
      -- Note: Images are determined by width and height. The following are supported -->
    <splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>
    <splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
    <splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
    <splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/>
    <splash src="res/screen/ios/Default-Landscape~ipad.png" width="1024" height="768"/>
    <splash src="res/screen/ios/Default-Landscape@2x~ipad.png" width="2048" height="1536"/>
    <splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
    <splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/>
    <splash src="res/screen/ios/Default-736h.png" width="1242" height="2208"/>
    <splash src="res/screen/ios/Default-Landscape-736h.png" width="2208" height="1242"/>
    <!-- Storyboard method (supports all devices):
      -- Important: If you use the storyboard method, legacy images are 
      -- copied but ignored.
      -- Note: images are determined by scale, idiom, and size traits. The following
      -- are suggested based on current device form factors -->
    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comcom.png" />
    <splash src="res/screen/ios/Default@3x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@3x~universal~anycom.png" />
    <splash src="res/screen/ios/Default@3x~universal~comany.png" />

</platform>

<!-- Configuration using MRT concept (Recommended, see "Windows-specific information" section for details): -->
<platform name="windows">
    <splash src="res/screen/windows/splashscreen.png" target="SplashScreen"/>
    <splash src="res/screen/windows/splashscreenphone.png" target="SplashScreenPhone"/>
</platform>

<!-- Configuration using image size: -->
<!--<platform name="windows">
    <splash src="res/screen/windows/splashscreen.png" width="620" height="300"/>
    <splash src="res/screen/windows/splashscreenphone.png" width="1152" height="1920"/>
</platform>-->

<platform name="blackberry10">
    <!-- Add a rim:splash element for each resolution and locale you wish -->
    <!-- http://developer.blackberry.com/html5/documentation/rim_splash_element.html -->
    <rim:splash src="res/screen/blackberry/splashscreen.png"/>
</platform>

<preference name="SplashScreenDelay" value="10000" />

Настройки

config.xml

• AutoHideSplashScreen (логическое значение, по умолчанию true). Указывает, скрывать ли экран загрузки автоматически или нет. Экран загрузки скрывается после определенного времени, указанного в настройке SplashScreenDelay.

<preference name="AutoHideSplashScreen" value="true" />

• SplashScreenDelay (число, по умолчанию 3000). Количество времени в миллисекундах, которое нужно подождать, прежде чем автоматически скрыть экран загрузки.

<preference name="SplashScreenDelay" value="3000" />

Также обратите внимание, что это значение раньше измерялось в секундах, а не в миллисекундах, поэтому значения меньше 30 все равно будут обрабатываться как секунды. (Рассматривайте это как устаревшее исправление, которое исчезнет в какой-то будущей версии).

Чтобы отключить экран загрузки, добавьте следующую настройку в config.xml:

<preference name="SplashScreenDelay" value="0"/>

Особенности Windows: Вы должны отключить заставку в случае динамического обновления всего содержимого документа (например, с помощью маршрутизатора SPA), чтобы избежать влияния на элементы управления пользовательского интерфейса.
Обратите внимание, что в этом случае вам также необходимо напрямую ссылаться на WinJS/base.js в HTML-странице, чтобы избежать проблем с контекстом активации (CB-11658).

Особенности iOS: чтобы отключить заставку на платформе ios, вы также должны добавить <preference name="FadeSplashScreenDuration" value="0"/> к config.xml.

• FadeSplashScreen (логическое значение, по умолчанию true): Установите значение false, чтобы предотвратить появление и исчезновение заставки при изменении её состояния отображения.

<preference name="FadeSplashScreen" value="false"/>

• FadeSplashScreenDuration (вещественное число, по умолчанию 500): Указывает количество миллисекунд для выполнения эффекта плавного перехода заставки.

<preference name="FadeSplashScreenDuration" value="750"/>

Примечание: FadeSplashScreenDuration включено в SplashScreenDelay, например, если у вас определены <preference name="SplashScreenDelay" value="3000" /> и <preference name="FadeSplashScreenDuration" value="1000"/> в config.xml:

• 00:00 - заставка отображается
• 00:02 - начался плавный переход
• 00:03 - заставка скрыта

Отключение плавного перехода с помощью <preference name="FadeSplashScreen" value="false"/> технически означает, что продолжительность плавного перехода равна 0, так что в этом примере общее время задержки заставки по-прежнему будет 3 секунды.

Примечание: Это относится только к запуску приложения — вы должны учитывать время задержки плавного перехода при ручном отображении/скрытии заставки в коде:

navigator.splashscreen.show();
window.setTimeout(function () {
    navigator.splashscreen.hide();
}, splashDuration - fadeDuration);

• ShowSplashScreenSpinner (логическое значение, по умолчанию true): Установите значение false, чтобы скрыть индикатор загрузки заставки.

<preference name="ShowSplashScreenSpinner" value="false"/>

Особенности Android

В вашем config.xml, вы можете добавить следующие настройки:

<preference name="SplashMaintainAspectRatio" value="true|false" />
<preference name="SplashShowOnlyFirstTime" value="true|false" />

Настройка "SplashMaintainAspectRatio" необязательна. Если она установлена в значение true, изображение заставки не растягивается для соответствия экрану, а вместо этого просто "покрывает" экран, как в CSS "background-size:cover". Это очень полезно, когда изображения заставки не могут быть искажены каким-либо образом, например, когда они содержат пейзаж или текст. Эта настройка лучше всего работает с изображениями, имеющими большие отступы (безопасные области), которые можно безопасно обрезать на экранах с различными соотношениями сторон.

Плагин перезагружает изображение заставки при изменении ориентации, поэтому вы можете указать разные изображения для портретного и ландшафтного режимов.

Настройка "SplashShowOnlyFirstTime" также необязательна и по умолчанию равна true. Если она установлена в значение true, заставка будет отображаться только при запуске приложения. Однако, если вы планируете использовать navigator.app.exitApp() для закрытия приложения и принудительного отображения заставки при следующем запуске, вы должны установить это свойство в значение false (это также относится к закрытию приложения кнопкой "Назад").

Особенности браузера

Вы можете использовать следующие настройки в вашем config.xml:

<platform name="browser">
    <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" -->
    <preference name="SplashScreenDelay" value="3000" /> <!-- defaults to "3000" -->
    <preference name="SplashScreenBackgroundColor" value="green" /> <!-- defaults to "#464646" -->
    <preference name="ShowSplashScreen" value="false" /> <!-- defaults to "true" -->
    <preference name="SplashScreenWidth" value="600" /> <!-- defaults to "170" -->
    <preference name="SplashScreenHeight" value="300" /> <!-- defaults to "200" -->
</platform>

Примечание: значение SplashScreen должно быть абсолютным, чтобы оно работало на подстранице. Значение SplashScreen используется только для платформы браузера. Значение будет проигнорировано для других платформ.

Особенности iOS

• В iOS изображения заставки называются изображениями запуска. Эти изображения обязательны в iOS.

Особенности Windows

• SplashScreenSpinnerColor (строка, по умолчанию системный цвет акцента): хэш, обозначение RGB или имя цвета CSS.

<preference name="SplashScreenSpinnerColor" value="#242424"/>
<preference name="SplashScreenSpinnerColor" value="DarkRed"/>
<preference name="SplashScreenSpinnerColor" value="rgb(50,128,128)"/>

• SplashScreenBackgroundColor (строка, по умолчанию #464646): шестнадцатеричное обозначение.

<preference name="SplashScreenBackgroundColor" value="0xFFFFFFFF"/>

Методы

• splashscreen.show
• splashscreen.hide

splashscreen.hide

Скрыть заставку.

navigator.splashscreen.hide();

Особенности BlackBerry 10, WP8, iOS

Значение настройки config.xml файла AutoHideSplashScreen должно быть false. Чтобы задержать скрытие заставки на две секунды, добавьте таймер, например, в обработчик события deviceready:

setTimeout(function() {
    navigator.splashscreen.hide();
}, 2000);

splashscreen.show

Отображает заставку.

navigator.splashscreen.show();

Ваше приложение не может вызвать navigator.splashscreen.show() до запуска приложения и срабатывания события deviceready. Но поскольку, как правило, заставка должна отображаться до запуска приложения, это, похоже, противоречит цели заставки. Предоставление некоторых настроек в config.xml автоматически show заставку сразу после запуска приложения и до того, как оно полностью запустится и получит событие deviceready. По этой причине маловероятно, что вам нужно вызывать navigator.splashscreen.show() для отображения заставки при запуске приложения.