cordova-plugin-inappbrowser 1.5.0

cordova-plugin-inappbrowser 1.5.0

×

测试测试过的✗
语言语言 Objective-CObjective C
许可证 Apache 2
发布最新发布2016年11月

由Holly Schinsky和Shazron Abdullah维护。

cordova-plugin-inappbrowser 1.5.0

  • 由
  • Adobe PhoneGap 团队

标题：Inappbrowser

描述：打开一个内联浏览器窗口。

Android iOS Windows 8.1 商店 Windows 8.1 手机 Windows 10 商店 Travis CI
Build Status Build Status Build Status Build Status Build Status

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窗口的行为像一个标准的网页浏览器，不能访问Cordova API。因此，如果您需要加载第三方（不受信任）的内容，建议使用InAppBrowser，而不是将其加载到主要的Cordova网页视图中。InAppBrowser不受白名单限制，也不受在系统浏览器中打开链接的限制。

InAppBrowser默认提供自己的用户GUI控件（后退、前进、完成）。

为了向后兼容，此插件还挂钩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

在一个新的InAppBrowser实例、当前浏览器实例或系统浏览器中打开URL。

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

  • ref：当目标设置为'_blank'时，对InAppBrowser窗口的引用。（InAppBrowser）

  • url：要加载的URL （字符串）。如果URL包含Unicode字符，请对此调用encodeURI()。

  • target：在哪个目标中加载URL，这是一个可选参数，默认为_self。 （字符串）

    • _self：如果在白名单中，则在Cordova WebView中打开，否则在InAppBrowser中打开。
    • _blank：在InAppBrowser中打开。
    • _system：在系统的网络浏览器中打开。

  • options：InAppBrowser的选项。可选，默认为：location=yes。 （字符串）

    选项字符串不得包含任何空白字符，并且每个功能的名称/值对必须通过逗号分隔。功能名称不区分大小写。所有平台都支持以下值

    • 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暂停/恢复与应用程序一起以停止后台音频（这在避免如CB-11013中描述的Google Play问题时可能是必要的）。

    仅限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以防止通过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以设置<a href="http://developer.apple.com/library/ios/documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalPresentationStyle">呈现样式</a>（默认是fullscreen）。
    • 过渡样式：将其设置为 fliphorizontal、crossdissolve 或 coververtical 以设置 过渡样式（默认为 coververtical）。
    • 工具栏位置：设置为 top 或 bottom（默认为 bottom）。这将使工具栏位于窗口的顶部或底部。

    仅限Windows系统

    • hidden：设置为yes以创建浏览器并加载数页，但不显示它。当加载完成时触发loadstop事件。省略或设置为no（默认）以正常打开和加载浏览器。
    • 全屏：将其设置为 yes 以在不环绕边框的情况下创建浏览器控件。请注意，如果还指定了 location=no，则用户将没有控件可以关闭IAB窗口。
    • 硬件后退：与Android平台上的行为相同。

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • 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 特殊问题

作为插件不强制任何设计，如果使用 target='_blank' 打开，需要添加一些CSS规则。规则可能如下所示

.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;
}

Windows 特殊问题

Windows 8.0、8.1 和 Windows Phone 8.1 不支持在 Cordova WebView 中打开远程 URL，因此如果使用 target='_self' 打开，远程 URL 将始终显示在系统的网络浏览器中。

在 Windows 10 上，如果 URL 不在白名单中并且使用 target='_self' 打开，它将在系统的网络浏览器中显示，而不是 InAppBrowser 弹出窗口。

类似于 Firefox OS，可以通过 inAppBrowserWrap/inAppBrowserWrapFullscreen CSS 类覆盖 IAB 窗口的视觉行为。

浏览器特殊问题

  • 插件通过 iframe 实现

  • 导航历史记录（LocationBar 中的 back 和 forward 按钮）未实现。

InAppBrowser

当目标设置为 '_blank' 时，从 cordova.InAppBrowser.open 调用返回的对象。

方法

  • addEventListener
  • removeEventListener
  • close
  • show
  • 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 属性

  • 类型：事件名称，可以是 loadstart、loadstop、loaderror 或 exit。 (String)

  • URL：所加载的URL。 (String)

  • 代码：错误代码，仅在 loaderror 情况下。 (Number)

  • 消息：错误消息，仅在 loaderror 情况下。 (String)

支持的平台

  • 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：停止监听的事件。 (String)

    • 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.executeScript

将 JavaScript 代码注入 InAppBrowser 窗口

ref.executeScript(details, callback);

  • ref：对 InAppBrowser 窗口的引用。 (InAppBrowser)

  • injectDetails：运行脚本的详细信息，指定一个 file 或 code 键。 (Object)

    • 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 文档，被调用的脚本只能返回字符串值，否则传递给 回调 的参数将为 [null]。

InAppBrowser.insertCSS

将 CSS 注入到 InAppBrowser 窗口。

ref.insertCSS(details, callback);

  • ref：指向 InAppBrowser 窗口引用 (InAppBrowser)

  • injectDetails：运行脚本的详细信息，指定一个 file 或 code 键。 (Object)

    • 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.net.cn/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