@luqi_test/cordova-plugin-inappbrowser

v6.0.0

Published

9 days ago

Cordova Inappbrowser Plugin

0High
0Medium
0Low

luqi_tan

cordova inappbrowser ecosystem:cordova cordova-openharmony

cordova-plugin-inappbrowser

1. 插件介绍

cordova-plugin-inappbrowser 是 Apache Cordova 生态中用于在应用内打开外部网页或本地 HTML 文件的核心插件，它提供了一个独立于主应用 WebView 的浏览器组件，支持自定义窗口样式、控制导航行为、监听页面加载状态等功能。该插件解决了 Cordova 主应用 WebView 无法灵活控制外部页面访问的问题，同时避免了跳转系统浏览器导致用户离开应用的体验损耗，广泛应用于展示帮助文档、支付页面、第三方内容等场景。本文档主要说明该插件在OHOS系统中的应用。

插件具备以下核心特性：

多场景页面加载：支持加载远程 URL（如 https://example.com）、本地 HTML 文件（如 /pages/about.html）；
灵活窗口控制：可配置窗口是否显示地址栏、工具栏、关闭按钮，支持设置窗口大小、位置及是否全屏，适配不同 UI 设计需求；
完整导航功能：提供前进、后退、刷新、关闭等导航控制 API，支持拦截 URL 跳转，实现自定义路由逻辑（如拦截支付回调链接）；
丰富事件监听：支持监听页面加载开始、加载完成、加载失败、URL 变化、窗口关闭等事件，便于开发者处理页面状态变化；
跨平台兼容性：适配 Android、iOS、OHOS 等主流移动平台统一 API 调用方式，降低跨平台开发成本。

2. 支持平台

插件已针对以下操作系统和运行环境完成兼容性适配，确保页面加载与交互功能稳定运行：

Android：API 级别 21 及以上（覆盖 Android 5.0 及更高版本），支持主流品牌手机（如华为、小米、OPPO、三星等），适配 AndroidX 架构；
iOS：iOS 11.0 及以上，支持 iPhone、iPad 全系列设备，适配 notch 屏（刘海屏）、动态岛及分屏模式；
OHOS: 5.0及以上版本；
Windows：Windows 10 及以上，支持 UWP（通用 Windows 平台）应用，适配桌面端与平板端窗口布局；
Browser：主流桌面及移动浏览器（Chrome 70+、Firefox 65+、Edge 79+、Safari 13+），模拟独立浏览器窗口（通过弹窗或 iframe 实现）；
Electron：Electron 12.0 及以上，支持桌面端应用（Windows、macOS、Linux），适配桌面窗口管理逻辑。

3. 安装步骤

3.1 前提条件

在安装插件前，需确保开发环境满足以下要求：

已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 node -v 和 npm -v 命令验证版本；
已全局安装 HCordova CLI（v1.0.0 及以上），若未安装，执行以下命令：

npm install -g hcordova

已创建 Cordova 项目（若未创建，执行 hcordova create InAppBrowserApp com.example.inappbrowser 应用内浏览器示例 快速创建）；

3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下安装方式：

常用安装

安装稳定版本，适合大多数开发场景：

#全平台安装
hcordova plugin add cordova-plugin-inappbrowser

#指定OHOS平台安装
hcordova plugin add cordova-plugin-inappbrowser --platform ohos

从 GitHub 源码安装

#需指定平台安装
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-inappbrowser.git --platform ohos

安装指定版本

若项目需兼容特定版本，可指定版本号安装（例如安装 1.0.0 版本）：

hcordova plugin add [email protected] --platform ohos

3.3 插件卸载与查看

卸载插件：

#全平台卸载
hcordova plugin remove cordova-plugin-inappbrowser

#指定OHOS平台卸载
hcordova plugin remove cordova-plugin-inappbrowser --platform ohos

查看已安装插件：

hcordova plugin list

若输出结果包含 cordova-plugin-inappbrowser，则表示插件已成功安装。

4. 核心配置（config.xml）

插件的全局行为、平台特定参数需在项目根目录的 config.xml 文件中配置，确保应用内浏览器功能符合业务需求。以下是完整配置示例及参数说明：

<!--cordova内部系统导航条背景色 -->
<preference name="NavigationBarBackgroundColor" value="#F90707" />

<!--cordova内部系统导航条文字按钮颜色 -->
<preference name="NavigationBarFontColor" value="#ffffff" />

<!--cordova内部系统导航条title位置left|center|right -->
<preference name="NavigationBarFontAlign" value="center" />

<!--导航栏高度配置-->
<preference name="NavigationBarHeight" value="44" />

5. 核心 API 说明

插件通过全局对象 cordova.InAppBrowser.open 创建应用内浏览器实例，并通过实例暴露导航控制、事件监听等 API。所有 API 需在 deviceready 事件触发后调用（确保 Cordova 环境就绪）。

5.1 创建浏览器实例（open）

cordova.InAppBrowser.open 是创建应用内浏览器的核心方法，支持配置窗口样式、加载目标地址等参数，返回浏览器实例对象（InAppBrowserObject）。

方法说明

const inAppBrowserRef = cordova.InAppBrowser.open(
   url,            // 加载的URL或本地文件路径
   target,         // 窗口目标（决定打开方式）
   options         // 窗口样式配置（可选）
);

参数说明

Url参数说明：支持在线网页、本地路径等，举例如下：

//加载rawfile/local-url.html
var ref = cordova.InAppBrowser.open('/local-url.html');
//加载沙箱路径文件/data/storage/el2/base/files/local-url.html
cordova.InAppBrowser.open('/data/storage/el2/base/files/index.html', '_blank');
//使用file协议加载沙箱路径文件/data/storage/el2/base/files/local-url.html
cordova.InAppBrowser.open('file:///data/storage/el2/base/files/index.html', '_blank');
//加载在线网页
var ref = cordova.InAppBrowser.open('https://developer.huawei.com', '_blank');

target参数说明:

    __blank：打开新页面
    __system：系统浏览器打开
    __self:鸿蒙中扔打开新页面，不在主应用打开

options参数说明：

location:设置 yes 或者 no显示导航工具栏，默认是yes
hidden：设置 yes 或者 no显示或者隐藏内置浏览器，默认是no
beforeload:当URL将要加载到当前Web中时，让宿主应用程序有机会获得控制权，加载非HTTP(s)协议的跳转可以触发，其他情况下无法触发
clearcache:设置yes 或者 no 清除缓存，默认no
clearsessioncache:设置yes 或者 no 清除session cookie 默认 no
closebuttoncaption:设置一个字符串，代替X的关闭图标，默认是空字符串
closebuttoncolor:设置关闭图标或者字符串的颜色(返回按钮和标题颜色也是这个参数），例如closebuttoncolor=#ff0000,默认是空字符串
fullscreen:设置yes或者no是否全屏，默认no
title:自定义标题
navbarheight:导航条高度，默认高度是采用鸿蒙系统的默认高度，如果要保持和安卓或ios一致，可自定义设定高度
appendUserAgent:浏览器User-Agent增加内容

5.2 浏览器实例方法（InAppBrowserObject）

通过 cordova.InAppBrowser.open 返回的 InAppBrowserObject 实例，可调用以下方法控制浏览器行为：

| 方法名 | 功能说明 | 示例代码 | | ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | show() | 显示隐藏的浏览器窗口（需先通过 hidden=yes 隐藏） | inAppBrowserRef.show(); | | hide() | 隐藏浏览器窗口（不关闭，可通过 show() 重新显示） | inAppBrowserRef.hide(); | | close() | 关闭浏览器窗口，释放资源 | inAppBrowserRef.close(); | | executeScript(options) | 在浏览器页面中执行 JavaScript 代码，支持注入脚本文件或内联代码 | javascript // 注入内联代码（修改页面标题） inAppBrowserRef.executeScript({ code: "document.title = '修改后的标题';" }); // 注入外部脚本文件 inAppBrowserRef.executeScript({ file: "https://example.com/scripts/custom.js" }); | | insertCSS(options) | 向浏览器页面中插入 CSS 样式，支持注入样式文件或内联样式 | javascript // 注入内联样式（修改body背景色） inAppBrowserRef.insertCSS({ code: "body { background-color: #f5f5f5; }" }); // 注入外部样式文件 inAppBrowserRef.insertCSS({ file: "https://example.com/styles/custom.css" }); | | goBack() | 导航到上一页（若存在历史记录），无返回值 | inAppBrowserRef.goBack(); | | goForward() | 导航到下一页（若存在历史记录），无返回值 | inAppBrowserRef.goForward(); | | reload() | 刷新当前页面，无返回值 | inAppBrowserRef.reload(); | | reloadIgnoringCache() | 刷新当前页面，忽略缓存（强制加载最新内容） | inAppBrowserRef.reloadIgnoringCache(); | | stopLoading() | 停止当前页面加载（如用户点击 “取消加载”） | inAppBrowserRef.stopLoading(); |

示例代码

var ref = window.open("https://www.chuzhitong.com", 
    '_blank', 
    'location=yes,hidden=no,closebuttoncolor=#ff0000,fullscreen=yes');
//加载非HTTP(s)协议的跳转可以触发，其他情况下无法触发
ref.addEventListener("beforeload", function(url){
    alert("beforeload function:"+url);
});
ref.addEventListener("loadstart", function(){
    console.log("loadstart function");
});
ref.addEventListener("loadstop", function(){
    //执行js返回arrayBuffer数据
    ref.executeScript({code:"function test(){console.log('execute function');
        let buffer = new ArrayBuffer(1);
        let view = new Uint8Array(buffer);
        view[0] = 255; return buffer;} test();"},function(message){
        //message js执行结果的返回值支持string/number/bool/array/arrayBuffer
        function stringToUint8Array(str){
            var arr = [];
            for (var i = 0, j = str.length; i < j; ++i) {
                arr.push(str.charCodeAt(i));
            }
            var tmpUint8Array = new Uint8Array(arr);
            return tmpUint8Array
        }
        var temp = stringToUint8Array(atob(message));
        console.log("execute callback:"+temp[0]);
    });
    //执行js并调用postMessage通知主浏览器
    //消息函数例如cordova_iab.postMessage("")
    ref.executeScript({ code: "
        var message = 'this is the message';
        var messageObj = {my_message: message};
        var stringifiedMessageObj = JSON.stringify(messageObj);
        cordova_iab.postMessage(stringifiedMessageObj);"
    });
    //加载rawfile/www/js/test.js,www.example.com:默认加载的rawfile的域名
    ref.executeScript({ file: "https://www.example.com/www/js/test.js" }, function(){
        ref.executeScript({code:"test();"});//加载成功后，执行test.js文件里面的函数
        console.log("execute callback:");
    });
    //加载在线js，支持跨域加载
    ref.executeScript({ file: "https://www.*****.com/js/test.js" });
    //加载rawfile/www/js/test.css,www.example.com:默认加载的rawfile的域名
    ref.insertCSS({ file: "https://www.example.com/css/test.css" });
    //加载在线css
    ref.insertCSS({ file: "https://www.****.com/css/test.css" }, function(){
        console.log("css execute callback");
    });
    //插入css代码，无回调函数
    ref.insertCSS({ code: "body{font-size:200px;}" });
    //插入css代码，有回调函数
    ref.insertCSS({ code: "body{font-size:200px;}" }, function(){
        console.log("css execute callback");
    });
    console.log("loadstop function");
});
ref.addEventListener("message", function(message){
    console.log("message function:"+message);
});
ref.addEventListener("exit", function(){
    console.log("exit function");
});
ref.addEventListener("download", function(paras){
    //应用可以根据下载的url，设定保存的文件名
    console.log("download:"+JSON.stringify(paras));
    function downloadInAppBrowser(uri, fileName) {
        function onErrorReadFile(error) {
        }
        function successFun(fileEntry) {
        }
        function failFun(error) {
            console.log("An error has occurred: Code = " + error.code);
            console.log("upload error source " + error.source);
            console.log("upload error target " + error.target);
        }
        function progressFun(progressEvent) {
            var progress = progressEvent.loaded / progressEvent.total * 100;
            console.log("download:"+progress);
        }
        window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, 
            function(dirEntry) {
            var targetPath = dirEntry.toURL() + fileName;
            var fileTransfer = new FileTransfer();
            fileTransfer.onprogress = progressFun;
            fileTransfer.download(
                uri,
                targetPath,
                successFun,
                failFun,
                false,
                {}
            );
        });
    }
    downloadInAppBrowser(paras.url, "ceshi.apk");
});
ref.addEventListener("customscheme", function(para){
    console.log("customscheme function:"+JSON.stringify(para));
});

5.3 事件监听

InAppBrowserObject 支持监听页面加载、URL 变化、窗口关闭等事件，通过 addEventListener 注册事件回调，removeEventListener 移除回调（避免内存泄漏）。

支持的事件类型

| 事件名 | 触发时机 | 事件参数（event 对象属性） | | ------------ | ------------------------------------------------ | ------------------------------------------------------------------------ | | loadstart | 页面开始加载时（包括初始加载和导航到新页面） | url：当前加载的 URL；code：状态码（仅部分平台支持）；message：状态信息（仅部分平台支持） | | loadstop | 页面加载完成时（DOM 渲染完成，资源可能仍在加载） | 同 loadstart | | loaderror | 页面加载失败时（如网络错误、404、500 等） | url：加载失败的 URL；code：错误码（如 -1：网络错误，404：未找到）；message：错误描述（如 “网络连接超时”） | | exit | 浏览器窗口被关闭时（用户点击关闭按钮或调用 close() 方法） | 无额外参数 | | beforeload | 页面即将加载新 URL 前（可拦截 URL，实现自定义路由） | url：即将加载的 URL；navigationType：导航类型（如 click：用户点击，reload：刷新） | | message | 浏览器页面向应用发送消息时（通过 window.opener.postMessage 发送） | data：消息内容；origin：消息来源 URL；source：消息发送源（仅部分平台支持） |

示例：事件监听与 URL 拦截

document.addEventListener('deviceready', function() {
   const inAppBrowserRef = cordova.InAppBrowser.open(
       'https://example.com',
       '_blank',
       'location=yes'
   );

   // 1. 监听页面加载状态
   inAppBrowserRef.addEventListener('loadstart', function(event) {
       console.log('开始加载：', event.url);
       // 显示加载中提示（如在主应用中显示进度条）
       document.getElementById('loading').style.display = 'block';
   });

   inAppBrowserRef.addEventListener('loadstop', function(event) {
       console.log('加载完成：', event.url);
       
       // 隐藏加载中提示
       document.getElementById('loading').style.display = 'none';

       // 加载完成后注入JS（监听页面消息）
       inAppBrowserRef.executeScript({
           code: `
               // 监听应用发送的消息
               window.addEventListener('message', function(event) {
                   if (event.data.type === 'FROM_APP') {
                       console.log('收到应用消息：', event.data.data);
                       // 页面向应用发送消息
                       window.opener.postMessage({ type: 'FROM_PAGE', data: '已收到消息' }, '*');
                   }
               });
           `
       });
   });

   inAppBrowserRef.addEventListener('loaderror', function(event) {
       console.error('加载失败：', event.url, '错误码：', event.code, '描述：', event.message);
       // 显示错误提示，提供重试按钮
       alert(`页面加载失败：${event.message}n是否重试？`);
       // 重试加载
       inAppBrowserRef.reload();
   });


   // 3. 监听页面发送的消息
   inAppBrowserRef.addEventListener('message', function(event) {
       console.log('收到页面消息：', event.data);
       if (event.data.type === 'FROM_PAGE') {
           alert(`页面回复：${event.data.data}`);
       }
   });

   // 4. 监听窗口关闭事件
   inAppBrowserRef.addEventListener('exit', function() {
       console.log('浏览器窗口已关闭');
       // 释放资源，清理事件监听
       inAppBrowserRef.removeEventListener('loadstart');
       inAppBrowserRef.removeEventListener('loadstop');
       inAppBrowserRef.removeEventListener('loaderror');
       inAppBrowserRef.removeEventListener('beforeload');
       inAppBrowserRef.removeEventListener('message');
       inAppBrowserRef.removeEventListener('exit');
   });

}, false);

6. 许可证

本插件基于 Apache 许可证 2.0 版开源。详见 LICENSE 文件。

7 联系我们

Apache Cordova：访问 Apache Cordova 官方仓库
OHOS cordova:访问https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-inappbrowser