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

draw_focus_border

false

bool

follow_focus

false

ScrollMode

horizontal_scroll_mode

1

bool

propagate_maximum_size

false (overrides Control)

int

scroll_deadzone

0

ScrollHintMode

scroll_hint_mode

0

int

scroll_horizontal

0

bool

scroll_horizontal_by_default

false

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 的结合。仅在必要时显示滚动条，但是会按照滚动条始终显示来调整内容的大小。适合需要保证无论滚动条是否可见，内容大小都保持一致的场合。

ScrollMode SCROLL_MODE_MAXIMIZE_FIRST = 5

其行为类似于 SCROLL_MODE_AUTO，但会使 ScrollContainer 根据其内容报告一个最小尺寸（受对应轴向上设置的 Control.custom_maximum_size 限制）。这允许容器优先扩展自身，仅在空间受限时才开始出现滚动条。

enum ScrollHintMode: 🔗

ScrollHintMode SCROLL_HINT_MODE_DISABLED = 0

滚动提示将永远不会显示。

ScrollHintMode SCROLL_HINT_MODE_ALL = 1

滚动提示将显示在顶部和底部（如果是垂直的），或左侧和右侧（如果是水平的）。

ScrollHintMode SCROLL_HINT_MODE_TOP_AND_LEFT = 2

滚动提示将显示在顶部（如果是垂直的），或左侧（如果是水平的）。

ScrollHintMode SCROLL_HINT_MODE_BOTTOM_AND_RIGHT = 3

滚动提示将显示在底部（如果是水平的），或右侧（如果是垂直的）。

属性说明

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 🔗

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

int scroll_deadzone = 0 🔗

  • void set_deadzone(value: int)

  • int get_deadzone()

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

ScrollHintMode scroll_hint_mode = 0 🔗

滚动提示（指示内容可以向特定方向滚动的指示器）的显示方式。

注意：如果内容可以同时在垂直和水平方向滚动，则不会显示提示。

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)

bool scroll_horizontal_by_default = false 🔗

  • void set_scroll_horizontal_by_default(value: bool)

  • bool is_scroll_horizontal_by_default()

如果设置为 true，鼠标滚轮将水平滚动视图，而按住 Shift 键则进行垂直滚动。

如果设置为 false（默认），鼠标滚轮将垂直滚动视图，而按住 Shift 键则进行水平滚动。

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

如果为 true，则滚动提示纹理将平铺而不是拉伸。见 scroll_hint_mode。

ScrollMode vertical_scroll_mode = 1 🔗

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

方法说明

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

用于调制 scroll_hint_horizontal 纹理的 Color。

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

用于调制 scroll_hint_vertical 纹理的 Color。

int scrollbar_h_separation = 0 🔗

ScrollContainer 的垂直滚动条与其内容之间的间距，单位为像素。如果内容的最小大小大于 ScrollContainer 的大小，则不会添加任何间距。

int scrollbar_v_separation = 0 🔗

ScrollContainer 的水平滚动条与其内容之间的间距，单位为像素。如果内容的最小大小大于 ScrollContainer 的大小，则不会添加任何间距。

Texture2D scroll_hint_horizontal 🔗

当内容仍可水平滚动时将显示的指示器。请参阅 scroll_hint_mode。

Texture2D scroll_hint_vertical 🔗

当内容仍可垂直滚动时将显示的指示器。请参阅 scroll_hint_mode。

StyleBox focus 🔗

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

StyleBox panel 🔗

ScrollContainer 的背景 StyleBox。