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 веб-вью. InAppBrowser не подлежит политике белого списка, как и открытие ссылок в системном браузере.

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

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

delete window.open // Reverts the call back to its 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 для загрузки (String). Вызовите encodeURI() для этого URL, если он содержит символы Юникода.
target: Целевой объект для загрузки URL, необязательный параметр, по умолчанию _self. (String)
- _self: Открывает в Cordova WebView, если URL находится в белом списке, в противном случае открывает в InAppBrowser.
- _blank: Открывает в InAppBrowser.
- _system: Открывает в системном веб-браузере.
options: Параметры для InAppBrowser. Необязательный параметр, по умолчанию: location=yes. (String)

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

Все платформы поддерживают:
- location: Установите в yes или no для включения или отключения строки состояния URL в InAppBrowser.
Android поддерживает следующие дополнительные параметры:
- hidden: Установите в yes для создания браузера и загрузки страницы без её отображения. Событие loadstop срабатывает по завершении загрузки. Опустите или установите в no (по умолчанию) для открытия и обычной загрузки браузера.
- clearcache: Установите в yes для очистки кэша файлов cookie браузера перед открытием нового окна.
- clearsessioncache: Установите в yes для очистки кэша файлов cookie сессии перед открытием нового окна.
- closebuttoncaption: Установите строку, которая будет использоваться в качестве подписи кнопки закрытия вместо символа X. Обратите внимание, что вам необходимо самостоятельно локализовать это значение.
- closebuttoncolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета кнопки закрытия от стандартного к указанному, независимо от того, является ли она текстовой или имеет стандартный символ X. Эффективен только при установленном параметре location в yes.
- footer: Установите в yes для отображения кнопки закрытия в футере, аналогично кнопке Готово в iOS. Кнопка закрытия будет отображаться так же, как и для заголовка, поэтому для настройки её свойств используйте параметры closebuttoncaption и closebuttoncolor.
- footercolor: Установите допустимое шестнадцатеричное цветовое значение, например #00ff00 или #CC00ff00 (#aarrggbb) , для изменения цвета футера от стандартного. Эффективен только при установленном параметре footer в yes.
- hardwareback: Установите в yes для использования кнопки "Назад" оборудования для навигации по истории InAppBrowser. Если предыдущей страницы нет, InAppBrowser закроется. Значение по умолчанию — yes, поэтому вы должны установить его в no, если хотите, чтобы кнопка "Назад" просто закрывала InAppBrowser.
- hidenavigationbuttons: Установите в yes для скрытия кнопок навигации в панели инструментов местоположения, эффективно только если user имеет location установлен на yes. Значение по умолчанию - no.
- hideurlbar: Установите в yes для скрытия строки URL в панели инструментов местоположения, эффективно только если user имеет location установлен на yes. Значение по умолчанию - no.
- navigationbuttoncolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета обеих кнопок навигации от стандартного. Эффективен только если location установлен на yes и не установлен hidenavigationbuttons в значение yes.
- toolbarcolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета панели инструментов от стандартного. Эффективен только если location установлен на yes.
- zoom: Установите в yes для отображения элементов управления масштабированием браузера Android, установите в no для их скрытия. Значение по умолчанию - yes.
- mediaPlaybackRequiresUserAction: Установите в yes для предотвращения автоматического воспроизведения HTML5 аудио или видео (по умолчанию no).
- shouldPauseOnSuspend: Установите в yes для приостановки/возобновления WebView InAppBrowser вместе с приложением, чтобы остановить воспроизведение звука в фоновом режиме (это может потребоваться для предотвращения проблем с Google Play, как описано в CB-11013).
- useWideViewPort: Определяет, должен ли WebView поддерживать тег мета-тега "viewport" HTML или использовать широкий viewport. Когда значение параметра равно no, ширина макета всегда устанавливается в ширину элемента управления WebView в устройствах (CSS) пикселях. Когда значение равно yes и страница содержит тег viewport, используется значение ширины, указанное в теге. Если страница не содержит тег или не предоставляет ширину, будет использован широкий viewport. (По умолчанию yes).
iOS поддерживает следующие дополнительные параметры:
- hidden: Установите в yes для создания браузера и загрузки страницы без её отображения. Событие loadstop срабатывает по завершении загрузки. Опустите или установите в no (по умолчанию) для открытия и обычной загрузки браузера.
- clearcache: Установите в yes для очистки кэша файлов cookie браузера перед открытием нового окна.
- clearsessioncache: Установите в yes для очистки кэша файлов cookie сессии перед открытием нового окна.
- closebuttoncolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета кнопки Готово по умолчанию. Применимо только если панель инструментов не отключена.
- closebuttoncaption: Установите строку, которая будет использоваться в качестве подписи кнопки Готово. Обратите внимание, что вам необходимо самостоятельно локализовать это значение.
- disallowoverscroll: Установите в yes или no (по умолчанию no). Включает/отключает свойство UIWebViewBounce.
- hidenavigationbuttons: Установите в yes или no для включения/выключения кнопок навигации панели инструментов (по умолчанию no). Применимо только если панель инструментов не отключена.
- navigationbuttoncolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета от стандартного. Применимо только если кнопки навигации видимы.
- toolbar: Установите в yes или no для включения/выключения панели инструментов InAppBrowser (по умолчанию yes).
- toolbarcolor: Установите допустимое шестнадцатеричное цветовое значение, например: #00ff00, для изменения цвета панели инструментов от стандартного. Применимо только если панель инструментов не отключена.
- toolbartranslucent: Установите в yes или no для создания полупрозрачной (полупрозрачной) панели инструментов (по умолчанию 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). Размещает панель инструментов вверху или внизу окна.
- hidespinner: Установите в yes или no для изменения видимости индикатора загрузки (по умолчанию no).
Windows поддерживает следующие дополнительные параметры:
- hidden: Установите в yes для создания браузера и загрузки страницы без её отображения. Событие loadstop срабатывает по завершении загрузки. Опустите или установите в no (по умолчанию) для открытия и обычной загрузки браузера.
- hardwareback: Работает так же, как и на платформе Android.
- fullscreen: Установите в yes для создания управления браузером без рамки вокруг него. Обратите внимание, что если также указано location=no, пользователю не будет представлено управление для закрытия окна IAB.

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

Android
Браузер
iOS
OSX
Windows

Пример

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');

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

В настоящее время единственный поддерживаемый параметр target в OSX — _system.

_blank и _self параметры пока не реализованы и будут проигнорированы. Pull requests и исправления для их работы будут очень полезны.

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

Плагин реализован через iframe.
История навигации (кнопки back и forward в панели LocationBar) не реализованы.

InAppBrowser

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

Методы

addEventListener
removeEventListener
close
show
hide
executeScript
insertCSS

InAppBrowser.addEventListener

Добавляет обработчик события от InAppBrowser. (Доступно только при установке целевого параметра на значение '_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. (Строка)

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

Android
Браузер
iOS
Windows
OSX

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

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

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

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

InAppBrowser.removeEventListener

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

ref.removeEventListener(eventname, callback);

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

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

Android
Браузер
iOS
Windows

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

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)

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

Android
Браузер
iOS
Windows

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

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

InAppBrowser.show

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

ref.show();

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

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

Android
Браузер
iOS
Windows

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

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)

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

Android
iOS
Windows

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

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

InAppBrowser.executeScript

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

ref.executeScript(details, callback);

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

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

Android
Браузер
iOS
Windows

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

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. (Доступно только при установке целевого параметра на '_blank')

ref.insertCSS(details, callback);

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

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

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