文档手册

数量 450

添加文章编辑

Window类

2024-07-07 00:24:43

class Window

Window类的窗口表示桌面窗口。

Window.this 是对当前窗口对象的引用，即加载HTML文档的 Window 类的实例。

注意：下面的窗口是Sciter的Window类的一个实例-例如 Window.this ，但不是浏览器中奇怪的“窗口”。

构造器：

new Window({params:object})

其中 params 是具有以下属性的对象：

type -可选，是以下之一：

Window.POPUP_WINDOW
Window.TOOL_WINDOW
Window.CHILD_WINDOW
Window.FRAME_WINDOW -默认窗口类型
Window.DIALOG_WINDOW

parent ：Window -可选，父窗口的实例（所有者窗口）。当所有者将被关闭或最小化时，此窗口也将被关闭/最小化。
caption ：string -可选，窗口标题（或标题）。
x ：整数-可选，屏幕像素，窗口在屏幕上的水平位置;
y ：整数-可选，屏幕像素，窗口从屏幕顶部的垂直位置;
width ：integer -屏幕像素，窗口宽度;
height ：integer -屏幕像素，窗口高度;
client ：真|false -如果 true ，则x，y，w，h是屏幕上所需窗口客户端框的坐标;
alignment ：integer -可选，[1 to 9]对齐显示器上的窗口，如果提供了[-1 to -9]和父窗口，则它将窗口与父窗口对齐。（1左下角，2中下角，3右下角，4中左，5中，6中右，7左上角，8中上，9右上角）
screen ：integer -可选，多主系统上的显示器数量。
state ：- optional - window state，是以下之一：

Window.WINDOW_SHOWN -默认状态
Window.WINDOW_MINIMIZED
Window.WINDOW_MAXIMIZED
Window.WINDOW_HIDDEN
Window.WINDOW_FULL_SCREEN

url ：string -可选，窗口html源代码文件。
parameters ：数组|字符串|object，. - 传递给新窗口的可选的额外参数。

产品特性：

focus

读/写属性，null或焦点中的元素;

state

window.state -读/写，整数，以下之一：

1 Window.WINDOW_SHOWN -窗口正常显示;
2 Window.WINDOW_MINIMIZED -窗口折叠为图标/托盘，也称为“图标化”状态;
3 Window.WINDOW_MAXIMIZED -窗口跨越桌面的整个工作区域（不包括桌面等）;
4 Window.WINDOW_HIDDEN -窗口被隐藏（不可见）;
5 Window.WINDOW_FULL_SCREEN -窗口跨越整个桌面区域，因此出现在所有其他窗口（包括Windows等）的顶部;
0 Window.WINDOW_SHOWN_NA -只写值，使用它来显示窗口而不激活它（设置焦点）;

frameType

window.frameType -读/写，字符串，窗口的帧类型，以下之一：

"standard" -默认帧类型;
"transparent" -透明（也称为分层）窗口;
"solid" -不透明，没有任何装饰的矩形窗口;
"solid-with-shadow" -没有标题和按钮的非透明窗口，如果操作系统支持，可能会有圆角和阴影。
"extended" -标准窗口形状，但没有标题栏。标题和窗口按钮（例外：MacOS）应在标记/css中定义。

caption

读写，字符串，窗口的标题（标题）。

icon

读/写，图形。图像，窗口图标。

screen

只读，整型。报告屏幕（监视器）索引此窗口此时打开。在范围[0.窗户。

graphicsBackend

只读，字符串。报告当前使用的图形后端：“direct 2d”，“Skia/OpenGL”等。

minSize, maxSize

window.minSize = [w,h] -获取/设置可调整大小的窗口的最小大小。
window.maxSize = [w,h] -获取/设置可调整大小的窗口的最大大小。

blurBehind

window.blurBehind = "..." -读/写，字符串，模糊效果配置字符串，或者：

"none" -无模糊后效果;
"dark|light|auto [ultra] [source-auto|source-windows|source-desktop]" -标记组合字符串，其中：

"source-windows" -此窗口后面的所有窗口模糊;
"source-desktop" -桌面背景图像模糊-所谓的云母效果;
"source-auto" -默认，根据窗口类型选择模糊源;

示例：W11云母光效果窗： window.blurBehind = "light source-desktop" ;

isActive

只读，布尔，如果窗口有输入焦点，则报告。

isAlive

只读，布尔值，如果窗口是活动的，则为true-具有有效的HWINDOW。当窗口关闭并销毁时，该属性为false。

isOnActiveSpace

只读，如果窗口现在在活动空间上，则为true。如果主机系统不支持空间（虚拟桌面），则该属性未定义。

isResizable

读/写，布尔值，如果用户可以调整窗口大小，则为true。

isMaximizable

读/写，布尔值，如果用户可以最大化窗口，则为true。

isMinimizable

读/写，布尔值，如果窗口可以被用户最小化，则为true。

isTopmost

读/写，布尔值，如果窗口在z顺序上是最高的，则为true。

isEnabled

读/写，布尔值，如果窗口允许接受用户的输入，则为true。

aspectRatio

读/写，浮动，宽高比，以保持窗口大小。

eventRoot

 Window.this.eventRoot = element | null

如果按元素设置，则将所有UI事件短接到该元素及其子元素，就好像窗口仅包含该元素一样。在lightbox对话框场景中使用（参见：samples.sciter/lightbox-dialog）。

focus

读/写，焦点中的DOM元素。

parent

只读，窗口|null -父窗口。

document

只读，文档-窗口的根文档。

parameters

只读，任何参数由构造函数提供，在窗口中可用。

methods:

box（）

window.box(boxPart,boxOf[,relTo[, asPPX : bool ]]):[...]

报告窗的几何图形。

产品参数：

boxPart定义了要返回的盒子的哪一部分，是以下之一：

"xywh" 或 "rectw" - [x，y，w，h]，数组，矩形的位置和尺寸。
"rect" - [x1，y1，x2，y2]，数组，矩形的原点和角的位置。
"position" - [x，y]，数组，矩形的位置。
"dimension" - [w，h]，数组，矩形的维数。
"left" 、 "top" 、 "right" 、 "bottom" 、 "width" 、 "height" -单个整数。

boxOf是其中之一：

"border" -窗口的边框区域，包括窗口标题和客户端区域周围的边框;
"client" -窗口的客户端（内容）区域;
"cursor" -鼠标光标位置，如 let [cx,cy] = Window.this.box("position","cursor","desktop");
"caret" -插入符号位置，相对于窗口的客户区;

relTo是其中之一：

"desktop" -坐标相对于桌面（系统中所有显示器的轮廓）;
"monitor" -坐标是相对于该窗口被替换的监视器;
"self" -坐标是相对于窗口的客户区的原点;

asPPX可选，是一个布尔值：

true -坐标以物理设备像素为单位;
false -坐标以CSS像素为单位- 1/96英寸;

screenBox（）

window.screenBox(what [, boxPart [,asPPX]])

报告此窗口打开时监视器的几何结构。

产品参数：

定义返回哪些信息的是以下内容之一：

"frame" -显示器的物理位置和尺寸，以投影在桌面上的屏幕像素为单位。
"workarea" -监视器上工作区域的物理位置和大小（帧减去宽度）
"device" - string，显示器的名称。
"isPrimary" - boolean，true表示主监视器。
"snapshot" - Graphics.Image，返回显示器的快照（屏幕截图）。

boxPart定义了要返回的盒子的哪一部分，是以下之一：

"xywh" 或 "rectw" - [x，y，w，h]，数组，矩形的位置和尺寸。
"rect" - [x1，y1，x2，y2]，数组，矩形的原点和角的位置。
"position" - [x，y]，数组，矩形的位置。
"dimension" - [w，h]，数组，矩形的维数。
"left" 、 "top" 、 "right" 、 "bottom" 、 "width" 、 "height" -单个整数。

asPPX是一个布尔值：

true -坐标以物理设备像素为单位;
false -坐标以CSS像素为单位- 1/96英寸;

move()

window.move(x, y [,width, height [, "client" ]])

移动/调整窗口大小。

参数：x、y、width、height以PPX（物理屏幕像素）为单位。

如果提供了“client”，则x、y、width、height被视为窗口客户区坐标。

moveTo()

window.moveTo(monitor, x, y [,width, height [, "client" ]])

移动/调整窗口大小到特定的监视器;

x、y、宽度、高度以DIP表示-设备独立像素（也称为CSS像素）。

selectFile()

window.selectFile({params:object})

文件打开/保存对话框，params是一个对象，带有以下字段：

mode ：“保存”|“开放”|“开倍数”
filter ：“标题|ext1;ext2”， "HTML File (*.htm,*.html)|*.html;*.htm|All Files (*.*)|*.*"
extension ：默认文件扩展名，“html”
caption ：对话框标题，“另存为”
path ：初始目录

字符串，在“打开”和“保存”模式下选定文件的文件URL;
array（string），选定文件的列表;
如果用户取消了选择，则返回null。

selectFolder()

window.selectFolder({params:object})

文件夹打开对话框，params是一个对象，带有字段：

caption ：对话框标题
path ：初始目录

返回字符串-文件夹URL;

mediaVar()

window.mediaVar(varname[,value])

获取/设置可以在CSS中使用的媒体变量 @media varname {...}

mediaVars()

window.mediaVars([values:object])

一次获取/设置多个媒体变量。

addEventHandler()

on()

window.on("eventname", handler)

订阅窗口相关事件。

尖端

eventname可以包含命名空间后缀：“move.mycomponent”

off()

window.off("eventname" | handler)

通过名称、命名空间或处理程序引用取消订阅事件处理程序

dispatchEvent()

window.dispatchEvent(event):boolean

将事件同步发送到窗口。如果任何事件处理程序使用该事件，则返回true。

postEvent()

window.postEvent(event)

将事件异步发布到窗口。函数立即返回-不等待事件消费。

load()

Window.this.load(url:string)

将新文档加载到窗口中。

尖端

几乎总是最好不要使用这种方法，而是在窗口中使用 <frame> 并在那里加载所需的文档：

document.$("frame.content").src = url;

xcall()

window.xcall(name:string [, arg0, ..., argN]): any

与附加到窗口的本机行为的交互。 window.xcall("foo") 将在使用SciterWindowAttachEventServer API附加到窗口的本地行为的 handle_scripting_call() 中结束。

doEvent()

window.doEvent(mode) : any

在应用程序消息队列中执行系统事件，模式为以下模式之一：

“wait”-等待下一个事件并执行它;
“noWait”-如果下一个事件可用，则执行它，否则立即返回;
“untilMouseUp”-执行事件直到mouseup事件到达，用于各种拖动情况;
“untilQuit”-执行运行循环-执行所有事件，直到应用程序退出消息到达;
“I/O”-执行与I/O相关的事件;

window.modal(JSX) : any

显示预定义的消息框：

<info>..</info>,
<alert>..</alert>,
<error>..</error>,
<question>..</question>.

window.modal({params}) : any

显示新窗口作为对话框，参数见 new Window({params}) 。该函数返回窗口内 window.close(valToReturn) 调用的窗口关闭值。

window.modal(new Window(...)) : any

显示已构建的窗口模式。

performDrag()

window.performDrag(data:object, mode, dragIcon[, dragIconXoff, dragIconYoff] ): null | string

使用系统D&D机制执行拖放。

产品参数：

数据对象，可以包含一个或多个字段：

text: string -纯文本数据;
html: string - HTML数据;
file : [path1,path2,...] | path0 -单个或多个文件名;
json ：any -任何可以被JSON.stringify'ed艾德的数据;

mode，string，“copy”或“move”;
dragIcon，图像或元素;
dragIconXoff，dragIconXoff -整数，图标锚点偏移。

null -用户通过按Escape取消了D&D操作。
“复制”-用户完成复制操作（D&D + CTRL）;
“move”-用户完成移动操作;

focusable()

该函数允许以TAB顺序枚举元素。

window.focusable(dir [,reference:element]): element

产品参数：

dir，string，其中之一：

“prior”-引用后的前一个可聚焦元素;
“first”-窗口上第一个可聚焦的DOM元素;
“last”-窗口上最后一个可聚焦的DOM元素;
“next”-引用后的下一个可聚焦元素;

reference -可选，必须是一个可聚焦的元素，具有：

tabindex >= 0或
element.state.focusable = true 或
STATE_FOCUSABLE 在本地代码中。

尖端

您可以将找到的元素分配给 window.focus = element ，并在其上设置焦点。

close()

window.close([value]): bool

请求关闭窗口，该值是模态对话框中使用的返回值;

update()

window.update()

请求计算窗口内元素的布局。元素的位置应该在调用之后知道。

activate()

window.activate(bringToFront: bool)

在窗口上设置输入焦点。

trayIcon()

window.trayIcon({image: Graphics.Image, text: string})

显示托盘图标与图像和工具提示文本。

托盘图标将在用户点击时生成“trayiconclick”事件。

window.trayIcon("remove")

删除托盘图标。

const [x,y,w,h] = window.trayIcon("place");

报告图标在桌面上的位置，坐标以屏幕像素为单位。

requestAttention()

window.requestAttention("info" | "alert" | "stop")

通过任务/停靠栏中的闪烁或弹跳窗口图标来请求用户注意。

addHotKeyHandler()

window.addHotKeyHandler(keyCombination:string, callback:function):id

注册全局系统热键挂钩。热键处理程序允许在窗口没有焦点或者甚至隐藏时处理组合键。

如果系统拒绝热键，例如，如果该热键已分配给其他应用程序，则该函数将抛出错误。

keyCombination是可选修饰符和键名（事件.代码名）的 + 组合，如： "F5" 和 "Control+KeyN" 。支持的修改器：

Control 或 Ctrl ;
Command 或 Cmd -MacOS上的CMD键和Windows上的Win键;
Alt;
AltGr;
Shortcut -在MacOS上是CMD键，在其他操作系统上是Ctrl键;
Shift;

该函数返回一个id，可用于注销热键。

危险

此功能仅在Windows上支持一段时间，因为只有此操作系统具有官方热键API。

removeHotKeyHandler()

removeHotKeyHandler(id)

设置热键处理程序 addHotKeyHandler 。

isOnActiveSpace

如果窗口现在位于活动虚拟桌面上，则为true。

类方法和属性：

this

Window.this

属性，Window类的实例-运行此代码的窗口的引用;

all

Window.all: Array<Window>

当前进程中所有Sciter窗口的列表（包括Window.this）。用于枚举窗口：

for(let wnd of Window.all)
 ...

Window.share: Object

属性是应用程序中所有文档和窗口之间共享的对象。

危险

负责任地使用它。如果临时窗口或文档填充了共享对象，那么它应该在unload之前清理那里的东西。

screens

Window.screens: integer

返回系统中屏幕（监视器）的数量;

screenBox()

Window.screenBox(screen:integer, what[, boxPart])

报告给定屏幕（监视器）的几何形状和信息。关于什么和boxPart参数，请参见上面的window.screenBox（）方法。

此外，支持“devicePixelRatio”值，在这种情况下，该函数返回给定监视器的物理像素分辨率与CSS像素分辨率的比率。

elementAt()

Window.elementAt(screenX,screenY):Element

返回screenX/screenY位置下的DOM元素。

注意

此方法可以返回当前进程中属于任何Sciter窗口的DOM元素。

ticks()

Window.ticks():milliseconds

以毫秒为单位返回内部计时器的值。

post()

Window.post( ge: Event )

将全局事件ge发布到当前进程中的所有窗口。

send()

Window.send( ge: Event ) : boolean

同步发送全局事件ge到当前进程中的所有窗口。

发送在第一个窗口停止，该窗口将通过从此事件的事件处理程序返回true来使用该事件。

如果某个事件处理程序使用该事件，则返回true。

事件

使用 window.on("eventname", handler) 订阅这些事件。

"statechange"

window.state 标志已更改。

"closerequest"

要求关窗。

JS代码可以通过调用 event.preventDefault() 来阻止用户关闭窗口：

const CLOSE_BY_CHROME = 0; // user clicked `🗙` on window chrome
const CLOSE_BY_CODE = 1; // window.close() issued
const CLOSE_BY_LOAD = 2; // document unload-old/load-new

Window.this.on("closerequest", event => {
 if(event.reason == CLOSE_BY_CHROME) {
 // instead of closing we just minimize it:
 Window.this.state = Window.WINDOW_MINIMIZED;
    event.preventDefault(); // prevent closing the window
 }
});

"resolutionchange"

在窗口移动到另一个显示器与不同的分辨率，或用户已更改屏幕分辨率。

"mediachange"

一个或多个CSS媒体变量已更改。

"activate"

该窗口被停用（evt.reason == 0）或获得焦点（evt.reason> 0）。

"replacementstart"

"replacementend"

用户已经开始/结束移动或刷新窗口框架。

"move"

用户移动了窗口。

"size"

用户改变了窗口的大小。

"trayiconclick"

用户点击了托盘图标。

"spacechange"

空间（又名虚拟桌面）已更改。使用 Window.this.isOnActiveSpace 属性确定窗口现在是否在活动空间中。

文档手册

Window类

class Window

构造器：

产品特性：

focus

state

frameType

caption

icon

screen

graphicsBackend

minSize, maxSize

blurBehind

isActive

isAlive

isOnActiveSpace

isResizable

isMaximizable

isMinimizable

isTopmost

isEnabled

aspectRatio

eventRoot

focus

parent

document

parameters

methods:

box（）

screenBox（）

move()

moveTo()

selectFile()

selectFolder()

mediaVar()

mediaVars()

addEventHandler()

on()

off()

dispatchEvent()

postEvent()

load()

xcall()

doEvent()

modal()

performDrag()

focusable()

close()

update()

activate()

trayIcon()

requestAttention()

addHotKeyHandler()

removeHotKeyHandler()

isOnActiveSpace

类方法和属性：

this

all

share

screens

screenBox()

elementAt()

ticks()

post()

send()

事件

"statechange"

"closerequest"

"resolutionchange"

"mediachange"

"activate"

"replacementstart"

"replacementend"

"move"

"size"

"trayiconclick"

"spacechange"