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 при установке параметра target на '_blank'. (InAppBrowser)
url: URL для загрузки (Строка). Вызовите encodeURI() для этого URL, если он содержит символы Юникода.
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).
Только 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 через тег мета (по умолчанию 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.

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.

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.

ref.executeScript(details, callback);

ref: ссылка на окно InAppBrowser . (InAppBrowser)
injectDetails: данные о выполняемом скрипте, указывающие либо на ключ file, либо code . (Объект)
- file: URL скрипта для вставки.
- code: Текст скрипта для вставки.
callback: функция, которая выполняется после вставки JavaScript-кода.
- Если вставленный скрипт имеет тип code, функция обратного вызова выполняется с одним параметром, который является возвращаемым значением скрипта, обернутого в 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 docs вызванный скрипт может возвращать только строковые значения, в противном случае параметр, переданный в callback, будет [null].

InAppBrowser.insertCSS

Вставляет CSS в окно InAppBrowser.

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/6.x/reference/cordova-plugin-inappbrowser/index.html