@ionic-native/in-app-browser

本项目基于 @ionic-native/[email protected]开发。

简介

一个用于在应用内部加载网页的插件，提供了一个全功能的浏览器视图，支持自定义工具栏、导航控制等功能。兼容Android、iOS和OpenHarmony平台，为跨平台应用开发提供统一的浏览器管理能力。本文档主要说明在OpenHarmony系统中的应用。

在移动应用开发中，应用内浏览器是提升用户体验的重要组成部分。@ionic-native/in-app-browser插件通过封装原生平台API，为开发者提供了统一的跨平台接口，无需深入原生开发即可实现应用内浏览器的显示、隐藏和自定义功能。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @ionic-native/in-app-browser

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @ionic-native/in-app-browser

手动引入安装

1.添加插件配置

根据plugin.xml的config-json项，找到entry模块中config.xml文件，并根据param标签添加配置

<feature name="InAppBrowser">
  <param name="harmony-package" value="InAppBrowser" />
  <param name="onload" value="true" />
</feature>

2.修改 CMake 配置

根据plugin.xml的CMakeLists项，找到cordova模块，路径为target字段的文件CMakeLists.txt，添加add_library

add_library(cordova SHARED
  // ...
  inappbrowser/InAppBrowser.cpp
  // ...
)

3.复制源码文件

根据plugin.xml的source-file项，将src字段的路径代码复制到cordova模块中target-dir字段的目录中：

将源码中src/main/cpp/inappbrowser目录下的InAppBrowser.h、InAppBrowser.cpp文件引入到cordova模块中src/main/cpp/inappbrowser目录下。

将源码中src/main/ets/components/inappbrowserAction目录下的BrowserAction.ets文件引入到cordova模块中src/main/ets/components/inappbrowserAction目录下。

4.添加 ArkTS 配置

在cordova模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤3中拷贝的ets文件路径:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/inappbrowserAction/BrowserAction.ets"
        // ...
      ]
    }
  }
}

卸载

# hionic CLI卸载
hionic plugin remove @ionic-native/in-app-browser

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及

使用示例

示例1：在应用内打开网页

实现显示应用内浏览器并加载网页的功能。

import { InAppBrowser } from "@ionic-native/in-app-browser";

// 调用create方法创建浏览器窗口
const browser = InAppBrowser.create("https://www.example.com", 
    '_blank', 
    'location=yes,hidden=no,closebuttoncolor=#ff0000,fullscreen=yes');
// 添加beforeload类型监听
browser.addEventListener("beforeload", function(url){
    console.log("beforeload function:"+url);
});
// 添加loadstart类型监听
browser.addEventListener("loadstart", function(){
    console.log("loadstart function");
});
// 添加loadstop类型监听
browser.addEventListener("loadstop", function(){
    // 执行js返回arrayBuffer数据
    browser.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通知主浏览器
    browser.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的域名
    browser.executeScript({ file: "https://www.example.com/www/js/test.js" }, function(){
        browser.executeScript({ code:"test();" });
        console.log("execute callback:");
    });
    // 加载在线js，支持跨域加载
    browser.executeScript({ file: "https://www.*****.com/js/test.js" });
    // 加载rawfile/www/js/test.css,www.example.com:默认加载的rawfile的域名
    browser.insertCSS({ file: "https://www.example.com/css/test.css" });
    // 加载在线css
    browser.insertCSS({ file: "https://www.****.com/css/test.css" }, function(){
        console.log("css execute callback");
    });
    // 插入css代码，无回调函数
    browser.insertCSS({ code: "body{font-size:200px;}" });
    // 插入css代码，有回调函数
    browser.insertCSS({ code: "body{font-size:200px;}" }, function(){
        console.log("css execute callback");
    });
    console.log("loadstop function");
});
// 添加message类型监听
browser.addEventListener("message", function(message){
    console.log("message function:"+message);
});
// 添加exit类型监听
browser.addEventListener("exit", function(){
    console.log("exit function");
});
// 添加download类型监听
browser.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");
});
// 添加customscheme类型监听
browser.addEventListener("customscheme", function(para){
    console.log("customscheme function:"+JSON.stringify(para));
});
// 展示浏览器
browser.show();
// 隐藏浏览器
browser.hide();
// 关闭浏览器
browser.close();

使用说明

插件在全局对象 InAppBrowser 下暴露所有功能接口，使用前需确保设备就绪事件（deviceready）已触发。

1. 创建浏览器窗口

在应用内打开浏览器窗口。

方法签名

const inAppBrowserRef = InAppBrowser.create(url, target, options)

参数说明

| 参数 | 类型 | 描述 | | ---- | ---- | ---- | | url | string | 要加载的URL地址 | | target | string | 打开方式：_blank(新页面)、_system(系统浏览器)、_self(应用内) | | options | string | 浏览器配置选项 |

2. 显示浏览器窗口

显示隐藏的浏览器窗口（需先通过hidden=yes隐藏）。

方法签名

inAppBrowserRef.show()

3. 隐藏浏览器窗口

隐藏浏览器窗口（不关闭，可通过show()重新显示）。

方法签名

inAppBrowserRef.hide()

4. 关闭浏览器窗口

关闭浏览器窗口，释放资源。

方法签名

inAppBrowserRef.close()

5. 执行JavaScript代码

在浏览器页面中执行JavaScript代码，支持注入脚本文件或内联代码。

方法签名

inAppBrowserRef.executeScript(options, callback)

参数说明

| 参数 | 类型 | 描述 | | ---- | ---- | ---- | | options.code | string | 要执行的内联JavaScript代码 | | options.file | string | 要注入的外部脚本文件URL | | callback | function | 执行完成后的回调函数 |

6. 插入CSS样式

向浏览器页面中插入CSS样式，支持注入样式文件或内联样式。

方法签名

inAppBrowserRef.insertCSS(options, callback)

参数说明

| 参数 | 类型 | 描述 | | ---- | ---- | ---- | | options.code | string | 要插入的内联CSS代码 | | options.file | string | 要注入的外部CSS文件URL | | callback | function | 插入完成后的回调函数 |

7. 添加事件监听

监听插件事件。

方法签名

inAppBrowserRef.addEventListener(eventName, callback)

支持的事件类型

| 事件名 | 触发时机 | 事件参数 | | ---- | ---- | ---- | | loadstart | 页面开始加载时 | url：当前加载的URL | | loadstop | 页面加载完成时 | url：当前加载的URL | | loaderror | 页面加载失败时 | url：加载失败的URL，code：错误码，message：错误描述 | | exit | 浏览器窗口被关闭时 | 无 | | beforeload | 页面即将加载新URL前 | url：即将加载的URL | | message | 浏览器页面向应用发送消息时 | data：消息内容 |

配置说明

以下配置值可用：

| 数据 | 类型 | 描述 | | ---- | ---- | ---- | | location | string | 是否显示地址栏，yes显示，no隐藏 | | hidden | string | 是否隐藏浏览器，yes隐藏，no显示 | | fullscreen | string | 是否全屏显示，yes全屏，no非全屏 | | closebuttoncolor | string | 关闭按钮颜色 | | toolbar | string | 是否显示工具栏，yes显示，no隐藏 | | toolbarposition | string | 工具栏位置，top顶部，bottom底部 | | hidenavigationbuttons | string | 是否隐藏导航按钮，yes隐藏，no显示 | | clearcache | string | 是否在打开前清除缓存，yes清除，no不清除 | | clearsessioncache | string | 是否清除会话缓存，yes清除，no不清除 |

示例

核心配置（config.xml）

所有浏览器相关配置需在项目rawfile目录下的config.xml中声明，以下是完整配置示例：

载于：config.xml

<!-- 显示地址栏 -->
<preference name="InAppBrowserLocation" value="yes" />
<!-- 默认显示浏览器 -->
<preference name="InAppBrowserHidden" value="no" />
<!-- 全屏显示 -->
<preference name="InAppBrowserFullscreen" value="yes" />
<!-- 关闭按钮颜色 -->
<preference name="InAppBrowserCloseButtonColor" value="#ff0000" />
<!-- 显示工具栏 -->
<preference name="InAppBrowserToolbar" value="yes" />
<!-- 工具栏位置在顶部 -->
<preference name="InAppBrowserToolbarPosition" value="top" />
<!-- 显示导航按钮 -->
<preference name="InAppBrowserHideNavigationButtons" value="no" />
<!-- 打开前清除缓存 -->
<preference name="InAppBrowserClearCache" value="no" />
<!-- 不清除会话缓存 -->
<preference name="InAppBrowserClearSessionCache" value="no" />

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|           |---- ets  # ArkTS 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。