對象WebView

瀏覽器視窗對象

WebView 是一個嵌入瀏覽器的視窗元件，目前僅支援windows, macOS(10.10+). 在windows 使用IE/Edge 核心, 在macOS 使用WKWebView.

由於WebView 內的JavaScript 程式與fibjs 並不在同一個引擎內，所以如果需要與宿主程式進行通訊，則需要透過訊息進行。

WebView 用於通訊的物件是external，external 支援一個方法postMessage 和兩個事件onmessage、onclose。

一個簡單的通訊範例程式碼如下：

1
2
3
4
5
6
7
8
9
// index.js
var gui = require('gui');
var webview = gui.open('fs://index.html');

webview.onmessage = msg => console.log(msg);

webview.onload = evt => webview.postMessage("hello from fibjs");

webview.wait();

index.html 的內容如下：

1
2
3
4
5
6
7
8
<script>
    external.onclose = function() {
    }

    external.onmessage = function(msg){
        external.postMessage("send back: " + msg);
    };
</script>

在使用者視窗關閉之前，會觸發external.onclose 事件，external.onclose 可以決定是否關閉。如果external.onclose 傳回false，則此操作取消，否則將關閉視窗。

以下的例子，會在用戶點關閉後等待5 秒後再關閉視窗。

1
2
3
4
5
6
7
8
9
10
11
12
<script lang="JavaScript">
    var bClose = false;
    external.onclose = function () {
        if (!bClose) {
            setTimeout(function () {
                bClose = true;
                window.close();
            }, 5000);
            return false;
        }
    }
</script>

上面的程式碼中，因為window.close 本身也會觸發onclose 事件，所以需要增加一個開關變量，用於識別是否需要處理此事件。

繼承關係

靜態屬性

defaultMaxListeners

Integer, 預設全域最大監聽器數

1
static Integer WebView.defaultMaxListeners;

成員屬性

onopen

Function, 查詢和綁定載入成功事件，相當於on("open", func);

1
Function WebView.onopen;

onload

Function, 查詢和綁定載入成功事件，相當於on("load", func);

1
Function WebView.onload;

onaddress

Function, 查詢與綁定頁面位址變更事件，相當於on("address", func);

1
Function WebView.onaddress;

ontitle

Function, 查詢和綁定頁面標題改變事件，相當於on("title", func);

1
Function WebView.ontitle;

onmove

Function, 查詢與綁定視窗移動事件，相當於on("move", func);

1
Function WebView.onmove;

以下範例會在視窗移動時輸出視窗的左上角座標：

1
2
3
4
var gui = require('gui');
var webview = gui.open('fs://index.html');

webview.onmove = evt => console.log(evt.left, evt.top);

onresize

Function, 查詢和綁定視窗尺寸改變事件，相當於on("size", func);

1
Function WebView.onresize;

以下範例會在視窗改變大小時輸出視窗的尺寸：

1
2
3
4
var gui = require('gui');
var webview = gui.open('fs://index.html');

webview.onresize = evt => console.log(evt.width, evt.height);

onclosed

Function, 查詢與綁定視窗關閉事件，WebView 關閉後會觸發此時間，相當於on("closed", func);

1
Function WebView.onclosed;

onmessage

Function, 查詢與綁定接受webview 內postMessage 訊息事件，相當於on("message", func);

1
Function WebView.onmessage;

ondownload

Function, 查詢與綁定接受webview 內下載交易狀態變更事件，相當於on("download", func);

1
Function WebView.ondownload;

成員函數

loadUrl

載入指定url的頁面

1
WebView.loadUrl(String url) async;

呼叫參數:

url: String, 指定的url

getUrl

查詢目前頁面的url

1
String WebView.getUrl() async;

回傳結果:

String, 返回目前頁面的url

setHtml

設定webview 的頁面html

1
WebView.setHtml(String html) async;

呼叫參數:

html: String, 設定的html

reload

重新整理當前頁面

1
WebView.reload() async;

goBack

退回上一個頁面

1
WebView.goBack() async;

goForward

前進到下一個頁面

1
WebView.goForward() async;

print

列印目前視窗文檔

1
WebView.print(Integer mode = 1) async;

呼叫參數:

mode: Integer, 列印參數，0: 快速列印; 1: 標準列印; 2: 列印預覽。缺省為 1

executeJavaScript

在目前視窗執行一段JavaScript 程式碼

1
WebView.executeJavaScript(String code) async;

呼叫參數:

code: String, 指定要執行的JavaScript 程式碼

close

關閉目前視窗

1
WebView.close() async;

postMessage

向webview 內發送訊息

1
WebView.postMessage(String msg) async;

呼叫參數:

msg: String, 要傳送的訊息

postMessage 需要在視窗載入完成後傳送訊息，在此之前發送的訊息會遺失。因此建議在onload 事件觸發後再呼叫此方法。

on

綁定一個事件處理函數到對象

1
2
Object WebView.on(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到對象

1
Object WebView.on(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

addListener

綁定一個事件處理函數到對象

1
2
Object WebView.addListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到對象

1
Object WebView.addListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

prependListener

綁定一個事件處理函數到物件起始

1
2
Object WebView.prependListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到物件起始

1
Object WebView.prependListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

once

綁定一個一次性事件處理函數到對象，一次性處理函數只會觸發一次

1
2
Object WebView.once(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個一次性事件處理函數到對象，一次性處理函數只會觸發一次

1
Object WebView.once(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

prependOnceListener

綁定一個事件處理函數到物件起始

1
2
Object WebView.prependOnceListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到物件起始

1
Object WebView.prependOnceListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

off

從物件處理佇列中取消指定函數

1
2
Object WebView.off(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

取消物件處理佇列中的全部函數

1
Object WebView.off(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消指定函數

1
Object WebView.off(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱作為事件名稱，屬性的值作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

removeListener

從物件處理佇列中取消指定函數

1
2
Object WebView.removeListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

取消物件處理佇列中的全部函數

1
Object WebView.removeListener(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消指定函數

1
Object WebView.removeListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱作為事件名稱，屬性的值作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

removeAllListeners

從物件處理佇列中取消所有事件的所有監聽器，如果指定事件，則移除指定事件的所有監聽器。

1
Object WebView.removeAllListeners(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消所有事件的所有監聽器，如果指定事件，則移除指定事件的所有監聽器。

1
Object WebView.removeAllListeners(Array evs = []);

呼叫參數:

evs: Array, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

setMaxListeners

監聽器的預設限制的數量，僅用於相容

1WebView.setMaxListeners(Integer n);

呼叫參數:

n: Integer, 指定事件的數量

getMaxListeners

取得監聽器的預設限制的數量，僅用於相容

1Integer WebView.getMaxListeners();

回傳結果:

Integer, 回傳預設限制數量

listeners

查詢物件指定事件的監聽器陣列

1
Array WebView.listeners(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Array, 傳回指定事件的監聽器數組

listenerCount

查詢物件指定事件的監聽器數量

1
Integer WebView.listenerCount(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Integer, 傳回指定事件的監聽器數量

查詢物件指定事件的監聽器數量

1
2Integer WebView.listenerCount(Value o,
    String ev);

呼叫參數:

o: Value, 指定查詢的對象
ev: String, 指定事件的名稱

回傳結果:

Integer, 傳回指定事件的監聽器數量

eventNames

查詢監聽器事件名稱

1
Array WebView.eventNames();

回傳結果:

Array, 傳回事件名稱數組

emit

主動觸發一個事件

1
2
Boolean WebView.emit(String ev,
    ...args);

呼叫參數:

ev: String, 事件名稱
args: ..., 事件參數，將會傳遞給事件處理函數

回傳結果:

Boolean, 回傳事件觸發狀態，有回應事件回傳true，否則回傳false

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String WebView.toString();

回傳結果:

String, 傳回物件的字串表示

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value WebView.toJSON(String key = "");

呼叫參數:

key: String, 未使用

回傳結果:

Value, 傳回包含可JSON 序列化的值

開發指南

基礎模組

內建對象

社群模組

對象WebView

繼承關係

靜態屬性

defaultMaxListeners

成員屬性

onopen

onload

onaddress

ontitle

onmove

onresize

onclosed

onmessage

ondownload

成員函數

loadUrl

getUrl

setHtml

reload

goBack

goForward

print

executeJavaScript

close

postMessage

on

addListener

prependListener

once

prependOnceListener

off

removeListener

removeAllListeners

setMaxListeners

getMaxListeners

listeners

listenerCount

eventNames

emit

toString

toJSON