npm package: @luqi_test/cordova-plugin-inappbrowser
Description: Cordova Inappbrowser Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 6.0.0

# 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 前提条件

在安装插件前，需确保开发环境满足以下要求：



1. 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；

2. 已全局安装 HCordova CLI（v1.0.0 及以上），若未安装，执行以下命令：



```bash
npm install -g hcordova
```

3. 已创建 Cordova 项目（若未创建，执行 `hcordova create InAppBrowserApp com.example.inappbrowser 应用内浏览器示例` 快速创建）；



### 3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下安装方式：

#### 常用安装

安装稳定版本，适合大多数开发场景：



```bash
#全平台安装
hcordova plugin add cordova-plugin-inappbrowser

#指定OHOS平台安装
hcordova plugin add cordova-plugin-inappbrowser --platform ohos
```

#### 从 GitHub 源码安装


```bash
#需指定平台安装
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-inappbrowser.git --platform ohos
```

#### 安装指定版本

若项目需兼容特定版本，可指定版本号安装（例如安装 1.0.0 版本）：


```bash
hcordova plugin add cordova-plugin-inappbrowser@1.0.0 --platform ohos
```

### 3.3 插件卸载与查看

* **卸载插件**：

```bash
#全平台卸载
hcordova plugin remove cordova-plugin-inappbrowser

#指定OHOS平台卸载
hcordova plugin remove cordova-plugin-inappbrowser --platform ohos
```

* **查看已安装插件**：

```bash
hcordova plugin list
```

若输出结果包含 `cordova-plugin-inappbrowser`，则表示插件已成功安装。

## 4. 核心配置（config.xml）

插件的全局行为、平台特定参数需在项目根目录的 `config.xml` 文件中配置，确保应用内浏览器功能符合业务需求。以下是完整配置示例及参数说明：

```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`）。

#### 方法说明

```js
const inAppBrowserRef = cordova.InAppBrowser.open(
   url,            // 加载的URL或本地文件路径
   target,         // 窗口目标（决定打开方式）
   options         // 窗口样式配置（可选）
);
```

#### 参数说明

* **Url**参数说明：支持在线网页、本地路径等，举例如下：

```js
//加载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**参数说明:

```js
    __blank：打开新页面
    __system：系统浏览器打开
    __self:鸿蒙中扔打开新页面，不在主应用打开
```

* **options**参数说明：

```js
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();`                                                                                                                                                                         |

#### 示例代码


```js
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 拦截


```js
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](LICENSE) 文件。


### 7 联系我们

1. **Apache Cordova**：访问 [Apache Cordova 官方仓库](https://github.com/apache/cordova-plugin-inappbrowser)

2. **OHOS cordova**:访问[https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-inappbrowser](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-inappbrowser)