cordova-plugin-inappbrowser

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

Для получения нескольких идей, ознакомьтесь с примером внизу этой страницы или перейдите непосредственно к ссылке.

Этот плагин предоставляет представление веб-браузера, которое отображается при вызове cordova.InAppBrowser.open().

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');

Функция cordova.InAppBrowser.open() определена как прямая замена функции window.open(). Существующие вызовы window.open() могут использовать окно InAppBrowser, заменив window.open:

window.open = cordova.InAppBrowser.open;

Окно InAppBrowser ведет себя как стандартный веб-браузер и не может получить доступ к API Cordova. По этой причине InAppBrowser рекомендуется, если вам нужно загрузить контент сторонних (ненадёжных) источников, вместо загрузки его в основное Cordova webview. InAppBrowser не подчиняется списку разрешённых сайтов, как и открытие ссылок в системном браузере.

InAppBrowser по умолчанию предоставляет собственные элементы управления для пользователя (назад, вперёд, завершить).

Для обратной совместимости этот плагин также подключает window.open. Однако, подключённый плагином обработчик window.open может иметь непредвиденные последствия (особенно если этот плагин включён только как зависимость другого плагина). Обработчик window.open будет удалён в будущей основной версии выпуска. До удаления обработчика из плагина приложения могут вручную восстановить стандартное поведение:

delete window.open // Reverts the call back to it's prototype's default

Хотя window.open находится в глобальной области видимости, InAppBrowser недоступен до события deviceready.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log("window.open works well");
}

Отправлять проблемы с этим плагином на отслеживатель проблем Apache Cordova

Ссылка

Установка

cordova plugin add cordova-plugin-inappbrowser

Если вы хотите, чтобы все загрузки страниц в вашем приложении происходили через InAppBrowser, вы можете просто подключить window.open во время инициализации. Например:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    window.open = cordova.InAppBrowser.open;
}

cordova.InAppBrowser.open

Открывает URL в новом InAppBrowser экземпляре, текущем экземпляре браузера или системном браузере.

var ref = cordova.InAppBrowser.open(url, target, options);

ref: Ссылка на окно InAppBrowser при назначении целевого параметра '_blank'. (InAppBrowser)
url: URL для загрузки (Строка). Вызовите encodeURI() для этой ссылки, если она содержит символы Юникода.
target: Цель для загрузки URL, необязательный параметр, по умолчанию _self. (Строка)
- _self: Открывается в Cordova WebView, если URL находится в списке разрешённых, в противном случае открывается в InAppBrowser.
- _blank: Открывается в InAppBrowser.
- _system: Открывается в системном веб-браузере.
options: Параметры для InAppBrowser. Необязательно, по умолчанию: location=yes. (Строка)

Строка options не должна содержать пробелов, а имена/значения каждой функции должны быть разделены запятой. Имена функций не чувствительны к регистру. Все платформы поддерживают значение ниже:
- location: Установите в yes или no для включения или выключения строки состояния InAppBrowser.
Только для Android:
- hidden: установите в yes для создания браузера и загрузки страницы, но не отображения её. Событие loadstop срабатывает после завершения загрузки. Опустите или установите в no (по умолчанию), чтобы браузер открылся и загрузил страницу в обычном режиме.
- clearcache: Установите в yes для очистки кэша файлов cookie браузера перед открытием нового окна
- clearsessioncache: Установите в yes для очистки кэша файлов cookie сессии перед открытием нового окна
- zoom: Установите в yes для отображения элементов управления масштабированием Android браузера, установите в no для скрытия их. Значение по умолчанию yes.
- hardwareback: Установите в yes для использования аппаратной кнопки "назад" для навигации по истории InAppBrowser. Если предыдущей страницы нет, InAppBrowser закроется. Значение по умолчанию yes, поэтому необходимо установить в no, если вы хотите, чтобы кнопка "назад" просто закрывала InAppBrowser.
- mediaPlaybackRequiresUserAction: Установите в yes для предотвращения автоматического воспроизведения аудио или видео HTML5 (по умолчанию no).
- shouldPauseOnSuspend: Установите в yes для приостановки/возобновления InAppBrowser WebView с приложением, чтобы остановить воспроизведение звука в фоновом режиме (это может потребоваться, чтобы избежать проблем с Google Play, как описано в CB-11013).
- useWideViewPort: Определяет, должен ли WebView поддерживать тег мета "viewport" HTML или использовать широкий viewport. Когда значение настройки no, ширина макета всегда устанавливается в ширину элемента управления WebView в независимых от устройства (CSS) пикселях. Когда значение yes и страница содержит тег viewport, используется значение ширины, указанное в теге. Если страница не содержит тег или не задаёт ширину, то будет использован широкий viewport. (Значение по умолчанию yes).
Только для iOS:
- closebuttoncaption: Установите строку, которая будет использоваться в качестве подписи кнопки Готово. Обратите внимание, что вам нужно самостоятельно локализовать это значение.
- disallowoverscroll: Установите в yes или no (значение по умолчанию no). Включает/выключает свойство UIWebViewBounce.
- hidden: установите в yes для создания браузера и загрузки страницы, но не отображения её. Событие loadstop срабатывает после завершения загрузки. Опустите или установите в no (по умолчанию), чтобы браузер открылся и загрузил страницу в обычном режиме.
- clearcache: Установите в yes для очистки кэша файлов cookie браузера перед открытием нового окна
- clearsessioncache: Установите в yes для очистки кэша файлов cookie сессии перед открытием нового окна
- toolbar: Установите в yes или no для включения или выключения панели инструментов InAppBrowser (по умолчанию yes)
- enableViewportScale: Установите в yes или no для предотвращения масштабирования viewport через тег meta (значение по умолчанию no).
- mediaPlaybackRequiresUserAction: Установите в yes для предотвращения автоматического воспроизведения аудио или видео HTML5 (по умолчанию no).
- allowInlineMediaPlayback: Установите в yes или no для разрешения встроенного воспроизведения медиа HTML5, отображения в окне браузера, а не в специфичном для устройства интерфейсе воспроизведения. Элемент HTML video также должен содержать атрибут webkit-playsinline (значение по умолчанию no).
- keyboardDisplayRequiresUserAction: Установите в yes или no для открытия клавиатуры при получении фокуса элементами формы через вызов JavaScript focus() (значение по умолчанию yes).
- suppressesIncrementalRendering: Установите в yes или no для ожидания получения всего нового содержимого представления перед его отрисовкой (значение по умолчанию no).
- presentationstyle: Установите в pagesheet, formsheet или fullscreen для задания стиля представления (значение по умолчанию fullscreen).
- transitionstyle: Установите в fliphorizontal, crossdissolve или coververtical для задания стиля перехода (значение по умолчанию coververtical).
- toolbarposition: Установите в top или bottom (значение по умолчанию bottom). Размещает панель инструментов вверху или внизу окна.
Только для Windows:
- hidden: установите в yes для создания браузера и загрузки страницы, но не отображения её. Событие loadstop срабатывает после завершения загрузки. Опустите или установите в no (по умолчанию), чтобы браузер открылся и загрузил страницу в обычном режиме.
- fullscreen: Установите в yes для создания элемента управления браузера без рамки вокруг него. Обратите внимание, что если также указано location=no, пользователю не будет представлен элемент управления для закрытия окна IAB.
- hardwareback: работает так же, как и на платформе Android.

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

Amazon Fire OS
Android
BlackBerry 10
Firefox OS
iOS
OSX
Windows 8 и 8.1
Windows Phone 7 и 8
Браузер

Пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
var ref2 = cordova.InAppBrowser.open(encodeURI('http://ja.m.wikipedia.org/wiki/ハングル'), '_blank', 'location=yes');

Особенности Firefox OS

Так как плагин не накладывает никаких ограничений на дизайн, необходимо добавить некоторые правила CSS, если он открыт с target='_blank'. Правила могут выглядеть так

.inAppBrowserWrap {
  background-color: rgba(0,0,0,0.75);
  color: rgba(235,235,235,1.0);
}
.inAppBrowserWrap menu {
  overflow: auto;
  list-style-type: none;
  padding-left: 0;
}
.inAppBrowserWrap menu li {
  font-size: 25px;
  height: 25px;
  float: left;
  margin: 0 10px;
  padding: 3px 10px;
  text-decoration: none;
  color: #ccc;
  display: block;
  background: rgba(30,30,30,0.50);
}
.inAppBrowserWrap menu li.disabled {
    color: #777;
}

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

В настоящее время единственная поддерживаемая цель в OSX — _system.

_blank и _self цели пока не реализованы и игнорируются молча. Заметки, предложения и исправления, чтобы эти функции заработали, высоко ценятся.

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

Windows 8.0, 8.1 и Windows Phone 8.1 не поддерживают открытие удалённых URL в Cordova WebView, поэтому удалённые URL всегда отображаются в системном веб-браузере, если открываются с target='_self'.

В Windows 10, если URL НЕ находится в списке разрешённых и открывается с target='_self' он будет отображаться в системном веб-браузере вместо всплывающего окна InAppBrowser.

Аналогично Firefox OS, визуальное поведение окна IAB может быть переопределено с помощью классов CSS inAppBrowserWrap/inAppBrowserWrapFullscreen.

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

Плагин реализован с помощью iframe,
История навигации (кнопки back и forward в строке состояния) не реализованы.

InAppBrowser

Объект, возвращаемый функцией cordova.InAppBrowser.open при установке параметра target в значение '_blank'.

Методы

addEventListener
removeEventListener
close
show
hide
executeScript
insertCSS

InAppBrowser.addEventListener

Добавляет обработчик события из InAppBrowser. (Доступно только при установке параметра target в значение '_blank')

ref.addEventListener(eventname, callback);

ref: ссылка на окно InAppBrowser (InAppBrowser)
eventname: событие для прослушивания (Строка)
- loadstart: событие срабатывает, когда InAppBrowser начинает загрузку URL.
- loadstop: событие срабатывает, когда InAppBrowser завершает загрузку URL.
- loaderror: событие срабатывает, когда у InAppBrowser возникает ошибка при загрузке URL.
- exit: событие срабатывает, когда окно InAppBrowser закрывается.
callback: функция, которая выполняется при срабатывании события. Функции передаётся объект InAppBrowserEvent в качестве параметра.

Пример

var inAppBrowserRef;

function showHelp(url) {

    var target = "_blank";

    var options = "location=yes,hidden=yes";

    inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);

    inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);

    inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);

    inAppBrowserRef.addEventListener('loaderror', loadErrorCallBack);

}

function loadStartCallBack() {

    $('#status-message').text("loading please wait ...");

}

function loadStopCallBack() {

    if (inAppBrowserRef != undefined) {

        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });

        $('#status-message').text("");

        inAppBrowserRef.show();
    }

}

function loadErrorCallBack(params) {

    $('#status-message').text("");

    var scriptErrorMesssage =
       "alert('Sorry we cannot open that page. Message from the server is : "
       + params.message + "');"

    inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);

    inAppBrowserRef.close();

    inAppBrowserRef = undefined;

}

function executeScriptCallBack(params) {

    if (params[0] == null) {

        $('#status-message').text(
           "Sorry we couldn't open that page. Message from the server is : '"
           + params.message + "'");
    }

}

Свойства InAppBrowserEvent

type: имя события, либо loadstart, loadstop, loaderror, или exit. (Строка)
url: загруженный URL. (Строка)
code: код ошибки, только в случае loaderror. (Число)
message: сообщение об ошибке, только в случае loaderror. (Строка)

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

Amazon Fire OS
Android
iOS
Windows 8 и 8.1
Windows Phone 7 и 8
Браузер

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

События loadstart и loaderror не срабатывают.

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstart', function(event) { alert(event.url); });

InAppBrowser.removeEventListener

Удаляет обработчик события из InAppBrowser. (Доступно только при установке параметра target в '_blank')

ref.removeEventListener(eventname, callback);

ref: ссылка на окно InAppBrowser . (InAppBrowser)
eventname: событие, для которого нужно прекратить прослушивание. (Строка)
- loadstart: событие срабатывает, когда InAppBrowser начинает загрузку URL.
- loadstop: событие срабатывает, когда InAppBrowser завершает загрузку URL.
- loaderror: событие срабатывает, когда у InAppBrowser возникает ошибка при загрузке URL.
- exit: событие срабатывает, когда окно InAppBrowser закрывается.
callback: функция, которая выполняется при срабатывании события. Функции передаётся объект InAppBrowserEvent.

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

Amazon Fire OS
Android
iOS
Windows 8 и 8.1
Windows Phone 7 и 8
Браузер

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
var myCallback = function(event) { alert(event.url); }
ref.addEventListener('loadstart', myCallback);
ref.removeEventListener('loadstart', myCallback);

InAppBrowser.close

Закрывает окно InAppBrowser.

ref.close();

ref: ссылка на окно InAppBrowser (InAppBrowser)

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

Amazon Fire OS
Android
Firefox OS
iOS
Windows 8 и 8.1
Windows Phone 7 и 8
Браузер

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.close();

InAppBrowser.show

Отображает окно InAppBrowser, которое было открыто скрытым. Вызов не повлияет, если InAppBrowser уже отображался.

ref.show();

ref: ссылка на окно InAppBrowser (InAppBrowser)

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

Amazon Fire OS
Android
iOS
Windows 8 и 8.1
Браузер

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'hidden=yes');
// some time later...
ref.show();

InAppBrowser.hide

Скрывает окно InAppBrowser. Вызов не повлияет, если InAppBrowser уже скрыт.

ref.hide();

ref: ссылка на окно InAppBrowser (InAppBrowser)

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

Amazon Fire OS
Android
iOS
Windows 8 и 8.1

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank');
// some time later...
ref.hide();

InAppBrowser.executeScript

Вставляет JavaScript-код в окно InAppBrowser . (Доступно только при установке параметра target в '_blank')

ref.executeScript(details, callback);

ref: ссылка на окно InAppBrowser . (InAppBrowser)
injectDetails: детали выполняемого скрипта, указывающие либо на file , либо на code ключ. (Объект)
- file: URL скрипта для вставки.
- code: Текст скрипта для вставки.
callback: функция, которая выполняется после вставки JavaScript-кода.
- Если вставленный скрипт типа code, callback выполняется с одним параметром, который является возвращаемым значением скрипта, заключённым в Array. Для многострочных скриптов это возвращаемое значение последнего оператора или выражения, вычисленного последним.

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

Amazon Fire OS
Android
iOS
Windows 8 и 8.1
Браузер

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.executeScript({file: "myscript.js"});
});

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

поддерживается только ключ code.

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

Из-за MSDN документации вызванный скрипт может возвращать только строковые значения, в противном случае параметр, переданный в callback, будет [null].

InAppBrowser.insertCSS

Вставляет CSS в окно InAppBrowser . (Доступно только при установке параметра target в '_blank')

ref.insertCSS(details, callback);

ref: ссылка на окно InAppBrowser (InAppBrowser)
injectDetails: детали выполняемого скрипта, указывающие либо на file , либо на code ключ. (Объект)
- file: URL таблицы стилей для вставки.
- code: Текст таблицы стилей для вставки.
callback: функция, которая выполняется после вставки CSS.

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

Amazon Fire OS
Android
iOS
Windows

Быстрый пример

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.insertCSS({file: "mystyles.css"});
});

Пример: Отображение страниц справки с помощью InAppBrowser

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

Вот несколько фрагментов, которые показывают, как это сделать.

Предоставьте пользователям возможность запросить помощь.
Загрузите страницу справки.
Уведомьте пользователей о подготовке страницы.
Отобразите страницу справки.
Обработайте ошибки страницы.

Предоставьте пользователям возможность запросить помощь

В вашем приложении есть множество способов сделать это. Выпадающий список – простой способ.

<select id="help-select">
    <option value="default">Need help?</option>
    <option value="article">Show me a helpful article</option>
    <option value="video">Show me a helpful video</option>
    <option value="search">Search for other topics</option>
</select>

Получите выбор пользователя в функции onDeviceReady страницы, а затем отправьте соответствующий URL в вспомогательную функцию в каком-либо общем файле библиотеки. Наша вспомогательная функция называется showHelp() , и мы напишем её далее.

$('#help-select').on('change', function (e) {

    var url;

    switch (this.value) {

        case "article":
            url = "https://cordova.apache.org/docs/en/latest/"
                        + "reference/cordova-plugin-inappbrowser/index.html";
            break;

        case "video":
            url = "https://youtu.be/F-GlVrTaeH0";
            break;

        case "search":
            url = "https://www.google.com/#q=inAppBrowser+plugin";
            break;
    }

    showHelp(url);

});

Загрузите страницу справки

Мы будем использовать функцию open для загрузки страницы справки. Мы устанавливаем свойство hidden в значение yes, чтобы отобразить браузер только после загрузки содержимого страницы. Таким образом, пользователи не увидят пустой браузер, пока ожидают появления содержимого. Когда произойдёт событие loadstop, мы узнаем, когда содержимое загрузится. Мы обработаем это событие вскоре.

function showHelp(url) {

    var target = "_blank";

    var options = "location=yes,hidden=yes";

    inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);

    inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);

    inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);

    inAppBrowserRef.addEventListener('loaderror', loadErrorCallBack);

}

Уведомьте пользователей о подготовке страницы

Поскольку браузер не появляется сразу, мы можем использовать событие loadstart для отображения сообщения о статусе, прогресс-бара или другого индикатора. Это обеспечивает пользователям уверенность в том, что содержимое скоро появится.

function loadStartCallBack() {

    $('#status-message').text("loading please wait ...");

}

Отобразите страницу справки

Когда произойдёт событие loadstopcallback, мы узнаем, что содержимое загружено, и можем сделать браузер видимым. Этот трюк может создать впечатление лучшей производительности. На самом деле, независимо от того, отображаете ли вы браузер до загрузки содержимого или нет, время загрузки одинаковое.

function loadStopCallBack() {

    if (inAppBrowserRef != undefined) {

        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });

        $('#status-message').text("");

        inAppBrowserRef.show();
    }

}

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

Обработайте ошибки страницы

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

Мы попробуем показать эту ошибку в окне сообщения. Мы можем сделать это, вставив скрипт, который вызовет функцию alert . Однако это не сработает в браузерах на устройствах Windows, поэтому нам придётся посмотреть на параметр функции обратного вызова executeScript , чтобы увидеть, сработала ли наша попытка. Если это не сработало, мы просто покажем сообщение об ошибке в <div> на странице.

function loadErrorCallBack(params) {

    $('#status-message').text("");

    var scriptErrorMesssage =
       "alert('Sorry we cannot open that page. Message from the server is : "
       + params.message + "');"

    inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);

    inAppBrowserRef.close();

    inAppBrowserRef = undefined;

}

function executeScriptCallBack(params) {

    if (params[0] == null) {

        $('#status-message').text(
           "Sorry we couldn't open that page. Message from the server is : '"
           + params.message + "'");
    }

}

Дополнительная информация по использованию

Локальные URL (исходный код находится в пакете приложения)

var iab = cordova.InAppBrowser;

iab.open('local-url.html');                  // loads in the Cordova WebView
iab.open('local-url.html', '_self');         // loads in the Cordova WebView
iab.open('local-url.html', '_system');       // Security error: system browser, but url will not load (iOS)
iab.open('local-url.html', '_blank');        // loads in the InAppBrowser
iab.open('local-url.html', 'random_string'); // loads in the InAppBrowser
iab.open('local-url.html', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar

Разрешенный контент

var iab = cordova.InAppBrowser;

iab.open('http://whitelisted-url.com');                  // loads in the Cordova WebView
iab.open('http://whitelisted-url.com', '_self');         // loads in the Cordova WebView
iab.open('http://whitelisted-url.com', '_system');       // loads in the system browser
iab.open('http://whitelisted-url.com', '_blank');        // loads in the InAppBrowser
iab.open('http://whitelisted-url.com', 'random_string'); // loads in the InAppBrowser

iab.open('http://whitelisted-url.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar

URL, не включенные в белый список

var iab = cordova.InAppBrowser;

iab.open('http://url-that-fails-whitelist.com');                  // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', '_self');         // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', '_system');       // loads in the system browser
iab.open('http://url-that-fails-whitelist.com', '_blank');        // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', 'random_string'); // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/7.x/reference/cordova-plugin-inappbrowser/index.html