Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ScrollContainer

继承: Container < Control < CanvasItem < Node < Object

派生: EditorInspector

需要时能够为子控件提供滚动条的容器。

描述

用于在需要时为子控件提供滚动条的容器。滚动条会自动绘制在右侧(垂直滚动条)或底部(水平滚动条),拖动滚动条能够移动 ScrollContainer 中的可见 Control(及其子项)。滚动条会根据该 Control 的 Control.custom_minimum_size 相对于 ScrollContainer 的大小自动调整抓取器的大小。

教程

属性

bool

clip_contents

true (overrides Control)

bool

follow_focus

false

ScrollMode

horizontal_scroll_mode

1

int

scroll_deadzone

0

int

scroll_horizontal

0

float

scroll_horizontal_custom_step

-1.0

int

scroll_vertical

0

float

scroll_vertical_custom_step

-1.0

ScrollMode

vertical_scroll_mode

1

方法

void

ensure_control_visible ( Control control )

HScrollBar

get_h_scroll_bar ( )

VScrollBar

get_v_scroll_bar ( )

主题属性

StyleBox

panel


信号

scroll_ended ( )

通过触摸事件拖动可滚动区域而导致滚动停止时发出。当通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时,会发出该信号。

注意:该信号仅在 Android 或 iOS 上,或在启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 时的桌面/Web 平台上发出。


scroll_started ( )

通过触摸事件拖动可滚动区域而导致滚动开始时发出。当通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时,会发出该信号。

注意:该信号仅在 Android 或 iOS 上,或在启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 时的桌面/Web 平台上发出。


枚举

enum ScrollMode:

ScrollMode SCROLL_MODE_DISABLED = 0

禁用滚动,滚动条不可见。

ScrollMode SCROLL_MODE_AUTO = 1

启用滚动,滚动条仅在需要时可见,即容器的内容比容器大时。

ScrollMode SCROLL_MODE_SHOW_ALWAYS = 2

启用滚动,滚动条始终可见。

ScrollMode SCROLL_MODE_SHOW_NEVER = 3

启用滚动,滚动条隐藏。


属性说明

bool follow_focus = false

  • void set_follow_focus ( bool value )

  • bool is_following_focus ( )

如果为 true,则 ScrollContainer 将自动滚动到获得焦点的子项(包括间接子项)以确保它们完全可见。


ScrollMode horizontal_scroll_mode = 1

控制水平滚动条是否可用、应该何时可见。选项见 ScrollMode


int scroll_deadzone = 0

  • void set_deadzone ( int value )

  • int get_deadzone ( )

触摸滚动的死区。较低的死区使滚动更加敏感。


int scroll_horizontal = 0

  • void set_h_scroll ( int value )

  • int get_h_scroll ( )

当前的水平滚动值。

注意:如果在 Node._ready 函数或更早的函数中设置该值,则需要用 Object.set_deferred 包装,因为滚动条的 Range.max_value 此时尚未初始化。

func _ready():
    set_deferred("scroll_horizontal", 600)

float scroll_horizontal_custom_step = -1.0

  • void set_horizontal_custom_step ( float value )

  • float get_horizontal_custom_step ( )

覆盖点击内部滚动条的水平增减按钮或 ScrollBar 处于聚焦状态下使用方向键时使用的 ScrollBar.custom_step


int scroll_vertical = 0

  • void set_v_scroll ( int value )

  • int get_v_scroll ( )

当前的垂直滚动值。

注意:scroll_horizontal 一样,最初设置时需要进行延迟。

func _ready():
    set_deferred("scroll_vertical", 600)

float scroll_vertical_custom_step = -1.0

  • void set_vertical_custom_step ( float value )

  • float get_vertical_custom_step ( )

覆盖点击内部滚动条的垂直增减按钮或 ScrollBar 处于聚焦状态下使用方向键时使用的 ScrollBar.custom_step


ScrollMode vertical_scroll_mode = 1

控制垂直滚动条是否可用、应该何时可见。选项见 ScrollMode


方法说明

void ensure_control_visible ( Control control )

确保给定的 control 控件可见(必须是 ScrollContainer 的直接或间接子节点)。会被 follow_focus 使用。

注意:这不适用于在同一帧内刚刚添加的节点。如果想滚动到一个新添加的子节点,就必须使用 SceneTree.process_frame 等待至下一帧:

add_child(child_node)
await get_tree().process_frame
ensure_control_visible(child_node)

HScrollBar get_h_scroll_bar ( )

返回该 ScrollContainer 的水平滚动条 HScrollBar

警告:这是一个必要的内部节点,移除和释放它可能会导致崩溃。如果你想禁用或隐藏滚动条,可以使用 horizontal_scroll_mode


VScrollBar get_v_scroll_bar ( )

返回该 ScrollContainer 的垂直滚动条 VScrollBar

警告:这是一个必要的内部节点,移除和释放它可能会导致崩溃。如果你想禁用或隐藏滚动条,可以使用 vertical_scroll_mode


主题属性说明

StyleBox panel

ScrollContainer 的背景 StyleBox