@modos189/nativescript-webview-x

A NativeScript WebView plugin wrapping the Android system WebView and iOS WKWebView. Built on top of @nativescript-community/ui-webview — WebViewX extends AWebView directly, so the full upstream API is available.

Both @modos189/nativescript-webview-x and @modos189/nativescript-webview-x-gecko export an identically named WebViewX class. Swap the engine by changing only the import path.

Installation

npm install @modos189/nativescript-webview-x

Usage

XML

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
      xmlns:wv="@modos189/nativescript-webview-x">
  <GridLayout rows="auto, *">
    <TextField row="0" hint="Enter URL" text="{{ url }}" returnPress="{{ onNavigate }}" />
    <wv:WebViewX row="1" src="{{ src }}" />
  </GridLayout>
</Page>

TypeScript

import { WebViewX } from '@modos189/nativescript-webview-x';

const webview = new WebViewX();
webview.loadUrl('https://example.com');
webview.on('loadFinished', () => {
  webview.executeJavaScript('document.title');
});

Implemented

Available in both @modos189/nativescript-webview-x and @modos189/nativescript-webview-x-gecko.

Static properties

None.

Properties

| Property | Type | Description | | --- | --- | --- | | src | string | URL to load (data-binding supported) | | userAgent | string | Set a custom User-Agent string | | debugMode | boolean | Enable remote WebView debugging | | supportPopups | boolean | Open window.open() / target="_blank" links in a native popup. Default: true | | autoInjectJSBridge | boolean | Inject window.nsWebViewBridge on every loadFinished. Default: true |

Methods

| Method | Returns | Description | | --- | --- | --- | | getTitle() | Promise<string | undefined> | Return the current page title | | executeJavaScript(code: string) | Promise<any> | Execute JavaScript in the page context and return the JSON-serialised result | | emitToWebView(eventName: string, data: any) | void | Emit an event into the page's nsWebViewBridge (calls onNativeEvent inside the WebView) |

Events

| Event | Description | | --- | --- | | loadStarted | Navigation started. args.url contains the target URL | | loadFinished | Navigation finished. args.error is set on failure | | loadProgress | Android: page load progress. args.progress is 0–100 | | titleChanged | Page title changed. args.title contains the new title | | popupNavigate | Android: fired on each navigation inside a popup; set args.cancel = true to intercept and dismiss the popup (e.g. capture OAuth redirect). args.url contains the target URL. |

API Reference

Full API inherited from @nativescript-community/ui-webview. All items are available — WebViewX extends AWebView directly.

Properties

| Property | Type | Description | | --- | --- | --- | | src | string | URL to load | | autoInjectJSBridge | boolean | Inject window.nsWebViewBridge on load finished. Default: true | | domStorage | boolean | Android: enable DOM Storage API (e.g. localStorage) | | databaseStorage | boolean | Android: enable database storage API | | builtInZoomControls | boolean | Android: use built-in zoom mechanisms | | displayZoomControls | boolean | Android: show on-screen zoom controls | | supportZoom | boolean | Android: enable zoom support | | cacheMode | string | Android: default, no_cache, cache_first, or cache_only | | debugMode | boolean | Enable Chrome (Android) / Safari (iOS) remote debugger | | scrollBounce | boolean | iOS: scrollView bounce. Default: true | | viewPortSize | boolean \| string \| ViewPortProperties | Set viewport metadata after load | | limitsNavigationsToAppBoundDomains | boolean | iOS: enable Service Workers | | supportPopups | boolean | iOS: support window.open / target="_blank". Default: true | | scrollBarIndicatorVisible | boolean | Show/hide scrollbars |

Methods

| Method | Returns | Description | | --- | --- | --- | | loadUrl(src: string) | Promise<LoadFinishedEventData> | Load a URL, resolves when finished | | executeJavaScript(code: string) | Promise<any> | Execute JavaScript and return the result | | executePromise(code: string, timeout?: number) | Promise<any> | Run a promise inside the webview | | getTitle() | Promise<string> | Return document.title | | emitToWebView(eventName: string, data: any) | void | Emit an event into the webview | | autoLoadJavaScriptFile(name: string, path: string) | void | Auto-inject a JS file on every loadFinished | | autoLoadStyleSheetFile(name: string, path: string, insertBefore?: boolean) | void | Auto-inject a CSS file on every loadFinished | | autoExecuteJavaScript(code: string, name: string) | void | Auto-execute a script on every loadFinished |

Events

| Event | Description | | --- | --- | | loadStarted | Navigation started | | loadFinished | Navigation finished. args.error is set on failure | | loadProgress | Android: page load progress (args.progress: number) | | shouldOverrideUrlLoading | Raised before each navigation; set args.cancel = true to block | | titleChanged | document.title changed | | webAlert | window.alert() triggered; call args.callback() to dismiss | | webConfirm | window.confirm() triggered; call args.callback(boolean) to dismiss | | webPrompt | window.prompt() triggered; call args.callback(string \| null) to dismiss | | webConsole | Android: a line was added to the web console |

nsWebViewBridge (inside the WebView)

When autoInjectJSBridge is true, the bridge is available after DOMContentLoaded:

window.nsWebViewBridge.emit('myEvent', { key: 'value' }); // → NativeScript
window.nsWebViewBridge.on('nativeEvent', (data) => { });  // ← NativeScript

License

Apache License Version 2.0