cordova-plugin-splashscreen

Для работы со стартовыми экранами требуется этот плагин. Этот плагин отображает и скрывает стартовый экран во время запуска приложения.

Установка

// 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

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

• Android
• iOS
• Windows (cordova-windows версия >= 4.4.0 требуется)
• Браузер

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

Сведения, специфичные для iOS

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

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

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

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

Предпочтительный способ предоставления изображений стартового экрана — использование изображений стартового сториборда. Для разработчиков приложений под native идеальным стартовым сторибордом является пустой вариант пользовательского интерфейса приложения при запуске. Однако для разработчиков non-native приложений, которые не желают изучать 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. Если это не так, устройство может не отобразить его должным образом или вообще не отобразить.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Масштаб

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

Варианты устройств

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

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

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

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

<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" />
<preference name="SplashScreenSpinnerColor" value="white" />

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

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

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

Настройка «SplashScreenSpinnerColor» также необязательна и игнорируется, если не задана. Установка ее на допустимое имя цвета или код цвета в формате HEX изменит цвет вращающегося индикатора на устройствах Android 5.0 и выше.

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

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

<platform name="browser">
    <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" -->
    <preference name="AutoHideSplashScreen" value="true" /> <!-- defaults to "true" -->
    <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();

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