窗口

Window 是DOM中 顶层 window对象的包装类 . 可扩展操作以及接收窗口事件 .

每个 Window都是EventEmitter类实例 , 使用 Window.on(...)可响应窗口事件 .

示例

//获取当前窗口
var win = nw.Window.get();
// 监听最小化事件
win.on('minimize', function() {
  console.log('Window is minimized');
});
// 窗口最小化
win.minimize();
// 移除最小化监听事件
win.removeAllListeners('minimize');
// 创建窗口并获取它的窗口对象
nw.Window.open('https://github.com', {}, function(new_win) {
  // 监听新窗口焦点事件
  new_win.on('focus', function() {
    console.log('New window is focused');
  });
});

Window.get([window_object])

用途:获取指定window_object窗口(未指定时默认为当前窗口)的窗口对象

• window_object {DOM Window} (可选) DOM窗口对象
• Returns {Window} the native Window object

如果 window_object 是 iframe, 该方法将返回其顶层窗口的 Window 对象.

// 获取当前窗口的`Window`对象
var win = nw.Window.get();
/获取iframe的窗口
var iframeWin = nw.Window.get(iframe.contentWindow);
//返回true
console.log(iframeWin === win);
// 创建窗口并获取它的窗口对象
nw.Window.open('https://github.com/nwjs/nw.js', {}, function(new_win) {
  // do something with the newly created window
});

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

用途:打开并加载 url至新窗口

• url String - 加载至新开窗口的 url
• options Object - (可选) 属性详情请查看窗口子字段:
  • new_instance Boolean - (可选) 是否在单独的渲染过程中打开新窗口
  • inject_js_start String - (可选) 加载文档之前要执行的脚本,更多细节参阅 Manifest format
  • inject_js_end String - (可选) 加载文档之后要执行的脚本. 更多细节参阅 Manifest format
  • id String - (可选) 含窗口尺寸与位置的状态的窗口ID,打开同ID的窗口时会还原该状态,细节请另见Chrome应用文档
  • focus Boolean - (可选) 是否聚焦打开的窗口.默认为 false.

• callback(win) Function - (可选) 窗口打开后的回调, Window对象将作为回调参数.

  与其任何组件进行交互都应在Window的 loaded事件之后.

win.window

用途:获取窗口中对应DOM的window对象

win.x

win.y

用途:获取或设置窗口在屏幕中距离左侧和顶部的偏移值

win.width

win.height

用途:获取或设置窗口尺寸

win.title

用途:获取或设置窗口标题

win.menu

用途:获取或设置窗口菜单栏

通过 type 为 menubar对象完成, 当 win.menu设为 null即没有菜单

更多细节参阅 自定义菜单栏和菜单.以及菜单项

win.isFullscreen

用途:判断窗口是否为全屏模式

win.isTransparent

用途:判断窗口是否为使用透明

win.isKioskMode

用途:判断窗口是否使用 Kiosk模式

win.zoomLevel

用途:获取或设置页面缩放级别

0表示正常大小 ; 数值为正数表示放大 ; 数值为负数表示缩小 .

win.cookies.*

用途:窗口的Cookie 操作

该内容包括了多个Cookie操作. 具体的Cookie API定义方式类同Chrome Extensions’. NW.js 支持 get, getAll, remove 和 set 方法以及 onChanged 事件,(在这个事件上还支持 addListener和 removeListener).

不过,在Chrome扩展API中的有关CookieStore的任意内容都不被支持,因为NW.js应用只有一个全局Cookie存储.

win.moveTo(x, y)

用途:移动窗口到指定位置,将窗口的左上角移动到指定的坐标

• x Integer - 屏幕左侧偏移值
• y Integer - 屏幕顶部偏移值

win.moveBy(x, y)

用途:移动窗口到相对于当前窗口左上角的横纵偏移,比如窗口上移10px

• x Integer - 横向偏移值
• y Integer - 纵向偏移值

win.resizeTo(width, height)

用途:重设窗口尺寸为 width 和 height

• width Integer - 窗口宽度
• height Integer - 窗口高度

win.resizeBy(width, height)

用途:调整窗口尺寸为相对于当前窗口尺寸的width 和 height,比如窗口加宽10px

• width Integer - 窗口宽度偏移值
• height Integer -窗口高度偏移值

win.focus()

用途:聚焦于窗口

win.blur()

用途:从窗口中移除焦点,通常将焦点移至程序其它窗口,但某些系统平台没有 blur这个概念

win.show([is_show])

用途:是否显示指定窗口

• is_show Boolean - (可选) 默认 true即显示

  win.show(false) 等同 win.hide().

某些平台可能需要使用 focus手动聚焦窗口,因为显示后可能不会自动聚焦新窗口.

win.hide()

用途:隐藏窗口

win.close([force])

用途:是否忽略 close事件或监听的强制关闭窗口

• force Boolean - true强制关闭, fasle则不强制

例子:

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

win.reload()

用途:重新加载当前窗口

win.reloadDev()

用途:在新渲染进程重新加载当前页面

win.reloadIgnoringCache()

用途:忽略缓存的重新加载当前页面

类似 reload()但忽略了缓存(又称 "shift-reload") .

win.maximize()

用途:Linux和Window中最大化窗口 , Mac中放大窗口

win.minimize()

用途:Windows/Mac中最小化窗口 , Linux中图标化窗口

win.restore()

用途:还原窗口,与最小化相反,更多人使用 restore来还原最大化的窗口

win.enterFullscreen()

用途:窗口进入全屏模式,但不同于HTML5的FullScreen API的部分页面全屏,该方法会使整个窗口进入全屏

win.leaveFullscreen()

用途:窗口退出全屏模式

win.toggleFullscreen()

用途:窗口切换全屏模式

win.enterKioskMode()

用途:窗口进入 Kiosk模式(该模式即应用将全屏并阻止用户离开应用,比如常见的公共触摸屏演示)

win.leaveKioskMode()

用途:窗口退出 Kiosk模式

win.toggleKioskMode()

用途:窗口切换 Kiosk模式

win.showDevTools([iframe], [callback]) 该方法仅支持SDK构建方式中使用

用途:打开调试工具

• iframe String 或 HTMLIFrameElement - (可选) 要被检查的<iframe>的id或Element. 调试工具默认以独立窗口显示

• callback(dev_win) Function - 开发调试工具窗的带有 Window对象为参数 dev_win的的回调

  iframe为 String 即 <iframe>标签的 id,开发工具将检查 <iframe>内容,为空则无效.

  iframe为 HTMLIFrameElement 即 iframe 对象.作用同上.

有关如何在webview中或为webview打开调试工具,请参阅webview 标签

win.closeDevTools() 该方法仅支持SDK构建方式中使用

用途:关闭调试工具

win.getPrinters(callback)

用途:枚举系统中可用的打印机信息并在回调里发送json格式的打印机信息数组

JSON对象中的设备名可使用于 nw.Window.print()方法中

win.isDevToolsOpen() 该方法仅支持SDK构建方式中使用

用途:判断开发工具是否已打开,细节详见win.showDevTools()

win.print(options)

用途:静默方式(无需用户参与或交互)打印页面内容,如打印小票

• autoprint Boolean - (可选) 是否以静默方式,默认为 true
• printer String - 由 nw.Window.getPrinters()返回的打印机设备名称; 该项在打印PDF时无需设置.
• pdf_path String - 在打印到PDF时用来存放PDF的路径
• headerFooterEnabled Boolean - 是否启用页眉和页脚
• landscape Boolean - 是否使用横向或纵向
• mediaSize JSON Object - 纸张尺寸规格
• shouldPrintBackgrounds Boolean - 是否打印CSS背景
• marginsType Integer - 0为默认边距; 1为无边距; 2为最小边距; 3为自定义边距, 用法参阅下文 marginsCustom.
• marginsCustom JSON Object - 自定义边距设置,单位为px
• copies Integer - 打印份数
• headerString String - 用于替换页头URL的内容

• footerString String - 用于替换页脚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 Integer - 窗口最大宽度
• height Integer - 窗口最大高度

win.setMinimumSize(width, height)

用途:设置窗口的最小宽高

• width Integer - 窗口最小宽度
• height Integer - 窗口最小高度

win.setResizable(resizable)

用途:是否允许调整窗口大小

• resizable Boolean - true允许, false不允许

win.setAlwaysOnTop(top)

用途:是否允许窗口总是置顶(在其余窗口上面)

• top Boolean - true允许, false不允许

win.setVisibleOnAllWorkspaces(visible) (Mac and Linux)

用途:是否允许窗口在所有工作区中都显示

• visible Boolean - true允许, false不允许

支持多工作区的系统(如Mac & Linux)中,将窗口同时显示在所有工作区中

win.canSetVisibleOnAllWorkspaces() (Mac and Linux)

用途:判断所在系统是否支持所有工作区窗口可见( Boolean)

该方法目前不支持Window,Window请使用 setVisibleOnAllWorkspace(Boolean) 方法

win.setPosition(position)

用途:移动窗口到指定位置

• position String -指定的窗口位置,可选值: null(不固定) , center(屏幕居中) , mouse(鼠标所在位置)

win.setShowInTaskbar(show)

用途:是否允许窗口在任务栏或dock中显示

• show Boolean - true允许, false不允许

该功能也可参考配置文件]($References-Manifest-format的 show_in_taskbar属性

win.requestAttention(attension)

用途:设置在任务栏中的窗口进行闪烁/禁止闪烁/闪烁次数

• attension Boolean或Integer - Boolean表示闪烁或禁止闪烁. Integer表示闪烁次数

Mac中 attension> 0即 NSInformationalRequest, attension<0即 NSCriticalRequest.

win.capturePage(callback [, config ])

用途:窗口可视区域的页面截图

• callback Function -页面截图后的回调
• config String或Object - (可选) 截图设置, 如果String则可选值为 "png" 和 "jpeg",如果Object则为如下:
  • format String - (可选) 生成的图片格式,可选: "png" 和 "jpeg". 默认为 "jpeg"
  • datatype String - 数据类型,可选: "raw"(Base64编码), "buffer"(缓存) 和 "datauri"(可用 <src>标签加载). 默认为 "datauri"

例子:

//png图片的base64编码
win.capturePage(function(base64string){
 // 使用base64编码字符串处理某些需求
}, { format : 'png', datatype : 'raw'} );
// png图片为buffer对象
win.capturePage(function(buffer){
// 使用buffer对象处理某些需求
}, { format : 'png', datatype : 'buffer'} );

win.setProgressBar(progress)

用途:设置任务栏或dock上的进度条

• progress Float - 进度值为[0, 1]之间. 当值为负数即删除该进度条.

注意,Linux中只有Ubuntu支持该项,但需要配置 .desktop文件的 NW_DESKTOP环境变量,未配置则默认使用 nw.desktop

win.setBadgeLabel(label)

用途:设置任务栏或dock上的图标标签

注意,Linux中只有Ubuntu支持该项,但该项仅为数字类型字符串,且需要配置 .desktop文件的 NW_DESKTOP环境变量,未配置则默认使用 nw.desktop

win.eval(frame, script)

用途:在指定 frame中执行评估代码 script

• frame HTMLIFrameElement - 要评估的框架. If iframe 为 null即作用于当前窗口或frame.
• script String - 要评估的js代码

win.evalNWBin(frame, path)

用途:在指定 frame中执行评估指定 path的JavaScript保护文件

• frame HTMLIFrameElement -要评估的框架. If iframe 为 null即作用于当前窗口或frame.
• path String|ArrayBuffer|Buffer - 通过 nwjc生成的 Buffer 或 ArrayBuffer 文件(JavaScript保护文件的路径 )

有关JavaScript保护文件,详见V8编译保护JavaScript代码

win.removeAllListeners([eventName])

用途:移除所有或者指定 eventName的监听

事件: close

触发:窗口关闭后,如A窗口监听着B窗口的关闭事件,B窗口关闭时将触发本事件

如果对窗口发起了 close事件监听,那么需要进行以下的流程:

1. Window.close()会先触发 close事件进行处理相关工作.
2. 触发后请先对窗口进行必要的 .hide()隐藏,使用户觉得窗口立即被关闭了而不影响用户体验.

3. 再调用 this.close(true)进行真正关闭.注意 true是必须的,如果忘记了 true会陷入无限循环

   有关示范例子,请查看这里

Mac中 , 使用 ⌘ + Q 关闭窗口时 , 会传递个指示字符串给 close的回调 , quit即成功关闭, 否则为 undefined .

事件: closed

触发:窗口关闭后,如A窗口监听着B窗口的关闭事件,B窗口关闭时将触发本事件

如果你只在一个窗口处理 closed,并不能得到该事件,因为 closed后,所有js对象均被释放.

但在另一个窗口中监听此窗口的 closed时,那么js对象就不会被释放并将触发此窗口的 closed.

// 打开一个新窗口
nw.Window.open('popup.html', {}, function(win) {
// 新窗口关闭后释放'win'对象
win.on('closed', function() {
  win = null;
});
// 监听主窗口的`close`事件
nw.Window.get().on('close', function() {
  // 关闭时先进行隐藏以让用户觉得立即关闭
  this.hide();
  // 虽然关了,但实际上它还在工作
  if (win != null)
    win.close(true);
  // 关闭新窗口也关闭主窗口
  this.close(true);
});
});

事件: loading

触发:窗口加载时,如A窗口监听着B窗口的loading事件,B窗口进行了刷新或重载

由于需要在设置回调方法之前触发该事件,所以在窗口开始加载时无法触发 loading.

除非,其它窗口正在监听该窗口的 loading时,该窗口进行了刷新或重载.

事件: loaded

触发:窗口加载完成后

该事件行为与 window.onload类似,但无需依赖DOM.

事件: document-start(frame)

触发:窗口文档对象或者子框架可用且所有文件加载之后,构建DOM或运行任何脚本之前

• frame HTMLIFrameElement - iframe对象 , 如果为null表示窗口事件 .

通过 nw.Window.open()创建的新窗口并不会触发这个事件且会解除事件绑定的回调函数.

参考配置文件中 inject-js-start字段 .

事件: document-end(frame)

触发:窗口文档对象或者卸载时, onunload事件被触发之前

• frame HTMLIFrameElement - iframe对象 , 如果为null表示窗口事件 .

参考配置文件中 inject-js-end字段 .

事件: focus

触发:窗口获得焦点时

事件: blur

触发:窗口失去焦点时

事件: minimize

触发:窗口最小化时

事件: restore

触发:从最小化,最大化或全面模式进行荒原时,如最大化还原时

事件: maximize

触发:窗口最大化时

事件: move(x, y)

触发:窗口移动时(将左上角的左侧和顶端距离坐标 (x, y)传至回调)

事件: resize(width, height)

触发:窗口调整大小时(将新尺寸宽度和高度 (width, height)传至回调)

事件: enter-fullscreen

触发:窗口进入全屏时

事件: zoom

触发:窗口缩放时 该事件需要提供缩放等级参数(0表示正常大小 ; 数值为正数表示放大 ; 数值为负数表示缩小 . )

事件: devtools-closed

触发:调试工具被关闭时

更多细节参阅 win.closeDevTools() 方法

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

触发:该窗口内或子框架中打开新窗口时

• frame HTMLIFrameElement - 要处理的子框架对象 , 为 null表示顶层窗口 .
• url String - 请求的链接地址 .
• policy Object - 改变打开新窗口的默认行为,如下:
  • ignore() : 忽略请求
  • forceCurrent() : 在同一框架中打开
  • forceDownload() : 链接是可下载的，或者由外部程序打开
  • forceNewWindow() : 新窗口中打开
  • forceNewPopup() : 新弹出窗口中打开
  • setNewWindowManifest(m) : 控制新弹出窗口中的参数 . m对象格式等同配置文件中Window子字段

例如使用系统默认浏览器打开指定URL:

nw.Window.get().on('new-win-policy', function(frame, url, policy) {
  // 不打开窗口
  policy.ignore();
  // 在系统默认浏览器打开
  nw.Shell.openExternal(url);
});

事件: navigation (frame, url, policy)

触发:导航到其他页面时

• frame HTMLIFrameElement - 要处理的子框架对象 , 为 null表示顶层窗口 .
• url String - 请求的链接地址 .
• policy Object - 可忽略导航,如下:
  • ignore() : 忽略请求

用法类同上文new-win-policy