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. Наследованные изображения запуска: изображения имеют размер точно соответствующий размеру экрана устройства. Не поддерживает родное разрешение 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 запуска. Они похожи на наследованные изображения запуска выше, но существуют важные различия:

• изображения не специфичны для данного устройства.

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

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

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

Создание изображений storyboard запуска

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

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

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

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

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

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

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

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

Масштаб

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

Стили

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

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

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

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

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

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

Одно изображение экрана запуска

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

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

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

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

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

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

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

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

Многоизображенческий экран запуска

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

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

* Этот образ необходим для того, чтобы 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. Симулятор может не отображать ожидаемые изображения при запуске из командной строки При развертывании Xcode на определённый симулятор копируются только ресурсы, соответствующие характеристикам симулятора. Например, если вы пытаетесь запустить приложение на симуляторе iPhone 6s Plus, копируются только заставки запуска с разрешением @3x. Однако при компиляции из командной строки по умолчанию предполагается iPhone 5s, что означает копирование только заставок запуска с разрешением @2x. Если ваши заставки запуска отличаются незначительно, разница, скорее всего, останется незамеченной, но это означает, что единственный точный способ тестирования — это тестирование на физическом устройстве.

3. anyany должен быть предоставлен для других вариантов Если вы не предоставите версию anyany заставки запуска для конкретного масштаба и стиля, другие варианты (например, anycom, comany, и comcom) будут проигнорированы.

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

В файле 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>

<platform name="windows">
    <!-- images are determined by width and height. The following are supported -->
    <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"/>

Особенности 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() для отображения экрана загрузки при запуске приложения.