@cordova-ohos/cordova-plugin-themeablebrowser
v0.2.19
Published
Cordova Themeable Browser Plugin
Readme
cordova-plugin-themeablebrowser
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-themeablebrowser 是一款功能强大的 Cordova 自定义主题浏览器插件，基于原生 cordova-plugin-inappbrowser 插件，提供高度可定制的 UI 样式、页面交互控制、功能扩展等核心能力。支持自定义导航栏、工具栏、颜色、图标、动画效果，可嵌入应用内作为内置浏览器，也可作为独立窗口打开外部链接，适用于应用内帮助中心、新闻资讯、支付页面、第三方内容展示等场景，为混合应用提供一致且个性化的网页浏览体验。
特别说明：内置浏览器插件已集成到 OHOS Cordova 框架中，在 html 页面中通过 <a href="https://**.***.com" target="_blank">打开新窗口</a> 就可以自动激活内置浏览器，打开在线网页、本地页面等。内置浏览器已经提供了导航栏、文字、图标等自定义配置，因此该插件在 OHOS 系统中并不是必须的，您可以直接通过框架的 config.xml 修改内置浏览器样式。点击查看 OHOS Cordova 框架
核心优势
全量 UI 定制：支持导航栏、工具栏、关闭按钮、进度条等所有 UI 元素的样式自定义（颜色、大小、图标、位置）
灵活交互控制：支持页面前进/后退、刷新、关闭、分享，可自定义按钮点击事件，支持手势关闭（iOS 侧滑）
功能扩展丰富：支持文件下载、Cookie 共享、JS 桥接（应用与网页通信）、页面加载进度监听
跨平台一致性：统一 Android/iOS/OHOS 浏览器样式与交互，支持平台专属配置
轻量高效：基于原生 WebView 优化，页面加载速度接近系统浏览器，无冗余依赖（体积＜80KB）
安全可靠：支持 HTTPS 加密传输、JS 注入限制，提供完善的错误回调机制
支持平台
Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+
下载安装
通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。
从 npm 安装（推荐）
# 使用 hcordova CLI 安装
# 安装 hcordova 命令化工具
npm install -g hcordova
# 全平台安装插件
hcordova plugin add cordova-plugin-themeablebrowser指定平台安装 ohos
仅为 OHOS 平台安装插件：
# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-themeablebrowser --platform ohos从 GitCode 仓库安装
仅为 OHOS 平台安装插件：
# 仅安装到 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-themeablebrowser.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-themeablebrowser.git@develop --platform ohos安装指定版本
# 仅安装到 OHOS 平台指定版本
hcordova plugin add [email protected] --platform ohos离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-themeablebrowser）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-themeablebrowser --platform ohos安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载
# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-themeablebrowser
# 指定平台卸载
hcordova plugin remove cordova-plugin-themeablebrowser --platform ohos约束与限制
依赖插件：无强制依赖，基于原生 cordova-plugin-inappbrowser 插件扩展，若需增强功能可搭配相关插件使用。
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过：
| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |
使用示例
// 目前 OHOS 支持以下新增的属性和监听事件，具体事件参考 cordova-plugin-inappbrowser 插件介绍
cordova.ThemeableBrowser.open(
'https://www.example.com',
'_blank',
{
statusbar: {
color: '#ffffffff'
},
toolbar: {
height: 44,
color: '#f0f0f0ff'
},
title: {
color: '#000000',
showPageTitle: true
},
backButton: {
event: 'backPressed'
},
closeButton: {
event: 'closePressed'
},
backButtonCanClose: true
}).addEventListener('backPressed', function(e) {
alert('back pressed');
}).addEventListener('closePressed', function(e) {
alert('closePressed');
});使用说明
配置参数（options）
配置参数（options）用于自定义 OHOS 系统中 ThemeableBrowser 窗口的外观、按钮及行为，以下仅列出当前 OHOS 版本支持的新增核心参数，与使用示例中的配置一一对应，未列出的参数可参考 cordova-plugin-inappbrowser 插件官方文档。
所有颜色值均支持十六进制格式（如 #ffffffff，前 6 位为颜色值，后 2 位为透明度，透明度范围 00-ff，00 为完全透明，ff 为完全不透明），数值类参数单位默认与系统一致（如 toolbar 高度单位为 px）。
1. statusbar（状态栏配置）
用于配置浏览器窗口状态栏的外观，仅支持 color 属性。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | color | String | 必选，状态栏背景颜色，支持十六进制颜色+透明度格式 | #ffffffff（白色不透明） |
2. toolbar（工具栏配置）
用于配置浏览器窗口工具栏（导航栏）的外观，支持高度和背景颜色设置。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | height | Number | 可选，工具栏高度，默认值根据系统自适应，建议设置为 44px（适配 OHOS 主流设备） | 44 | | color | String | 必选，工具栏背景颜色，支持十六进制颜色+透明度格式 | #f0f0f0ff（浅灰色不透明） |
3. title（标题栏配置）
用于配置浏览器窗口标题的外观及显示规则。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | color | String | 必选，标题文字颜色，支持十六进制纯颜色值（无需透明度，仅控制文字颜色） | #000000（黑色） | | showPageTitle | Boolean | 可选，是否显示当前网页的标题，true 显示，false 隐藏，默认值为 true | true |
4. backButton（返回按钮配置）
用于配置浏览器返回按钮的事件绑定，点击返回按钮时触发绑定的事件。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | event | String | 必选，返回按钮点击时触发的事件名称，需与 addEventListener 绑定的事件名一致 | backPressed |
5. closeButton（关闭按钮配置）
用于配置浏览器关闭按钮的事件绑定，点击关闭按钮时触发绑定的事件。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | event | String | 必选，关闭按钮点击时触发的事件名称，需与 addEventListener 绑定的事件名一致 | closePressed |
6. backButtonCanClose（返回按钮关闭权限配置）
用于控制点击返回按钮时，是否允许关闭浏览器窗口。
| 参数名 | 类型 | 说明 | 示例 | |---|---|---|---| | backButtonCanClose | Boolean | 可选，true 表示点击返回按钮可关闭浏览器窗口，false 表示仅触发 backPressed 事件、不关闭窗口，默认值为 false | true |
补充说明
配置参数需与使用示例中的属性严格对应，事件名（如 backPressed、closePressed）可自定义，但需保证 backButton/closeButton 的 event 参数与 addEventListener 绑定的事件名一致，否则事件无法触发。
颜色值建议使用十六进制格式。
除上述参数外，未列出的配置参数及事件，可参考 cordova-plugin-inappbrowser 插件官方文档，当前 OHOS 版本均兼容其基础功能。
目录结构
cordova-plugin-themeablebrowser # [根目录] 可定制主题浏览器插件项目根目录
├── src # [源码目录] 存放原生平台代码
│ └── main # [主目录] 主代码目录
│ ├── cpp # [C++ 目录] C++ 原生代码目录
│ │ └── inappbrowser # [C++ 模块] 应用内浏览器 C++ 模块文件夹（注意文件夹名为小写）
│ │ ├── ThemeableBrowser.cpp # [C++ 实现] C++ 源文件，实现浏览器核心逻辑及主题控制
│ │ └── ThemeableBrowser.h # [C++ 声明] C++ 头文件，定义浏览器接口
│ └── ets # [ArkTS 目录] ArkTS/ETS 代码目录
│ └── components # [组件目录] 存放 UI 组件
│ └── InAppBrowser # [TS 模块] 应用内浏览器 UI 组件文件夹
│ └── BrowserAction.ets # [ETS 文件] 浏览器操作栏（如前进、后退、关闭按钮）的 UI 实现
├── www # [前端目录] 存放供 Web 端调用的 JS 接口文件
│ └── themeablebrowser.js # [JS 文件] 暴露给 Web 端的 JS 接口，用于打开可定制浏览器
├── .gitignore # [配置] Git 版本控制忽略文件配置
├── LICENSE # [文本] 开源许可证文件
├── OAT.xml # [配置] 门禁配置文件
├── package.json # [配置] NPM 包配置文件，包含插件版本、依赖等信息
├── plugin.xml # [配置] Cordova 插件核心配置文件，定义插件元数据、文件映射等
└── README.md # [文档] 项目说明文档，通常包含安装和使用指南贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。
官方资源
内置浏览器 Apache Cordova：访问 Apache Cordova 官方仓库
OHOS cordova-plugin-themeablebrowser：访问 https://gitcode.com/CPF-Cordova/cordova-plugin-themeablebrowser
cordova-plugin-inappbrowser 插件：访问 https://gitcode.com/CPF-Cordova/cordova-plugin-inappbrowser