視窗

Window 是 DOM 最上層 window 物件的包裝器。它已擴充運算，且可以接收各種視窗事件。

每個 Window 都是 EventEmitter 類別的執行個體，而且您可以使用 Window.on(...) 來回應原生視窗的事件。

概要

// Get the current window
var win = nw.Window.get();

// Listen to the minimize event
win.on('minimize', function() {
  console.log('Window is minimized');
});

// Minimize the window
win.minimize();

// Unlisten the minimize event
win.removeAllListeners('minimize');

// Create a new window and get it
nw.Window.open('https://github.com', {}, function(new_win) {
  // And listen to new window's focus event
  new_win.on('focus', function() {
    console.log('New window is focused');
  });

});

Window.get([window_object])

• window_object {DOM 視窗} 選用 是 DOM 視窗
• 傳回 {視窗} 原生 視窗 物件

如果未指定 window_object，則傳回目前視窗的 Window 物件，否則傳回 window_object 的 Window 物件。

// Get the current window
var win = nw.Window.get();

// Get iframe's window
var iframeWin = nw.Window.get(iframe.contentWindow);

//This will return true
console.log(iframeWin === win);

// Create a new window and get it
nw.Window.open('https://github.com/nwjs/nw.js', {}, function(new_win) {
  // do something with the newly created window
});

Window.getAll(callback)

取得所有視窗，並提供一個回呼函式，其參數為 nw.Window 物件陣列。此函式自 0.42.6 起支援。

Window.open(url, [options], [callback])

• url {字串} 要在開啟的視窗中載入的 URL
• options {物件} 選用 請參閱明細格式中的 視窗子欄位。下列額外欄位也可以用於選項中。
  • new_instance {布林值} 選用 是否在個別的呈現程序中開啟新視窗。
  • mixed_context {布林值} 選用 如果為 true，節點內容和 DOM 內容會在新視窗的程序中合併。僅在 new_instance 為 true 時使用。
  • inject_js_start {字串} 選用 在建構任何 DOM 和執行任何腳本之前要注入的腳本。請參閱 明細格式
  • inject_js_end {字串} 選用 在載入文件物件後、觸發 onload 事件之前要注入的腳本。請參閱 明細格式
  • id {字串} 選用 用於識別視窗的 id。這將用於記住視窗的大小和位置，並在稍後開啟具有相同 id 的視窗時還原該幾何。請另參閱 Chrome App 文件
• callback(win) {函式} 選用 使用開啟的原生 Window 物件時的回呼。

開啟新視窗並載入其中的 url。

win.window

取得原生視窗對應的 DOM 視窗物件。

win.x

win.y

取得或設定從視窗框架到螢幕的左/上偏移量。

win.width

win.height

取得或設定視窗的大小，包括視窗的框架。

win.title

取得或設定視窗的標題。

win.menu

取得或設定視窗的選單列。使用類型為 menubar 的 Menu 設定。當 win.menu 設定為 null 時，選單列會在 Windows 和 Linux 中完全移除，而 Mac 上的選單列則會清除。

請參閱 自訂選單列 以了解選單列的使用方式。並參閱 Menu 和 MenuItem 以取得詳細的 API。

win.isAlwaysOnTop

取得視窗是否始終置於其他視窗之上。

win.isFullscreen

取得我們是否在全螢幕模式中。

win.isTransparent

取得是否已開啟透明度

win.isKioskMode

取得我們是否在資訊亭模式中。

win.zoomLevel

取得或設定頁面縮放。0 為正常大小；正值為放大；負值為縮小。

win.cookies.*

這包含多個用於操作 Cookie 的函數。API 的定義方式與 Chrome 擴充功能 相同。NW.js 支援 get、getAll、remove 和 set 方法；onChanged 事件（支援在此事件上使用 addListener 和 removeListener 函數）。

而且，由於 NW.js 應用程式中只有一個全域 Cookie 儲存區，因此不支援 Chrome 擴充功能 API 中與 CookieStore 相關的任何內容。

win.moveTo(x, y)

• x {Integer} 螢幕左方的偏移量
• y {Integer} 螢幕上方的偏移量

將視窗的左邊緣和上邊緣移至指定的座標。

win.moveBy(x, y)

• x {Integer} 水平偏移量
• y {Integer} 垂直偏移量

將視窗相對於其目前座標移動指定的像素數。

win.resizeTo(width, height)

• width {Integer} 視窗的內部寬度
• height {Integer} 視窗的內部高度

將視窗調整為指定的 width 和 height。

win.setInnerWidth(width)

• width {Integer} 視窗的內部寬度

win.setInnerHeight(height)

• height {Integer} 視窗的內部高度

win.resizeBy(width, height)

• width {Integer} 視窗的偏移寬度
• height {Integer} 視窗的偏移高度

將視窗調整為指定的量。

win.focus()

聚焦視窗。

win.blur()

移開焦點。通常會將焦點移至應用程式的其他視窗，因為在某些平台上沒有模糊的概念。

win.show([is_show])

• is_show {Boolean} 選用 指定視窗應顯示或隱藏。預設設定為 true。

如果視窗未顯示，則顯示視窗。

show(false) 的效果與 hide() 相同。

win.hide()

隱藏視窗。一旦隱藏視窗，使用者將無法找到視窗。

win.close([force])

• force {Boolean} 指定是否強制關閉視窗並略過 close 事件。

關閉目前的視窗。您可以透過聆聽 close 事件來防止關閉。如果指定 force 且等於 true，則會忽略 close 事件。

通常您會聆聽 close 事件並執行一些關閉工作，然後執行 close(true) 以真正關閉視窗。

win.on('close', function () {
  this.hide(); // Pretend to be closed already
  console.log("We're closing...");
  this.close(true); // then close it forcefully
});

win.close(); // Would be detected by the above close event. To skip the above close event use win.close(true);

win.reload()

重新載入目前的視窗。

win.reloadDev()

從頭開始新的渲染器程序來重新載入目前的頁面。

win.reloadIgnoringCache()

類似於 reload()，但不要使用快取（又稱「shift-reload」）。

win.maximize()

在 GTK 和 Windows 上最大化視窗，並在 Mac OS X 上縮放視窗。

win.unmaximize()

取消最大化視窗，也就是 maximize() 的反向操作。

win.minimize()

將視窗最小化至 Windows 的工作列、將 GTK 的視窗圖示化，以及將 Mac OS X 的視窗最小化。

win.restore()

在視窗最小化後，將視窗還原至先前的狀態，也就是 minimize() 的反向操作。由於一般都使用 restore，因此未將其命名為 unminimize。

win.enterFullscreen()

讓視窗全螢幕顯示。

win.leaveFullscreen()

離開全螢幕模式。

win.toggleFullscreen()

切換全螢幕模式。

win.enterKioskMode()

進入 Kiosk 模式。在 Kiosk 模式中，應用程式會全螢幕顯示，並試著防止使用者離開應用程式，因此您應該記得在應用程式中提供離開 Kiosk 模式的方法。此模式主要用於在公開顯示器上進行簡報。

win.leaveKioskMode()

離開 Kiosk 模式。

win.toggleKioskMode()

切換 Kiosk 模式。

win.setTransparent(transparent)

• transparent {Boolean} 是否將視窗設定為透明

開啟/關閉透明度支援。請參閱 透明視窗 中的更多資訊。

win.setShadow(shadow) (Mac)

• shadow {Boolean} 視窗是否具有陰影

開啟/關閉視窗的原生陰影。對於無邊框、透明視窗很有用。

win.showDevTools([iframe], [callback])

• iframe {String} 或 {HTMLIFrameElement} 選用 要監控的 <iframe> 的 id 或元素。預設情況下，DevTools 會顯示整個視窗。
• callback(dev_win) {Function} 回呼，其中包含 DevTools 視窗的原生視窗。

開啟 devtools 來檢查視窗。

選用的 iframe 作為 String 應為視窗中任何 <iframe> 元素的 id 屬性的值。它會監控 DevTools 以僅檢查 <iframe>。如果它是一個空字串，這個功能不會有任何效果。

選用的 iframe 作為 HTMLIFrameElement 應為 iframe 物件。它與 id 參數有相同的作用。

這個函式會透過回呼傳回一個 Window 物件。你可以使用 Window 的任何屬性和方法，但事件除外。

另請參閱 webview 參考，了解如何為 webview 開啟 DevTools 或在 webview 中開啟 DevTools。

win.closeDevTools()

關閉 devtools 視窗。

win.getPrinters(callback)

列舉系統中的印表機。回呼函式會收到一個 JSON 物件陣列，其中包含印表機資訊。JSON 物件的裝置名稱可以用作 nw.Window.print() 中的參數。

win.isDevToolsOpen()

查詢 devtools 視窗的狀態。

另請參閱 win.showDevTools()。

win.print(options)

列印視窗中的網路內容，不論是否需要使用者的互動。options 是包含下列欄位的 JSON 物件

• autoprint {Boolean} 是否在不需要使用者互動的情況下列印；選用，預設為 true
• silent {Boolean} 隱藏閃爍的列印預覽對話框；選用，預設為 false
• printer {字串} nw.Window.getPrinters() 傳回的印表機裝置名稱；列印至 PDF 時無需設定
• pdf_path {字串} 列印至 PDF 時的輸出 PDF 檔案路徑
• headerFooterEnabled {布林值} 是否啟用頁首和頁尾
• landscape {布林值} 是否使用橫向或直向
• mediaSize {JSON 物件} 紙張大小規格
• shouldPrintBackgrounds {布林值} 是否列印 CSS 背景
• marginsType {整數} 0 - 預設值；1 - 無邊界；2 - 最小；3 - 自訂，請參閱 marginsCustom。
• marginsCustom {JSON 物件} 自訂邊界設定；單位為點數。
• copies {整數} 要列印的份數。
• scaleFactor {整數} 比例因子；100 為預設值。
• headerString {字串} 取代頁首中 URL 的字串。
• footerString {字串} 取代頁尾中 URL 的字串。

marginsCustom 範例："marginsCustom":{"marginBottom":54,"marginLeft":70,"marginRight":28,"marginTop":32}
mediaSize 範例：'mediaSize':{'name': 'CUSTOM', 'width_microns': 279400, 'height_microns': 215900, 'custom_display_name':'Letter', 'is_default': true}

注意：如果未傳遞任何選項，則應呼叫 win.print({})。

win.setMaximumSize(width, height)

• width {整數} 視窗的最大寬度
• height {整數} 視窗的最大高度

設定視窗的最大尺寸。

win.setMinimumSize(width, height)

• width {整數} 視窗的最小寬度
• height {整數} 視窗的最小高度

設定視窗的最小尺寸。

win.setResizable(resizable)

• resizable {布林值} 視窗是否可調整大小

設定視窗是否可調整大小。

win.setAlwaysOnTop(top)

• top {布林值} 視窗是否應始終置頂

設定小工具置於視窗系統中所有其他視窗之上。

win.setVisibleOnAllWorkspaces(visible) (Mac 和 Linux)

• visible {布林值} 視窗是否應在所有工作空間中可見

對於支援多個工作區的平台（目前為 Mac OS X 和 Linux），這允許 NW.js 視窗同時在所有工作區中顯示。

win.canSetVisibleOnAllWorkspaces() (Mac 和 Linux)

傳回一個布林值，指出平台（目前為 Mac OS X 和 Linux）是否支援視窗 API 方法 setVisibleOnAllWorkspace(Boolean)。

win.setPosition(position)

• position {字串} 視窗的位置。有三個有效位置：null 或 center 或 mouse

將視窗移至指定位置。目前僅在所有平台上支援 center，這會將視窗置於螢幕中央。

win.setShowInTaskbar(show)

• show {布林值} 是否顯示在工作列中

控制是否在工作列或 Dock 中顯示視窗。另請參閱 Manifest 格式 中的 show_in_taskbar。

win.requestAttention(attension)

• attension {布林值} 或 {整數} 如果是布林值，則表示要求或取消使用者的注意力。如果是一個整數，則表示視窗閃爍的次數。

透過在工作列中讓視窗閃爍來要求使用者的注意力。

win.capturePage(callback [, config ])

• callback {函式} 完成擷取視窗時的回呼函式
• config {字串} 或 {物件} 選用 如果是字串，請參閱 config.format 以取得有效值。
  • format {字串} 選用 用於產生影像的影像格式。它支援兩種格式："png" 和 "jpeg"。如果忽略，預設為 "jpeg"。
  • datatype {字串} 它支援三種類型："raw"、"buffer" 和 "datauri"。如果忽略，預設為 "datauri"。

擷取視窗的顯示區域。若要擷取整頁，請參閱 win.captureScreenshot。

範例用法

// png as base64string
win.capturePage(function(base64string){
 // do something with the base64string
}, { format : 'png', datatype : 'raw'} );

// png as node buffer
win.capturePage(function(buffer){
 // do something with the buffer
}, { format : 'png', datatype : 'buffer'} );

win.captureScreenshot(options [, callback])

當省略 callback 時，會傳回 Promise，而且會以 callback 的 data 參數解析。

• callback {Function} 選用 完成擷取視窗時的 callback。會呼叫它，並傳入
  • err null 表示成功；{String} 表示失敗的錯誤訊息。
  • data {String} base64 編碼的影像
• options {Object}
  • fullSize {Boolean} 選用 擷取整個頁面，超出可見區域。目前 Chromium 將擷取影像的高度上限設為 16384 像素。
  • format {String} 選用 用於產生影像的影像格式。它支援兩種格式："png" 和 "jpeg"。"png" 是預設值。
  • quality {Integer} 選用 範圍 [0..100] 內的壓縮品質（僅限 jpeg）。
  • clip {Object} 選用 僅擷取指定區域的螢幕截圖。物件的屬性為
  • x: {Number} 以與裝置無關的像素 (dip) 為單位的 X 位移。
  • y: {Number} 以與裝置無關的像素 (dip) 為單位的 Y 位移。
  • width: {Number} 以與裝置無關的像素 (dip) 為單位的矩形寬度。
  • height: {Number} 以與裝置無關的像素 (dip) 為單位的矩形高度。
  • scale: {Number} 頁面縮放因子。

擷取視窗。它可用於擷取超出可見區域的整個頁面。

範例用法

          win.captureScreenshot({fullSize: true}, (err, data) => {
            if (err) {
              alert(err.message);
              return;
            }
            var image = new Image();
            image.src = 'data:image/jpg;base64,' + data;
            document.body.appendChild(image);
          });

win.setProgressBar(progress)

• progress {Float} [0, 1] 內的有效值。設定為負值 (<0) 會移除進度條。

win.setBadgeLabel(label)

在工作列或 Dock 中設定視窗圖示上的徽章標籤。

win.eval(frame, script)

• frame {HTMLIFrameElement} 要執行的框架。如果 iframe 為 null，它會假設在目前的視窗/框架中。
• script {String} 要執行的指令碼的原始碼

在框架中執行 JavaScript 片段。

win.evalNWBin(frame, path)

• frame {HTMLIFrameElement} 要執行的框架。如果 iframe 為 null，它會假設在目前的視窗/框架中。
• path {String|ArrayBuffer|Buffer} 由 nwjc 產生的二進位檔案的路徑或 Buffer 或 ArrayBuffer

載入並執行框架中的已編譯二進位檔案。請參閱 保護 JavaScript 原始碼。

win.evalNWBinModule(frame, path, module_path)

• frame {HTMLIFrameElement} 要執行的框架。如果 iframe 為 null，它會假設在目前的視窗/框架中。
• path {String|ArrayBuffer|Buffer} 由 nwjc 產生的二進位檔案的路徑或 Buffer 或 ArrayBuffer
• module_path {String} 與目前文件相關的模組 URL。它會用於 解析模組指定項。

載入並執行框架中模組的已編譯二進位檔案。二進位檔案應使用 nwjc --nw-module 編譯。以下程式碼會將 lib.bin 載入為模組，其他模組可以使用類似 import * from './lib.js' 的方式參照它

nw.Window.get().evalNWBinModule(null, 'lib.bin', 'lib.js');

win.removeAllListeners([eventName])

移除所有監聽器，或移除指定 eventName 的監聽器。

事件：close

close 事件是一個特殊事件，它會影響 Window.close() 函式的結果。如果開發人員監聽視窗的 close 事件，Window.close() 會發出 close 事件，但不會關閉視窗。

通常您會在 close 事件的回呼中執行一些關閉工作，然後呼叫 this.close(true) 來真正關閉視窗，這將不會再次被捕獲。忘記在回呼中呼叫 this.close() 時加入 true 會導致無限迴圈。

如果關閉工作需要一些時間，使用者可能會覺得應用程式退出得很慢，這是一個不好的體驗，因此您可以在 close 事件中隱藏視窗，然後再真正關閉視窗，以提供流暢的使用者體驗。

請參閱 上面 win.close(true) 的範例程式碼，以了解 close 事件的用法。

事件：closed

在對應的視窗關閉後，會發出 closed 事件。通常您無法取得此事件，因為在視窗關閉後，所有 js 物件都會被釋放。但當在另一個視窗中監聽視窗的事件時，這很有用，因為該視窗的物件不會被釋放。

// Open a new window.
nw.Window.open('popup.html', {}, function (win) {
  // Release the 'win' object here after the new window is closed.
  win.on('closed', function () {
    win = null;
  });

  // Listen to main window's close event
  nw.Window.get().on('close', function () {
    // Hide the window to give user the feeling of closing immediately
    this.hide();

    // If the new window is still open then close it.
    if (win !== null) {
      win.close(true);
    }

    // After closing the new window, close the main window.
    this.close(true);
  });
});

事件：loading

當視窗開始重新載入時發出，通常您無法捕獲此事件，因為它通常在您實際設定回呼之前發出。

唯一可以捕獲此事件的情況是，當您重新整理視窗並在另一個視窗中監聽此事件時。

事件：loaded

當視窗完全載入時發出，此事件與 window.onload 的行為相同，但不會依賴 DOM。

事件：document-start(frame)

• frame {HTMLIFrameElement} 是 iframe 物件，或 null 如果事件是針對視窗。

當此視窗或子 iframe 中的文件物件可用時發出，在所有檔案載入後，但在 DOM 建立或執行任何指令碼之前。
它不會在使用 nw.Window.open() 建立的新視窗中觸發：該函式的回呼會在這個事件的同一時間點觸發。

請參閱 Manifest 格式 中的 inject_js_start。

事件：document-end(frame)

• frame {HTMLIFrameElement} 是 iframe 物件，或 null 如果事件是針對視窗。

當此視窗或子 iframe 中的文件物件卸載時發出，但在 onunload 事件發出之前。

請參閱 Manifest 格式 中的 inject_js_end。

事件：focus

當視窗獲得焦點時發出。

事件：blur

當視窗失去焦點時發出。

事件：minimize

當視窗最小化時發出。

事件：restore

當視窗從最小化、最大化和全螢幕狀態還原時發出。

事件：maximize

當視窗最大化時發出。

事件：move(x, y)

在視窗移動後發出。回呼會使用 2 個參數呼叫：(x, y) 表示視窗左上角的新位置。

事件：resize(width, height)

在視窗調整大小後發出。回呼會使用 2 個參數呼叫：(width, height) 表示視窗的新大小。

事件：enter-fullscreen

當視窗進入全螢幕狀態時發出。

事件：leave-fullscreen

當視窗離開全螢幕狀態時發出。

事件：zoom

當視窗縮放變更時發出。它有一個參數表示新的縮放層級。請參閱 win.zoom() 方法 以取得參數值的定義。

事件：capturepagedone

在呼叫 capturePage 方法且影像資料準備就緒後發出。請參閱 win.capturePage() 回呼函數，以取得參數值定義。

事件：devtools-opened(url)

請參閱 win.showDevTools() 方法，以取得更多詳細資料。

事件：devtools-closed

在 Devtools 關閉後發出。

請參閱 win.closeDevTools() 方法，以取得更多詳細資料。

事件：new-win-policy (frame, url, policy)

• frame {HTMLIFrameElement} 是來自要求的子 iframe 物件，如果來自頂層視窗，則為 null。
• url {String} 是所要求連結的位址
• policy {Object} 是具有下列方法的物件
  • ignore() : 忽略要求，導覽不會發生。
  • forceCurrent() : 強制連結在同一框架中開啟
  • forceDownload() : 強制連結成為可下載，或由外部程式開啟
  • forceNewWindow() : 強制連結在新視窗中開啟
  • forceNewPopup() : 強制連結在新快顯視窗中開啟
  • setNewWindowManifest(m) : 控制新快顯視窗的選項。物件 m 的格式與明細格式中的 視窗子欄位 相同。

當從此視窗或子 iframe 要求新視窗時發出。您可以在回呼中呼叫 policy.* 方法，以變更開啟新視窗的預設行為。

例如，當使用者嘗試在新視窗中開啟時，您可以在系統瀏覽器中開啟 URL

nw.Window.get().on('new-win-policy', function(frame, url, policy) {
  // do not open the window
  policy.ignore();
  // and open it in external browser
  nw.Shell.openExternal(url);
});

事件：navigation (frame, url, policy)

• frame {HTMLIFrameElement} 是來自要求的子 iframe 物件，如果來自頂層視窗，則為 null。
• url {String} 是所要求連結的位址
• policy {Object} 是具有下列方法的物件
  • ignore() : 忽略要求，導覽不會發生。

在導覽至其他頁面時發出。類似於 new-win-policy，您可以在回呼中呼叫 policy.ignore()，以忽略導覽。