cordova-plugin-splashscreen

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

Сообщайте о проблемах с этим плагином на следящей за проблемами 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

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

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

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

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