> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/scrollingframe.md).

# ScrollingFrame

ScrollingFrame : `GuiObject`

## Overview

ScrollingFrame은 내부에 배치된 UI 요소가 표시 영역을 벗어날 경우, 자동으로 가로 또는 세로 스크롤을 제공하는 UI 컨테이너입니다. 인벤토리, 퀘스트 목록처럼 많은 항목을 한 화면에서 정돈된 형태로 보여주고자 할 때 특히 유용하며, 다양한 스크롤 동작을 상황에 맞게 설정할 수 있습니다.

ScrollingFrame은 **클라이언트 환경**에서만 제어할 수 있습니다.

## Properties

### AbsoluteCanvasSize

`Vector2`

사용자가 스크롤로 이동할 수 있는 전체 영역의 크기를 정의하는 읽기 전용 속성입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

wait(2)
print(ScrollingFrame.AbsoluteCanvasSize)
```

### AbsoluteWindowSize

`Vector2`

스크롤 바 영역을 뺀 실제 표시 영역의 크기를 정의하는 읽기 전용 속성입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print(ScrollingFrame.AbsoluteWindowSize)
```

### AutomaticCanvasSize

`Enum.AutomaticSize`

ScrollingFrame 내부 콘텐츠의 실제 크기에 맞추어 CanvasSize를 자동으로 조정하도록 설정하는 속성입니다.

AutomaticSize가 None이 아닐 경우, 지정한 방향에 따라 내부 UI 요소들의 실제 크기를 기반으로 AbsoluteCanvasSize가 산출되며, 자동으로 업데이트됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.AutomaticCanvasSize = Enum.AutomaticSize.XY
```

### BottomImage

`string`

스크롤 바의 아래쪽 끝부분에 표시할 이미지의 AssetId를 지정합니다.

BottomImageContent와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.BottomImage = "ovdrassetid://1234"
```

### BottomImageContent

`Content`

스크롤 바의 아래쪽 끝부분에 표시할 이미지를 Content 형식으로 지정합니다.

BottomImage와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("BottomImageContent : ", ScrollingFrame.BottomImageContent)
```

### CanvasPosition

`Vector2`

ScrollingFrame 안에서 캔버스가 현재 어느 위치에 놓여 있는지를 픽셀 단위로 지정하는 속성입니다.

설정된 값에 따라 스크롤 바도 동일한 위치로 조정됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.CanvasPosition = Vector2.new(0, 210)
```

### CanvasSize

`UDim2`

사용자가 스크롤로 이동할 수 있는 전체 영역의 크기를 지정합니다.

내부 콘텐츠의 양에 따라 스크롤 범위를 자동으로 산출하고자 할 때는 AutomaticCanvasSize를 사용할 수 있습니다.

또한 CanvasSize에 값을 직접 지정한 상태에서 AutomaticCanvasSize를 활성화하면, 자동으로 계산된 크기보다 CanvasSize에 입력한 값이 더 클 경우 해당 수동 설정 값이 우선적으로 적용됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.CanvasSize = UDim2.new(0, 0, 0, 400)
```

### DraggingScrollBar

`Enum.DraggingScrollBar`

현재 드래그 중인 스크롤 바를 나타내는 읽기 전용 속성입니다.

드래그 중이 아니면 None입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("DraggingScrollBar : ", ScrollingFrame.DraggingScrollBar)
```

### ElasticBehavior

`Enum.ElasticBehavior`

스크롤 경계에서 더 끌었을 때 경계를 넘었다가 되돌아오는 탄성 효과를 사용할 조건을 지정합니다.

* `WhenScrollable`: 스크롤할 수 있는 내용이 있을 때만 사용합니다.
* `Always`: 항상 사용합니다.
* `Never`: 사용하지 않습니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ElasticBehavior = Enum.ElasticBehavior.Never
```

### HorizontalBarRect

`Rect`

가로 스크롤 바가 화면에서 차지하는 영역을 픽셀 단위 사각형으로 나타내는 읽기 전용 속성입니다.

가로 스크롤 바가 표시되지 않으면 크기가 0인 사각형입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("HorizontalBarRect : ", ScrollingFrame.HorizontalBarRect)
```

### HorizontalScrollBarInset

`Enum.ScrollBarInset`

가로 스크롤 바의 두께를 콘텐츠 영역의 여백(inset)으로 적용하는 조건을 지정합니다.

* `None`: 여백을 적용하지 않습니다.
* `ScrollBar`: 스크롤 바가 표시될 때만 여백을 적용합니다.
* `Always`: 항상 여백을 적용합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.HorizontalScrollBarInset = Enum.ScrollBarInset.ScrollBar
```

### MaxCanvasPosition

`Vector2`

CanvasPosition에 지정할 수 있는 최댓값을 나타내는 읽기 전용 속성입니다.

축마다 AbsoluteCanvasSize에서 AbsoluteWindowSize를 뺀 값이며, 0보다 작아지지 않습니다. CanvasPosition에 이보다 큰 값을 지정하면 이 값으로 제한됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.CanvasPosition = Vector2.new(0, ScrollingFrame.MaxCanvasPosition.Y) -- 맨 아래로 스크롤
```

### MidImage

`string`

스크롤 바의 가운데 부분에 표시할 이미지의 AssetId를 지정합니다.

MidImageContent와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.MidImage = "ovdrassetid://1234"
```

### MidImageContent

`Content`

스크롤 바의 가운데 부분에 표시할 이미지를 Content 형식으로 지정합니다.

MidImage와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("MidImageContent : ", ScrollingFrame.MidImageContent)
```

### ScrollBarImageColor3

`Color3`

스크롤 바 이미지의 색상을 지정합니다.

값이 흰색이면 별도의 색 보정 없이 원본 이미지 그대로 표시됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollBarImageColor3 = Color3.fromRGB(255, 0, 0)
```

### ScrollBarImageTransparency

`number`

스크롤 바 이미지의 투명도를 지정합니다.

0은 완전한 불투명 상태를 의미하고, 1은 전혀 보이지 않는 상태를 의미합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollBarImageTransparency = 0.3
```

### ScrollBarThickness

`number`

스크롤 바의 두께를 픽셀 단위로 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollBarThickness = 30
```

### ScrollingDirection

`Enum.ScrollingDirection`

사용자가 콘텐츠를 어느 방향으로 스크롤할 수 있는지를 지정합니다.

선택한 방향으로만 스크롤 바가 생성됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollingDirection = Enum.ScrollingDirection.Y
```

### ScrollingEnabled

`boolean`

스크롤 동작을 허용할지 여부를 지정합니다.

스크롤을 비활성화하면 스크롤 바도 표시되지 않으며, 사용자는 콘텐츠를 스크롤 할 수 없습니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollingEnabled = false
```

### ScrollRate

`number`

스크롤 이동량의 배율을 지정합니다.

기본값은 1이며, 0보다 작은 값은 0으로 처리됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.ScrollRate = 2
```

### ScrollVelocity

`Vector2`

현재 스크롤 속도를 초당 픽셀 단위로 나타내는 읽기 전용 속성입니다.

CanvasPosition이 커지는 방향이 양수입니다. GetScrollVelocity()의 반환값과 같습니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("ScrollVelocity : ", ScrollingFrame.ScrollVelocity)
```

### SmoothScroll

`boolean`

스크롤 입력을 놓은 뒤에도 관성으로 부드럽게 이어서 스크롤할지 지정합니다.

기본값은 true입니다. false로 설정하면 진행 중인 관성 스크롤도 즉시 멈춥니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.SmoothScroll = false
```

### TopImage

`string`

스크롤 바의 위쪽 끝부분에 표시할 이미지의 AssetId를 지정합니다.

TopImageContent와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.TopImage = "ovdrassetid://1234"
```

### TopImageContent

`Content`

스크롤 바의 위쪽 끝부분에 표시할 이미지를 Content 형식으로 지정합니다.

TopImage와 값이 서로 동기화됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("TopImageContent : ", ScrollingFrame.TopImageContent)
```

### VerticalBarRect

`Rect`

세로 스크롤 바가 화면에서 차지하는 영역을 픽셀 단위 사각형으로 나타내는 읽기 전용 속성입니다.

세로 스크롤 바가 표시되지 않으면 크기가 0인 사각형입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

print("VerticalBarRect : ", ScrollingFrame.VerticalBarRect)
```

### VerticalScrollBarInset

`Enum.ScrollBarInset`

세로 스크롤 바의 두께를 콘텐츠 영역의 여백(inset)으로 적용하는 조건을 지정합니다.

* `None`: 여백을 적용하지 않습니다.
* `ScrollBar`: 스크롤 바가 표시될 때만 여백을 적용합니다.
* `Always`: 항상 여백을 적용합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.VerticalScrollBarInset = Enum.ScrollBarInset.ScrollBar
```

### VerticalScrollBarPosition

`Enum.VerticalScrollBarPosition`

세로 스크롤 바를 표시할 위치를 지정합니다.

* `Left`: 왼쪽에 표시합니다.
* `Right`: 오른쪽에 표시합니다. 기본값입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame.VerticalScrollBarPosition = Enum.VerticalScrollBarPosition.Left
```

## Methods

### ClearInertialScrolling

진행 중인 관성 스크롤을 즉시 멈추는 메서드입니다.

CanvasPosition은 멈춘 위치에 그대로 유지됩니다. ResetScrollVelocity()와 같은 동작을 합니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame:ClearInertialScrolling()
```

### GetSampledInertialVelocity

최근 스크롤 입력에서 측정한 관성 속도의 원시값을 반환하는 메서드입니다.

배율과 방향 보정이 적용되지 않은 값이므로, 일반적인 스크롤 속도 확인에는 GetScrollVelocity()를 사용하는 것을 권장합니다.

#### Parameters

#### Return

| `Vector2` | 보정 전 관성 속도입니다. |
| --------- | -------------- |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

local SampledInertialVelocity = ScrollingFrame:GetSampledInertialVelocity()
print("SampledInertialVelocity : ", SampledInertialVelocity)
```

### GetScrollVelocity

현재 스크롤 속도를 반환하는 메서드입니다.

#### Parameters

#### Return

| `Vector2` | 초당 픽셀 단위의 스크롤 속도입니다. CanvasPosition이 커지는 방향이 양수입니다. |
| --------- | --------------------------------------------------- |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

local ScrollVelocity = ScrollingFrame:GetScrollVelocity()
print("ScrollVelocity : ", ScrollVelocity)
```

### MoveToSlot

지정한 슬롯 인덱스 위치에 해당하는 UI 요소가 ScrollingFrame의 표시 영역 안으로 들어오도록 스크롤을 이동시키는 메서드입니다.

slotIndex는 계층 순서가 아닌 실제 화면에서의 정렬(표시) 순서를 기준으로 판단합니다.

#### Parameters

| `number` SlotIndex | 스크롤 이동의 기준이 될 슬롯의 표시(정렬) 순서를 나타내는 인덱스 값입니다. |
| ------------------ | ------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame:MoveToSlot(3)
```

### ResetScrollVelocity

진행 중인 관성 스크롤을 즉시 멈추는 메서드입니다.

CanvasPosition은 멈춘 위치에 그대로 유지됩니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame:ResetScrollVelocity()
```

### ScrollToTop

스크롤 위치를 맨 위로 이동시키는 메서드입니다.

ScreenGui에 표시되는 ScrollingFrame에서는 CanvasPosition의 Y 값을 0으로 설정하며, X 값은 유지합니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame")

ScrollingFrame:ScrollToTop()
```

## Events

## See also

{% content-ref url="/pages/K1g0tEWDJhh6a6E4UURk" %}
[GUI](/korean/manual/studio-manual/gui.md)
{% endcontent-ref %}