@capacitor/inappbrowser

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

简介

@capacitor/inappbrowser是capacitor生态系统中的核心插件，用于在应用内部加载网页。它提供了一个全功能的浏览器视图，支持自定义工具栏、导航控制等功能，适用于显示第三方内容、加载外部网页等场景，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档仅说明其在OpenHarmony系统中的使用方法。

该插件提供可调用的InAppBrowser插件对象，支持在应用内打开新的浏览器窗口，提供多种打开方式（WebView、系统浏览器、外部浏览器），并配备丰富的配置选项，可灵活自定义浏览器的外观和行为，满足不同场景下的网页加载需求。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/inappbrowser

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/inappbrowser

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件，步骤如下：

1. 添加插件配置

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

{
  "pkg": "@capacitor/inappbrowser",
  "classpath": "InAppBrowser"
}

2. 修改 CMake 配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

{
  "buildOption": {
    // ...
    "arkOptions": {
      "runtimeOnly": [
        // ...
        "./src/main/ets/components/InAppBrowser/AppBrowser.ets"
        // ...
      ]
    }
  }
}

卸载

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

约束与限制

兼容性

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

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;

权限要求

无需额外配置应用权限。

功能限制

• OpenInWebViewOptions 中的 customHeaders 参数在OpenHarmony平台暂不支持。

• AndroidWebViewOptions 中的 pauseMedia 参数在OpenHarmony平台暂不支持。

• iOSWebViewOptions 中的 enableViewportScale、allowInLineMediaPlayback、surpressIncrementalRendering、viewStyle、 animationEffect、allowsBackForwardNavigationGestures 参数在OpenHarmony平台暂不支持（仅适配 iOS 平台）。

• close() 方法、所有 addListener 监听方法及 removeAllListeners 方法，仅支持关闭/监听通过 openInWebView 方法打开的应用内浏览器，不支持系统浏览器和外部浏览器。

使用示例

示例 1：在应用内打开网页（WebView 方式）

import { InAppBrowser } from '@capacitor/inappbrowser';

const openBrowser = async () => {
  // 打开网页，配置工具栏、URL显示等参数
  await InAppBrowser.openInWebView({
    url: 'https://www.example.com',
    options: {
      showToolbar: true, // 显示工具栏
      toolbarPosition: 'TOP', // 工具栏在顶部
      showURL: true, // 显示URL地址栏
      closeButtonText: '关闭', // 关闭按钮文本
      showNavigationButtons: true, // 显示前进/后退按钮
      clearCache: false // 不清除浏览器缓存
    }
  });
};

const closeBrowser = async () => {
  // 关闭当前打开的应用内浏览器
  await InAppBrowser.close();
};

示例 2：在系统浏览器/外部浏览器打开网页

import { InAppBrowser } from '@capacitor/inappbrowser';

// 在系统浏览器中打开网页
const openInSystemBrowser = async () => {
  await InAppBrowser.openInSystemBrowser({
    url: 'https://www.example.com'
  });
};

// 在外部浏览器应用中打开网页
const openInExternalBrowser = async () => {
  await InAppBrowser.openInExternalBrowser({
    url: 'https://www.example.com'
  });
};

示例 3：监听浏览器事件

import { InAppBrowser } from '@capacitor/inappbrowser';

// 监听浏览器关闭事件
const closeListener = await InAppBrowser.addListener('browserClosed', () => {
  console.log('浏览器已关闭');
});

// 监听网页加载完成事件
const loadedListener = await InAppBrowser.addListener('browserPageLoaded', () => {
  console.log('网页加载完成');
});

// 监听网页导航完成事件（返回当前URL）
const navigationListener = await InAppBrowser.addListener('browserPageNavigationCompleted', (info) => {
  console.log('网页导航完成，当前URL：', info.url);
});

// 移除所有监听器（无需监听时调用）
const removeAllListeners = async () => {
  await InAppBrowser.removeAllListeners();
};

使用说明

InAppBrowser 是插件导出对象，可直接导入使用，用于管理浏览器窗口的打开、关闭及事件监听。所有 API 均基于 Promise 实现，支持异步调用，适用于应用内加载第三方网页、外部链接等场景，使用前需确保插件已正确安装并配置。

核心 API：InAppBrowser 对象

InAppBrowser 是插件导出对象，用于管理浏览器窗口，提供多种打开方式、关闭操作及事件监听能力，调用便捷高效。

方法列表与说明

| 方法名 | 入参类型 | 功能描述 | |----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------| | openInWebView(...) | OpenInWebViewOptions | 在应用内 WebView 中打开 URL | | openInSystemBrowser(...) | { url: string } | 在系统浏览器（如 Chrome Custom Tabs）中打开 URL | | openInExternalBrowser(...) | { url: string } | 在外部浏览器应用中打开 URL | | close() | 无入参 | 关闭当前打开的浏览器窗口（仅支持关闭 openInWebView 打开的应用内浏览器） | | addListener(browserClosed丨 browserPageLoaded, ...) | eventName: 'browserClosed' 丨 'browserPageLoaded', listenerFunc: () => void | 监听插件事件 (无返回数据)（仅支持 openInWebView 打开的应用内浏览器） | | addListener(browserPageNavigationCompleted, ...) | eventName: 'browserPageNavigationCompleted', listenerFunc: (info: { url: string }) => void | 监听插件事件 (返回当前 URL)（仅支持 openInWebView 打开的应用内浏览器） | | removeAllListeners() | 无入参 | 移除所有监听器（仅支持 openInWebView 打开的应用内浏览器） |

接口定义

OpenInWebViewOptions

调用 openInWebView 方法时的入参对象，用于配置要加载的 URL 及浏览器窗口参数。

| 参数 | 类型 | 描述 | |-------------------|------------------------|---------------------------------| | url | string | 要加载的 URL 地址（必填）。 | | options | WebViewOptions | 浏览器窗口的配置选项。 | | customHeaders | Record<string, string> | 自定义 HTTP 请求头。（OpenHarmony平台不支持） |

WebViewOptions

配置浏览器窗口的外观和行为，可根据需求灵活设置。

| 参数 | 类型 | 描述 | |-------------------------------------|-------------------------------------------------|-----------------------------------------------| | showURL | boolean | 是否显示 URL 地址栏。 | | showToolbar | boolean | 是否显示工具栏（包含关闭、导航等按钮）。 | | clearCache | boolean | 是否在打开浏览器前清除浏览器缓存。 | | clearSessionCache | boolean | 是否清除会话缓存（包括 session cookie 和 sessionStorage）。 | | mediaPlaybackRequiresUserAction | boolean | 媒体播放是否需要用户手动触发（如视频、音频自动播放控制）。 | | closeButtonText | string | 工具栏关闭按钮的显示文本（如“关闭”“返回”）。 | | toolbarPosition | ToolbarPosition | 工具栏的显示位置（顶部或底部）。 | | showNavigationButtons | boolean | 是否显示导航按钮（前进、后退）。 | | leftToRight | boolean | 浏览器内容是否采用从左到右的布局（适配不同语言排版）。 | | customWebViewUserAgent | string | 自定义 WebView 的 UserAgent，用于标识浏览器类型。 | | android | AndroidWebViewOptions | Android 平台特定的 WebView 配置（OpenHarmony平台可参考适配）。 | | iOS | iOSWebViewOptions | iOS 平台特定的 WebView 配置（OpenHarmony平台不支持）。 |

AndroidWebViewOptions

Android 平台特定的 WebView 配置，OpenHarmony平台可参考适配部分参数。

| 参数 | 类型 | 描述 | |------------------|---------|-----------------------------------------| | allowZoom | boolean | 是否允许对 WebView 内容进行缩放。 | | hardwareBack | boolean | 是否启用硬件返回键，用于返回上一页或关闭浏览器。 | | pauseMedia | boolean | 离开 WebView 时是否暂停媒体播放。（OpenHarmony平台不支持） |

iOSWebViewOptions

iOS 平台特定的 WebView 配置，OpenHarmony平台暂不支持以下参数。

| 参数 | 类型 | 描述 | |-----------------------------------------|-------------------------------|----------------------------------------| | allowOverScroll | boolean | 是否允许 WebView 过度滚动（iOS 特有效果）。 | | enableViewportScale | boolean | 是否启用视口缩放。（OpenHarmony平台不支持） | | allowInLineMediaPlayback | boolean | 是否允许媒体在内联窗口中播放。（OpenHarmony平台不支持） | | surpressIncrementalRendering | boolean | 是否抑制网页增量渲染。（OpenHarmony平台不支持） | | viewStyle | iOSViewStyle | WebView 的视图样式。（OpenHarmony平台不支持） | | animationEffect | iOSAnimation | WebView 打开/关闭时的动画效果。（OpenHarmony平台不支持） | | allowsBackForwardNavigationGestures | boolean | 是否允许通过手势实现前进/后退导航。（OpenHarmony平台不支持） |

Enums（枚举）

ToolbarPosition

定义工具栏的显示位置，仅支持以下两个枚举值：

| 成员 | 描述 | |------------|----------------| | TOP | 工具栏显示在浏览器窗口顶部。 | | BOTTOM | 工具栏显示在浏览器窗口底部。 |

iOSViewStyle

iOS 平台 WebView 的视图样式，OpenHarmony平台不支持，枚举值如下：

| 成员 | 描述 | |-----------------|-----------------| | PAGE_SHEET | 页面表单样式（iOS 特有）。 | | FORM_SHEET | 表单样式（iOS 特有）。 | | FULL_SCREEN | 全屏样式（iOS 特有）。 |

iOSAnimation

iOS 平台 WebView 打开/关闭的动画效果，OpenHarmony平台不支持，枚举值如下：

| 成员 | 描述 | |---------------------|-----------------| | FLIP_HORIZONTAL | 水平翻转动画（iOS 特有）。 | | CROSS_DISSOLVE | 交叉溶解动画（iOS 特有）。 | | COVER_VERTICAL | 垂直覆盖动画（iOS 特有）。 |

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码（InAppBrowser核心逻辑）
|           |----ets   # ArkTS 代码（应用层调用逻辑）
|     |---- README.md          # 插件说明文档
|     |---- package.json       # 插件配置文件
|     |---- plugin.xml         # 插件集成配置文件

贡献代码

使用过程中发现任何问题，可提交 Issue 反馈；也非常欢迎提交 PR 共同完善插件。

许可证

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