ScrollContainer

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

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

描述

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

教程

使用容器

属性

bool	clip_contents	`true` (overrides Control)
bool	draw_focus_border	`false`
bool	follow_focus	`false`
ScrollMode	horizontal_scroll_mode	`1`
int	scroll_deadzone	`0`
ScrollHintMode	scroll_hint_mode	`0`
int	scroll_horizontal	`0`
float	scroll_horizontal_custom_step	`-1.0`
int	scroll_vertical	`0`
float	scroll_vertical_custom_step	`-1.0`
bool	tile_scroll_hint	`false`
ScrollMode	vertical_scroll_mode	`1`

方法

void	ensure_control_visible(control: Control)
HScrollBar	get_h_scroll_bar()
VScrollBar	get_v_scroll_bar()

主题属性

Color	scroll_hint_horizontal_color	`Color(0, 0, 0, 1)`
Color	scroll_hint_vertical_color	`Color(0, 0, 0, 1)`
int	scrollbar_h_separation	`0`
int	scrollbar_v_separation	`0`
Texture2D	scroll_hint_horizontal
Texture2D	scroll_hint_vertical
StyleBox	focus
StyleBox	panel

信号

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

启用滚动，滚动条隐藏。

ScrollMode SCROLL_MODE_RESERVE = 4

SCROLL_MODE_AUTO 和 SCROLL_MODE_SHOW_ALWAYS 的结合。仅在必要时显示滚动条，但是会按照滚动条始终显示来调整内容的大小。适合需要保证无论滚动条是否可见，内容大小都保持一致的场合。

enum ScrollHintMode: 🔗

ScrollHintMode SCROLL_HINT_MODE_DISABLED = 0

Scroll hints will never be shown.

ScrollHintMode SCROLL_HINT_MODE_ALL = 1

Scroll hints will be shown at the top and bottom (if vertical), or left and right (if horizontal).

ScrollHintMode SCROLL_HINT_MODE_TOP_AND_LEFT = 2

Scroll hints will be shown at the top (if vertical), or the left (if horizontal).

ScrollHintMode SCROLL_HINT_MODE_BOTTOM_AND_RIGHT = 3

Scroll hints will be shown at the bottom (if horizontal), or the right (if horizontal).

属性说明

bool draw_focus_border = false 🔗

void set_draw_focus_border(value: bool)
bool get_draw_focus_border()

如果为 true，则当 ScrollContainer 或其子节点获得焦点时会绘制 focus。

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()

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

int scroll_deadzone = 0 🔗

void set_deadzone(value: int)
int get_deadzone()

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

ScrollHintMode scroll_hint_mode = 0 🔗

void set_scroll_hint_mode(value: ScrollHintMode)
ScrollHintMode get_scroll_hint_mode()

The way which scroll hints (indicators that show that the content can still be scrolled in a certain direction) will be shown.

Note: Hints won't be shown if the content can be scrolled both vertically and horizontally.

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。

bool tile_scroll_hint = false 🔗

void set_tile_scroll_hint(value: bool)
bool is_scroll_hint_tiled()

If true, the scroll hint texture will be tiled instead of stretched. See scroll_hint_mode.

ScrollMode vertical_scroll_mode = 1 🔗

void set_vertical_scroll_mode(value: ScrollMode)
ScrollMode get_vertical_scroll_mode()

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

方法说明

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。

主题属性说明

Color scroll_hint_horizontal_color = Color(0, 0, 0, 1) 🔗

Color used to modulate the scroll_hint_horizontal texture.

Color scroll_hint_vertical_color = Color(0, 0, 0, 1) 🔗

Color used to modulate the scroll_hint_vertical texture.

int scrollbar_h_separation = 0 🔗

The space between the ScrollContainer's vertical scroll bar and its content, in pixels. No space will be added when the content's minimum size is larger than the ScrollContainer's size.

int scrollbar_v_separation = 0 🔗

The space between the ScrollContainer's horizontal scroll bar and its content, in pixels. No space will be added when the content's minimum size is larger than the ScrollContainer's size.

Texture2D scroll_hint_horizontal 🔗

The indicator that will be shown when the content can still be scrolled horizontally. See scroll_hint_mode.

Texture2D scroll_hint_vertical 🔗

The indicator that will be shown when the content can still be scrolled vertically. See scroll_hint_mode.

StyleBox focus 🔗

ScrollContainer 的聚焦边框 StyleBox。仅在 draw_focus_border 为 true 时使用。

StyleBox panel 🔗

ScrollContainer 的背景 StyleBox。