@capacitor/browser

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/browser是capacitor生态系统中的核心插件，提供在应用内唤起系统浏览器打开指定网络地址的能力，为跨平台应用开发提供浏览器调用适配能力。插件兼容Android、iOS等主流移动平台及浏览器环境，本文档仅说明在OpenHarmony环境下的使用情况。

API支持唤起系统浏览器加载指定URL、监听浏览器状态、移除事件监听等功能，调用便捷无需等待就绪事件。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/browser

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/browser

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/browser",
  "classpath": "Browser"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Browser)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Browser
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Browser目录下的Browser.h、Browser.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Browser目录下。

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 browser 插件
hionic plugin remove @capacitor/browser

约束与限制

兼容性

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

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

无需额外配置应用权限。

使用示例

示例1：基础用法 - 打开指定网页地址

import { Browser } from '@capacitor/browser';

// 打开系统浏览器访问指定URL
const openBrowser = async () => {
  try {
    await Browser.open({
      url: 'https://www.openharmony.cn/',
    });
    console.log('浏览器已成功唤起');
  } catch (error) {
    console.error('浏览器打开失败：', error);
  }
};

示例2：添加浏览器状态监听

import { Browser } from '@capacitor/browser';

// 添加浏览器打开完成监听
const addBrowserListener = async () => {
  try {
    const listener = await Browser.addListener('browserFinished', () => {
      console.log('浏览器已完成打开');
      // 此处可执行后续业务逻辑
    });
    console.log('已添加浏览器状态监听器');
  } catch (error) {
    console.error('添加浏览器监听器失败：', error);
  }
};

// 移除所有事件监听器
const removeAllBrowserListeners = async () => {
  try {
    await Browser.removeAllListeners();
    console.log('已移除浏览器的所有事件监听');
  } catch (error) {
    console.error('移除监听器失败：', error);
  }
};

使用说明

引入@capacitor/browser插件的Browser模块使用，所有API均基于Promise实现，支持异步调用，无需等待就绪事件。

1. 打开浏览器加载地址

方法签名

open(options: OpenOptions): Promise<void>

OpenOptions

| 参数名 | 类型 | 说明 | 备注 | |-------------------|------------------------|----------------------------|--------------------| | url | string | 需要打开的网页地址，必传 | 支持http/https协议 | | windowName | string | 浏览器打开的可选目标，对应window.open属性 | 仅限网页端，默认_blank | | toolbarColor | string | 工具栏颜色，十六进制色值 | OpenHarmony系统不生效 | | presentationStyle | 'fullscreen'丨'popover' | 浏览器呈现风格 | 仅限iOS，默认全屏 | | width | number | 窗口宽度，单位px | OpenHarmony仅自由窗口生效 | | height | number | 窗口高度，单位px | OpenHarmony仅自由窗口生效 |

2. 关闭浏览器

方法签名

close(): Promise<void>

说明

仅限Web和iOS平台，OpenHarmony系统不支持该方法。

3. 事件监听

方法签名

addListener('browserFinished', listenerFunc: () => void): Promise<PluginListenerHandle>
addListener('browserPageLoaded', listenerFunc: () => void): Promise<PluginListenerHandle>
removeAllListeners(): Promise<void>

监听说明

| 监听方法 | 返回类型 | 说明 | 备注 | |---------------------------------------|--------------------------------------------------------------|-------------|---------------| | addListener('browserFinished', ...) | Promise<PluginListenerHandle> | 监听浏览器打开完成事件 | 全平台支持 | | addListener('browserPageLoaded', ...) | Promise<PluginListenerHandle> | 监听页面加载完成事件 | 仅限Android和iOS | | removeAllListeners() | Promise<void> | 移除插件所有原生监听器 | 全平台支持 |

PluginListenerHandle

| 属性名 | 类型 | |--------|---------------------------| | remove | () => Promise<void> |

目录结构

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

贡献代码

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

许可证

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