Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Window¶
派生： AcceptDialog, Popup
所有窗口、对话框、弹出框的基类。
描述¶
创建窗口的节点。窗口可以是原生系统窗口，也可以是嵌入到其他 Window 中的窗口（见 Viewport.gui_embed_subwindows）。
运行时，Window 不会在请求关闭时自动关闭。你需要使用 close_requested 信号手动处理（适用于点击关闭按钮和点击弹出窗口外部）。
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法¶
主题属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
信号¶
about_to_popup ( )
在调用 popup 之后但在 Window 出现或执行任何操作之前发送的信号。
close_requested ( )
按下该 Window 的关闭按钮或启用 popup_window 并且用户在窗口外点击时发出。
这个信号可以用来处理窗口的关闭，例如将其连接到 hide。
dpi_changed ( )
该 Window 的 DPI 由于操作系统级别的更改而发生更改时发出（例如将该窗口从 Retina 屏幕移动到了更低分辨率的屏幕）。
注意：仅在 macOS 上实现。
files_dropped ( PackedStringArray files )
将文件从操作系统文件管理器拖放到游戏窗口时发出。参数为文件路径列表。
请注意，这个方法仅适用于原生窗口，即主窗口和禁用主视口 Viewport.gui_embed_subwindows 时的 Window 派生节点。
示例用法：
func _ready():
get_viewport().files_dropped.connect(on_files_dropped)
func on_files_dropped(files):
print(files)
focus_entered ( )
当该 Window 获得焦点时发出。
focus_exited ( )
当该 Window 失去焦点时发出。
go_back_requested ( )
发送返回请求时，在 Node.NOTIFICATION_WM_GO_BACK_REQUEST 之后发出（例如在 Android 上按下“返回”按钮）。
mouse_entered ( )
当鼠标光标进入 Window 的可见区域时发出，该区域未被其他 Control 或窗口遮挡，只要其 Viewport.gui_disable_input 为 false 并且无论它当前聚焦与否。
mouse_exited ( )
当鼠标光标离开 Window 的可见区域时发出，该区域未被其他 Control 或窗口遮挡，只要其 Viewport.gui_disable_input 为 false 并且无论它当前聚焦与否。
theme_changed ( )
发送 NOTIFICATION_THEME_CHANGED 通知时发出。
titlebar_changed ( )
窗口标题栏装饰发生改变时发出，例如 macOS 窗口进入/退出全屏模式，或者“扩展至标题”标志发生改变。
visibility_changed ( )
显示或隐藏该 Window 时发出。
window_input ( InputEvent event )
该 Window 持有焦点并收到任何输入时发出，会把收到的事件作为参数传入。该事件如果存在位置属性，该位置使用嵌入器的坐标系。
枚举¶
enum Mode:
Mode MODE_WINDOWED = 0
窗口模式，即 Window 不占据整个屏幕（除非设置为屏幕的大小）。
Mode MODE_MINIMIZED = 1
最小化窗口模式，即 Window 在窗口管理器的窗口列表中既不可见也不可用。通常发生在按下最小化按钮时。
Mode MODE_MAXIMIZED = 2
最大化窗口模式，即 Window 会占据整个屏幕区域，任务栏除外，并且会显示边框。通常发生在按下最大化按钮时。
Mode MODE_FULLSCREEN = 3
具有完整多窗口支持的全屏模式。
全屏窗口覆盖屏幕的整个显示区域，且没有任何装饰。显示的视频模式没有更改。
在 Windows 上：多窗口全屏模式具有 1px 宽的颜色为 ProjectSettings.rendering/environment/defaults/default_clear_color 的边框。
在 macOS 上：使用新桌面来显示正在运行的项目。
注意：无论平台如何，启用全屏都会更改窗口大小以匹配显示器的大小。因此，请确保你的项目在启用全屏模式时支持多种分辨率。
Mode MODE_EXCLUSIVE_FULLSCREEN = 4
单窗口全屏模式。这种模式开销较小，但一次只能在给定屏幕上打开一个窗口（打开子窗口或切换应用程序会触发全屏过渡）。
全屏窗口会覆盖屏幕的整个显示区域，没有边框或装饰。显示视频模式没有改变。
在 Windows 上：取决于视频驱动程序，全屏过渡可能会导致屏幕暂时变黑。
在 macOS 上：一个新的桌面用于显示正在运行的项目。当鼠标指针悬停在屏幕边缘时，独占全屏模式会阻止 Dock 和 Menu 出现。
在 Linux（X11）上：独占全屏模式会绕过合成器。
注意：无论平台如何，启用全屏都会更改窗口大小以匹配显示器的大小。因此，确保你的项目在启用全屏模式时支持多个分辨率。
enum Flags:
Flags FLAG_RESIZE_DISABLED = 0
该窗口不能通过拖动其调整大小的手柄来调整大小。仍然可以使用 size 来调整窗口的大小。这个标志对于全屏窗口来说是被忽略的。用 unresizable 设置。
Flags FLAG_BORDERLESS = 1
该窗口没有原生标题栏和其他装饰。全屏窗口会忽略该标志。由 borderless 设置。
Flags FLAG_ALWAYS_ON_TOP = 2
该窗口漂浮在所有其他窗口之上。全屏窗口会忽略该标志。由 always_on_top 设置。
Flags FLAG_TRANSPARENT = 3
该窗口的背景可以是透明的。使用 transparent 设置。
注意：如果 ProjectSettings.display/window/per_pixel_transparency/allowed 或该窗口的 Viewport.transparent_bg 为 false，则这个标志无效。
Flags FLAG_NO_FOCUS = 4
该窗口无法被聚焦。无焦点窗口会忽略除鼠标点击之外的所有输入。由 unfocusable 设置。
Flags FLAG_POPUP = 5
窗口为菜单或 OptionButton 下拉菜单的一部分。窗口可见时无法更改这个标志。活动的弹出窗口会以独占的形式接收所有输入，但不会从其父窗口窃取焦点。用户在区域外点击或切换应用程序时，弹出窗口会自动关闭。弹出窗口必须设置临时父级（见 transient）。
注意：这个标志在嵌入式窗口中无效（除非该窗口是 Popup）。
Flags FLAG_EXTEND_TO_TITLE = 6
窗口内容扩展到窗口的全部尺寸。与无边框窗口不同，框架保持不变，可以用来调整窗口的大小，标题栏是透明的，但有最小/最大/关闭按钮。用 extend_to_title 设置。
注意：这个标志在 macOS 上实现。
注意：这个标志在嵌入式窗口中无效。
Flags FLAG_MOUSE_PASSTHROUGH = 7
所有鼠标事件都被传递到同一应用程序的底层窗口。
注意：这个标志在嵌入式窗口中无效。
Flags FLAG_MAX = 8
Flags 的最大值。
enum ContentScaleMode:
ContentScaleMode CONTENT_SCALE_MODE_DISABLED = 0
不会为了匹配 Window 的大小而对内容进行缩放。
ContentScaleMode CONTENT_SCALE_MODE_CANVAS_ITEMS = 1
会将内容按照目标大小渲染。比 CONTENT_SCALE_MODE_VIEWPORT 更消耗性能，但结果更佳。
ContentScaleMode CONTENT_SCALE_MODE_VIEWPORT = 2
会将内容按照原始大小渲染，然后再缩放到目标大小。比 CONTENT_SCALE_MODE_CANVAS_ITEMS 性能更高，但会导致图像的像素化。
enum ContentScaleAspect:
ContentScaleAspect CONTENT_SCALE_ASPECT_IGNORE = 0
会忽略纵横比。缩放就是简单地将内容拉伸至目标大小。
ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP = 1
会保留内容的纵横比。如果目标大小与原始大小的纵横比不同，则会将图像居中，左右两侧会出现黑条。
ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_WIDTH = 2
内容可以垂直扩展。横向缩放时，会保留宽度比，在左右两侧添加黑条。
ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_HEIGHT = 3
内容可以水平扩展。纵向缩放时，会保留高度比，在上下两侧添加黑条。
ContentScaleAspect CONTENT_SCALE_ASPECT_EXPAND = 4
会保留内容的纵横比。如果目标大小与原始大小的纵横比不同，则内容会保持在左上角，将拉伸出的空间增加为可见区域。
enum ContentScaleStretch:
ContentScaleStretch CONTENT_SCALE_STRETCH_FRACTIONAL = 0
内容会根据小数系数进行拉伸。这样就能够填充窗口的所有空间，但非整数的像素缩放会导致发生“像素摆动”。
ContentScaleStretch CONTENT_SCALE_STRETCH_INTEGER = 1
内容只会根据整数系数进行拉伸，保持像素的锐利。可能导致窗口的边缘留出可见的黑色背景，具体取决于窗口大小。
enum LayoutDirection:
LayoutDirection LAYOUT_DIRECTION_INHERITED = 0
自动布局方向，由父窗口的布局方向决定。
LayoutDirection LAYOUT_DIRECTION_LOCALE = 1
自动布局方向，根据当前语言环境确定。
LayoutDirection LAYOUT_DIRECTION_LTR = 2
从左至右的布局方向。
LayoutDirection LAYOUT_DIRECTION_RTL = 3
从右至左的布局方向。
enum WindowInitialPosition:
WindowInitialPosition WINDOW_INITIAL_POSITION_ABSOLUTE = 0
初始窗口位置由 position 决定。
WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_PRIMARY_SCREEN = 1
初始窗口位置为主屏幕的中心。
WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_MAIN_WINDOW_SCREEN = 2
初始窗口位置为主窗口屏幕的中心。
WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_OTHER_SCREEN = 3
初始窗口位置为 current_screen 屏幕的中心。
WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_MOUSE_FOCUS = 4
初始窗口位置为鼠标指针所在屏幕的中心。
WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_KEYBOARD_FOCUS = 5
初始窗口位置为键盘聚焦的窗口所在屏幕的中心。
常量¶
NOTIFICATION_VISIBILITY_CHANGED = 30
该 Window 的可见性发生改变时，在 visibility_changed 之前发出。
NOTIFICATION_THEME_CHANGED = 32
当节点需要刷新其主题项时发送。以下任意情况都会触发：
此节点或其任何祖先节点更改了 theme 属性。
此节点更改了 theme_type_variation 属性。
节点进入场景树。
注意：为了优化性能，此节点在场景树之外发生更改时不会发送此通知。取而代之的是，当节点进入场景树时会统一应用所有主题项的更新。
属性说明¶
bool always_on_top = false
如果为 true，则该窗口将位于所有其他窗口的顶部。如果启用了 transient 则不起作用。
bool auto_translate = true
切换是否所有文本都应该根据当前区域设置自动变为翻译后的版本。
bool borderless = false
如果为 true，则该窗口将没有边框。
ContentScaleAspect content_scale_aspect = 0
void set_content_scale_aspect ( ContentScaleAspect value )
ContentScaleAspect get_content_scale_aspect ( )
指定当 Window 的大小改变时，内容纵横比的行为。基础纵横比由 content_scale_size 决定。
float content_scale_factor = 1.0
指定当 size 等于 content_scale_size 时 Window 内容的基础比例。
ContentScaleMode content_scale_mode = 0
void set_content_scale_mode ( ContentScaleMode value )
ContentScaleMode get_content_scale_mode ( )
指定当 Window 的大小改变时，如何对内容进行缩放。
Vector2i content_scale_size = Vector2i(0, 0)
内容的基础大小（内容指在窗口内绘制的节点）。如果非零，当窗口大小发生变化时，Window 的内容将被缩放。
ContentScaleStretch content_scale_stretch = 0
void set_content_scale_stretch ( ContentScaleStretch value )
ContentScaleStretch get_content_scale_stretch ( )
决定 2D 元素最终缩放系数的策略。会影响 content_scale_factor 的使用，与 content_scale_size 决定的自动缩放系数共同生效。
int current_screen
该窗口当前所在的屏幕。
bool exclusive = false
如果为 true，则 Window 将处于独占模式。独占窗口总是在其父窗口的顶部，会阻止所有输入到达父级 Window。
需要启用 transient 才能正常工作。
bool extend_to_title = false
如果为 true，则 Window 的内容将会扩展到窗口的完整大小，窗口标题栏是透明的。
注意：这个属性仅在 macOS 上实现。
注意：这个属性仅对原生窗口有效。
WindowInitialPosition initial_position = 0
void set_initial_position ( WindowInitialPosition value )
WindowInitialPosition get_initial_position ( )
指定该 Window 的初始位置类型。见 WindowInitialPosition 常量。
bool keep_title_visible = false
如果为 true，则该 Window 宽度被扩展以保持标题栏文本完全可见。
Vector2i max_size = Vector2i(0, 0)
如果非零，则调整该 Window 的大小时无法大于该尺寸。
注意：如果值小于 min_size，该属性将被忽略。
Vector2i min_size = Vector2i(0, 0)
如果非零，则调整该 Window 的大小时无法小于该尺寸。
注意：如果启用了 wrap_controls 并且 get_contents_minimum_size 更大，则此属性将被忽略。
Mode mode = 0
设置该窗口的当前模式。
注意：在 Windows 和 Linux 上，全屏与独占全屏是不同的模式。
注意：这个方法仅对原生窗口有效，即主窗口和禁用主视口 Viewport.gui_embed_subwindows 时的 Window 派生节点。
bool mouse_passthrough = false
如果为 true，则所有鼠标事件都会传递给同一应用的底层窗口。另见 mouse_passthrough_polygon。
注意：这个属性在 Linux（X11）、macOS 和 Windows 上实现。
注意：这个属性仅对原生窗口有效。
PackedVector2Array mouse_passthrough_polygon = PackedVector2Array()
void set_mouse_passthrough_polygon ( PackedVector2Array value )
PackedVector2Array get_mouse_passthrough_polygon ( )
设置窗口的一个接受鼠标事件的多边形区域。该区域外的鼠标事件将被传递出去。
传递一个空数组将禁用穿透支持（所有鼠标事件将被窗口拦截，这是默认行为）。
# 设置区域，使用 Path2D 节点。
$Window.mouse_passthrough_polygon = $Path2D.curve.get_baked_points()
# 设置区域，使用 Polygon2D 节点。
$Window.mouse_passthrough_polygon = $Polygon2D.polygon
# 重置区域为默认值。
$Window.mouse_passthrough_polygon = []
// 设置区域，使用 Path2D 节点。
GetNode<Window>("Window").MousePassthrough</