ScrollContainer

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

派生： EditorInspector

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

描述

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

教程

• 使用容器

属性

方法

主题属性

信号

scroll_ended() 🔗

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

注意：该信号仅会在 Android、iOS、桌面、Web 平台上发出，在桌面/Web 平台上需要启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。

scroll_started() 🔗

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

注意：该信号仅会在 Android、iOS、桌面、Web 平台上发出，在桌面/Web 平台上需要启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。

枚举

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(value: bool)

• bool is_following_focus()

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

ScrollMode horizontal_scroll_mode = 1 🔗

• void set_horizontal_scroll_mode(value: ScrollMode)

• ScrollMode get_horizontal_scroll_mode()

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

int scroll_deadzone = 0 🔗

• void set_deadzone(value: int)

• int get_deadzone()

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

int scroll_horizontal = 0 🔗

• void set_h_scroll(value: int)

• 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(value: float)

• float get_horizontal_custom_step()

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

int scroll_vertical = 0 🔗

• void set_v_scroll(value: int)

• 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(value: float)

• float get_vertical_custom_step()

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

ScrollMode vertical_scroll_mode = 1 🔗

• void set_vertical_scroll_mode(value: ScrollMode)

• ScrollMode get_vertical_scroll_mode()

控制垂直滚动条是否可用、应该何时可见。选项见 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。