Window

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

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

概要

// 获取window对象
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 {DOM Window} 可选 DOM窗口对象
Returns {Window} Window对象

如果window_object没有指定 , 将返回当前窗口的Window对象 , 否则返回window_object窗口的Window对象 .

// 获取当前窗口的`Window`对象
var win = nw.Window.get();

// 创建窗口并获取窗口对象
nw.Window.open('https://github.com/nwjs/nw.js', {}, function(new_win) {
  // 新窗口可完成工作
});

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

版本从0.13之后部分方法行为发生变化 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

url {String} 打开窗口加载页面URL地址
options {Object} 可选参考配置文件中的窗口子字段 . 此外 , 以下额外字段也可使用 .
- new_instance {Boolean} 可选新窗口在独立渲染进程中打开 .
- inject_js_start {String} 可选页面文档加载前执行脚本 . 参考配置格式 .
- inject_js_end {String} 可选页面文档加载之后执行脚本 . 参考配置格式 .
- id {String} 可选窗口唯一标识 . 使用该参数能够记录窗口尺寸以及位置以便再次打开窗口时进行恢复 . 参考Chrome应用文档
callback(win) {Function} 可选回调打开窗口 , Window对象作为回调方法参数以便使用 .

打开新窗口 , 同时利用url加载页面 .

窗口需要等待`loaded`事件之前完成加载页面相互作用的组件 .

新打开窗口默认不是聚焦窗口 . 如果需要聚焦 , 打开方法参数中`focus`需要设置为`true` .

win.window

获取窗口中DOM的window对象 .

win.x

win.y

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

win.width

win.height

获取或设置窗口宽度或高度 .

win.title

获取或设置窗口标题信息 .

win.menu

获取或设置窗口菜单 . 通过类型为menubar对象完成 . 当win.menu为null , Linux和Windows系统中 , 菜单栏被删除 , Mac系统中 , 菜单栏被清空 .

参考自定义菜单栏 , 也可参考菜单以及菜单项 .

win.isFullscreen

获取窗口是否为全屏模式 .

win.isTransparent

获取窗口是否为使用透明 .

win.isKioskMode

获取窗口是否使用Kiosk模式 .

win.zoomLevel

获取或设置页面缩放等级 . 0表示正常大小 ; 数值为正数表示放大 ; 数值为负数表示缩小 .

win.cookies.*

Cookies操作拥有多种功能 . 相关接口定义方式同Chrome扩展 . NW.js中支持get , getAll , remove以及set等方法 ; onChanged事件 , 支持addListener和removeListener操作事件 .

Chrome扩展中 , 相关CookieStore的扩展不支持 , 因为NW.js应用中只能适应一个全局cookie存储 .

win.moveTo(x, y)

x {Integer} 屏幕左侧偏移值
y {Integer} 屏幕顶部偏移值

移动窗口到指定位置 , 距离屏幕左侧以及顶部边缘的距离 .

win.moveBy(x, y)

x {Integer} 横向偏移值
y {Integer} 纵向偏移值

相对于当前窗口位置移动位置 , 按照横向或纵向进行偏移 .

win.resizeTo(width, height)

width {Integer} 窗口宽度
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()方法相同 .

部分系统中 , `show`不能使窗口聚焦 , 如果需要 , 可以调用`focus`方法完成聚焦 .

win.hide()

隐藏窗口 . 窗口一旦隐藏 , 用户将不能够找到以及使用隐藏窗口 .

win.close([force])

force {Boolean} 强制关闭窗口同时跳过close事件 .

关闭当前窗口 . 同时该方法可以阻止监听的close事件 . 如果设置force值为true , close事件将被忽略 .

通常监听close事件 , 完成关闭时完成的工作 , 同时调用close(true)真正关闭窗口 .

win.on('close', function() {
  this.hide(); // 阻止关闭窗口
  console.log("We're closing...");
  this.close(true); // 强制关闭窗口
});

win.close();

win.reload()

重新加载当前窗口 .

win.reloadDev()

通过新渲染进程重新加载当前页面 .

win.reloadIgnoringCache()

类似reload() , 但不使用缓存(又称"shift-reload") .

win.maximize()

Linux和Window中最大化窗口 , Mac OS X系统中放大窗口 .

win.unmaximize()

0.13版本之后弃用该方法 . 现在使用[`restore`事件](#event-restore)代替 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

取消窗口最大化 , 与maximize()方法相反 .

win.minimize()

Windows系统中窗口最小化到任务栏 , Linux系统图标化窗口 , Mac OS X系统最小化窗口 .

win.restore()

恢复系统到最小化窗口之前状态 , 与minimize()方法相反 . 通常使用restore方法 , 不使用unminimize()方法 .

win.enterFullscreen()

窗口全屏 .

该方法不同于HTML5中的全屏接口 , HTML5中的全屏接口只能使部分页面全屏 , `Window.enterFullscreen`可以使整个窗口进入全屏 .

win.leaveFullscreen()

退出全屏模式 .

win.toggleFullscreen()

切换全屏模式 .

win.enterKioskMode()

窗口进入Kiosk模式 . 该模式下 , 应用进入全屏并且阻止用户离开应用 , 这样应用需要提供一种离开该模式的方法 . 该模式主要适用公共展示 .

win.leaveKioskMode()

退出Kiosk模式 .

win.toggleKioskMode()

切换Kiosk模式 .

win.setTransparent(transparent)

0.13版本之后弃用该方法 , 参考[版本0.12到0.13版本迁移](../For Users/Migration/From 0.12 to 0.13.md) .

transparent {Boolean} 设置窗口透明

开启/关闭窗口透明支持 . 参考透明窗体 .

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

该方法只可以在SDK构造方式中使用 .

0.13版本之后该方法的作用发生变化 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

iframe {String} or {HTMLIFrameElement} 可选元素标识或者<iframe>标签 . 默认情况 , 开发工具作为独立窗口显示 , 检查该参数指定的iframe标签内容 .
callback(dev_win) {Function} 开发工具窗口回调方法 .

打开开发工具窗口 .

参数iframe为String类型为窗口中<iframe>标签的id属性 . 开发工具将检查该<iframe>中内容 . 如果为空字符串将没有效果 .

参数iframe为HTMLIFrameElement代表的iframe对象 . 作用与传入id参数作用相同 .

该方法返回Window对象作为参数的回调方法 . 可以使用Window中的任意属性 , 但不能使用事件 .

参考页面标签 , 如何为页面或者页面中打开开发工具 .

win.closeDevTools()

该方法只可以在SDK构造方式中使用 .

关闭开发工具窗口 .

win.getPrinters(callback)

列出系统中可以使用的打印机信息 . 回调方法将会接收到一个JSON对象格式的打印机信息数组 . JSON对象中的设备名可以在nw.Window.print()方法中使用 .

win.isDevToolsOpen()

该方法只可以在SDK构造方式中使用 .

获取当前窗口开发工具状态 .

参考win.showDevTools() .

win.print(options)

Print the web contents in the window without the need for user's interaction. options is a JSON object with the following fields:

无需用户交互完成打印窗口页面内容 . options为JSON对象格式 , 提供打印动作参数如下:

printer {String} 打印机设备名 , 可以通过nw.Window.getPrinters()获取 , 打印PDF格式时不需要设置该属性 .
pdf_path {String} 打印PDF格式时提供路径 .
headerFooterEnabled {Boolean} 是否启用页眉页脚 .
landscape {Boolean} 横向或纵向打印 .
mediaSize {JSON Object} 页面尺寸
shouldPrintBackgrounds {Boolean} 是否打印CSS背景
marginsType {Integer} 0 - 默认; 1 - 无留边; 2 - 最小值; 3 - 自定义, see marginsCustom.
marginsCustom {JSON Object} 自定义留边设置 , 单位为位 .

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.setMaximumSize(width, height)

width {Integer} 窗口最大宽度
height {Integer} 窗口最大高度

设置窗口最大宽度和高度 .

win.setMinimumSize(width, height)

width {Integer} 窗口最小宽度
height {Integer} 窗口最小高度

设置窗口最小宽度和高度 .

win.setResizable(resizable)

resizable {Boolean} 窗口是否可以调整大小 .

设置窗口是否可以调整大小 .

win.setAlwaysOnTop(top)

top {Boolean} 窗口是否总是置顶 .

设置窗口总是置于其他窗口之上 .

win.setVisibleOnAllWorkspaces(visible) (Mac 和 Linux)

visible {Boolean} 窗口在所有工作区中都可见

该方式只支持拥有多个工作区的系统中使用 , 比如Mac OS X和Linux系统 , 窗口同时在所有工作区中可见 .

win.canSetVisibleOnAllWorkspaces() (Mac and Linux)

返回应用所在系统是否支持所有工作区窗口可见 , 返回值为boolean类型 , 如果为true , 可以使用setVisibleOnAllWorkspace(Boolean)方法 .

win.setPosition(position)

position {String} 窗口所在位置 . 参数适用三个值 , 分别为:null , center , mouse .

移动窗口到指定位置 . 所有系统中都支持center , 窗口将置于屏幕中心 .

win.setShowInTaskbar(show)

show {Boolean} 是否在任务栏中显示 .

控制窗口在任务栏或者dock中显示 . 也可参考配置文件中show_in_tackbar字段 .

win.requestAttention(attension)

attension {Boolean} or {Integer} 类型为布尔 , 代表需要或者取消用户关注 . 类型为整型 , 标识窗口闪烁次数 .

通过窗口在任务栏中的删除获取用户关注 .

Mac系统中 , 设置值小于0代表`NSInformationalRequest` , 值大于0代表`NSCriticalRequest` .

win.capturePage(callback [, config ])

callback {Function} 截取窗口内容之后回调方法 .
config {String} or {Object} 可选类型为字符串 , 参考config.format可以使用的值 .
- format {String} 可选生成图片的格式 , 支持两种格式: "png"和"jpeg" , 默认类型为"jpeg" .
- datatype {String} 数据类型支持三种 , 分别为:"raw" "buffer"以及"datauri" , 默认类型为"datauri" .

截取窗口课件内容 .

数据类型为`"raw"`会使用Base64编码图片 . 类型为`"datauri"`可以直接使用`Image`标签中`src`属性加载图片 .

Example usage:

// 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)

progress {Float} 有效值为0到1之间的小数 , 设置为负数为删除进度条 .

Linux系统中 , 只有Ubuntu支持该功能 , 需要指定应用.desktop文件配置NW_DESKTOP环境变量 . 如果没有配置NW_DESKTOP环境变量 , 将默认使用nw.desktop .

win.setBadgeLabel(label)

设置任务栏或dock中窗口图标标签 .

Linux系统中 , 只有Ubuntu支持该功能 , 该标签只能为数字类型字符串 . 同样需要指定应用`.desktop`文件配置 , 参考[`setProgressBar`](#winsetprogressbar) .

win.eval(frame, script)

frame {HTMLIFrameElement} 执行框架 . 如果iframe为null , 将作用在当前窗口或者框架 .
script {String} 执行脚本代码 .

框架中执行一段JavaScript代码 .

win.evalNWBin(frame, path)

frame {HTMLIFrameElement} 执行框架 . 如果iframe为null , 将作用在当前窗口或者框架 .
path {String} 通过nwjc生成JavaScript保护文件路径 .

框架中加载和执行编译的JavaScript代码 . 参考V8编译保护JavaScript代码 .

事件: close

close事件影响Window.close()方法执行结果 . 如果监听窗口close事件 , Window.close()触发close事件 , 并不会关闭窗口 .

通常close事件回访方法中完成一些关闭工作 , 之后调用this.close(true)关闭窗口 , 关闭事件将不会再次触发 . 如果没有在this.close()传入true参数 , 关闭事件将进入无限循环中 .

close事件中完成的关闭工作会影响应用退出的速度 , 可以在关闭窗口中将窗口隐藏 , 之后完成关闭工作 , 最后关闭窗口 , 以提供用户较好的体验 .

参考win.close(true)中close事件中提供的例子代码 .

Mac系统中 , 使用<kbd>&#8984;</kbd>+<kbd>Q</kbd>关闭窗口时 , `close`事件回调方法中传入一个参数 , 成功关闭该值为`quit` , 否则为`undefined` .

事件: closed

窗口关闭之后触发closed事件 . 通常不能获取该事件 , 窗口关闭之后js对象将被释放 . 但被其他窗口监听当前窗口closed事件 , js对象将不会释放 , 同时可以触发该事件 .

// 打开新窗口
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

窗口开始加载时触发loading事件 , 通常不能触发该事件 , 因为设置回调方法之前触发该事件 .

唯一可以触发该事件方法是刷新窗口 , 同时其他窗口监听当前窗口loading事件 .

事件: loaded

窗口全部加载完成触发该事件 , 该事件行为与window.onload相同 , 只是不需要依赖DOM .

事件: document-start(frame)

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

窗口文档对象或者子框架可见触发 , 所有文件加载之后 , DOM构建或者脚本运行之前 . 通过nw.Window.open()创建新窗口不会触发 , 同时将解除事件绑定的回调函数 .

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

事件: document-end(frame)

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

窗口文件对象或自框架卸载时触发 , onunload事件触发之前 .

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

事件: focus

窗口获取焦点时触发 .

事件: blur

窗口失去焦点时触发 .

事件: minimize

窗口最小化时触发 .

事件: restore

0.13版本之后该事件行为发生变化 , 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

窗口由最小化 , 最大化以及全屏状态恢复时触发 .

事件: maximize

窗口最大化时触发 .

事件: move(x, y)

窗口移动时触发 . 回调方法两个参数: (x, y)表示窗口移动距离左侧和顶端位置 .

事件: resize(width, height)

窗口调整大小时触发 . 回调方法两个参数: (width, height)标识新窗口尺寸宽度和高度 .

事件: enter-fullscreen

窗口进入全屏时触发 .

事件: leave-fullscreen

0.13版本之后该事件弃用 . [`restore`事件](#event-restore)代替 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

窗口退出全屏模式时触发 .

事件: zoom

窗口缩放时触发 . 需要提供一个参数标识窗口新缩放等级 . 参考win.zoom()方法说明参数值定义方式 .

事件: capturepagedone

0.13版本之后弃用该方法 . 使用回调方法`win.capturePage()`代替 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

截屏方法调用并生成图片数据之后触发 . 参考win.capturePage()方法中参数值定义 .

事件: devtools-opened(url)

0.13版本之后弃用该方法 . 使用回调方法[`win.showDevtools`](#winshowdevtoolsiframe-callback)代替 . 参考[版本0.12到0.13迁移](../For Users/Migration/From 0.12 to 0.13.md) .

参考win.showDevTools()方法

事件: 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子字段相同 .

窗口或子框架打开新窗口时触发 . 通过policy.*方法改变打开新窗口的默认行为 .

例如 , 当打开新窗口时 , 系统默认浏览器将打开指定URL:


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

frame {HTMLIFrameElement} 需要处理的子框架对象 , 为null表示顶层窗口 .
url {String} 请求链接地址 .
policy {Object} 以下方法对象:
- ignore() : 忽略请求 .

导航到其他页面触发 . 同new-win-policy类似 , 回调方法中调用policy.ignore()忽略导航 .