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...

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

void set_horizontal_scroll_mode ( ScrollMode value )
ScrollMode get_horizontal_scroll_mode ( )

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

void set_vertical_scroll_mode ( ScrollMode value )
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。