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

使用觸控事件拖曳可滾動區域時滾動停止時發出。拖曳滾動條時不會發出此訊號，使用滑鼠滾輪滾動或使用鍵盤/遊戲手把事件滾動。

注意：此訊號僅在啟用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 時在 Android 或 iOS 或桌面/Web 平台上發出。

scroll_started() 🔗

透過觸控事件拖曳可捲動區域時開始捲動時發出。拖曳滾動條時不會發出此訊號，使用滑鼠滾輪滾動或使用鍵盤/遊戲手把事件滾動。

注意：此訊號僅在啟用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 時在 Android 或 iOS 或桌面/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

啟用滾動，捲軸隱藏。

ScrollMode SCROLL_MODE_RESERVE = 4

Combines SCROLL_MODE_AUTO and SCROLL_MODE_SHOW_ALWAYS. The scrollbar is only visible if necessary, but the content size is adjusted as if it was always visible. It's useful for ensuring that content size stays the same regardless if the scrollbar is visible.

ScrollMode SCROLL_MODE_MAXIMIZE_FIRST = 5

Behaves like SCROLL_MODE_AUTO, but makes the ScrollContainer report a minimum size based on its content (limited by Control.custom_maximum_size when set on the corresponding axis). This allows it to grow first and only start scrolling once constrained.

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

If true, focus is drawn when the ScrollContainer or one of its descendant nodes is focused.

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

Controls whether horizontal scrollbar can be used and when it should be visible.

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)

bool scroll_horizontal_by_default = false 🔗

void set_scroll_horizontal_by_default(value: bool)
bool is_scroll_horizontal_by_default()

If true, the mouse wheel scrolls the view horizontally, and holding Shift scrolls vertically.

If false (default), the mouse wheel scrolls the view vertically, and holding Shift scrolls horizontally.

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

Controls whether vertical scrollbar can be used and when it should be visible.

方法說明

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 🔗

The focus border StyleBox of the ScrollContainer. Only used if draw_focus_border is true.

StyleBox panel 🔗

ScrollContainer 的背景 StyleBox。