Skip to content

Latest commit

 

History

History
197 lines (148 loc) · 5.65 KB

README-EN.md

File metadata and controls

197 lines (148 loc) · 5.65 KB

中文版 | English Version

CloakPluginInAppBrowser

CloakPluginInAppBrowser is a plugin for the Cloak framework, designed to open and manage internal browser window within Cloak applications.

Usage

Prerequisites

Install the Cloak framework @wisdomgarden/cloak

For more details, refer to @wisdomgarden/cloak

  1. Install the CloakPluginInAppBrowser plugin

    ohpm install @wisdomgarden/cloak-plugin-inappbrowser
npm install @wisdomgarden/cloak-plugin-inappbrowser # optional

  2. Declare internet access permissions in your project's entry/src/main/module.json5.

    Official Documentation

    Example:

    "requestPermissions": [
 // ...
 {
   "name": "ohos.permission.INTERNET",
   "reason": "$string:permission_internet_reason",
   "usedScene": {
     "abilities": [
       "EntryAbility"
     ],
     "when": "inuse"
   }
 },
 // ...
]

  3. You can now directly call the plugin in your H5 logic code.

  4. If you are using TypeScript or want to extend the plugin on the frontend, install the NPM package

    npm install @wisdomgarden/cloak-plugin-inappbrowser

    Currently, the npm package extends the create method, mimicking the Cordova style, and also provides RxJS-style event subscriptions. For more details, see index.d.ts

Example Code

Open URL and Listen for Events

const onOpenUrl = async (url) => {
  const browser = Cloak.plugins.InAppBrowser.create(url, "_blank", { clearcache: true, footer: false });

  // Listen for loadstart event
  browser.addEventListener('loadstart', function (event) {
    alert("addEventListener loadstart: " + event.url);
  });

  // Use RxJS-style subscription to listen for loadstart event
  browser.on("loadstart").subscribe(({ url }) => {
    alert("on loadstart: " + url);
  });

  // Listen for loadstop event and execute script and insert CSS
  browser.on("loadstop").subscribe(({ url }) => {
    browser.executeScript({
      code: "document.querySelector('.core-card .card-title').innerText = 'Start your OpenHarmony journey with Wisdom Garden!';document.querySelector('.core-card .card-title').style.fontSize = '2rem';document.querySelector('.core-card .card-title').style.color = 'red';"
    });
    browser.insertCSS({ code: ".card-summary {color: purple !important;}" });
    alert("on loadstop: " + url);
  });

  // Listen for exit event
  browser.on("exit").subscribe(() => {
    alert("closed");
  });
};

Core Interfaces

Create Browser Instance

interface InAppBrowserPlugin extends Plugin {
  currentBrowser: InAppBrowserObject | null;
  create(url: string, target: IOpenTarget, options: ICreateBrowserOptions): InAppBrowserObject;
  createBrowser(url: string, target: string, options: ICreateBrowserOptions): InAppBrowserObject;
}

Browser Object Interface

interface InAppBrowserObject {
  open: () => boolean;
  close: () => boolean;
  show: () => boolean;
  hide: () => boolean;
  executeScript: (payload: IBrowserExecutePayload) => Promise<ESObject>;
  insertCSS: (payload: IBrowserExecutePayload) => Promise<ESObject>;
  addEventListener: (event: IBrowserEvent, handler?: (event: IBrowserEventPayload) => void) => void;
}

RxJS-style Event Subscription

interface InAppBrowserInstanceRxjs extends InAppBrowserObject {
  on: (event: IBrowserEvent) => {
    subscribe: (handler: (event: IBrowserEventPayload) => void) => void;
  };
}

Interface Type Definitions

Browser Script Execution Payload

export interface IBrowserExecutePayload {
  code: string;
}

Browser Event Types

export type IBrowserEvent = "loadstart" | "loadstop" | "loaderror" | "exit";

Target Options for Opening

export type IOpenTarget = "_self" | "_blank" | "_system" | null;

Browser Creation Options

export interface ICreateBrowserOptions {
  clearCache?: boolean | null;
  clearcache?: boolean | null;
  clearSessionCache?: boolean | null;
  clearsessioncache?: boolean | null;
  session?: string | null;
  closeButtonCaption?: string | null;
  closebuttoncaption?: string | null;
  footer?: boolean | null;
  footerColor?: string | null;
  footercolor?: string | null;
  hideNavigationButtons?: boolean | null;
  hidenavigationbuttons?: boolean | null;
}

Browser Event Payload

export interface IBrowserEventPayload {
  event: IBrowserEvent;
  url: string;
}

About Cloak

Cloak is a lightweight hybrid development framework for HarmonyOS, inspired by Cordova and Capacitor, but with simpler implementation and better performance.

Enables rapid conversion of web applications to native HarmonyOS apps with plugin-based native API access.

Core Features

  • Quick Packaging Compile H5/web apps into HarmonyOS applications within minutes

  • Native API Access Extend functionality through HarmonyOS native plugins

  • Optimized WebView High-performance WebView container with hardware acceleration

  • Plugin Development Easily create HarmonyOS native plugins using TypeScript/ArkTS

For more information about the Cloak framework, please visit: https://github.com/WisdomGardenInc/Cloak