스튜디오 위젯

*이 콘텐츠는 AI(베타)를 사용해 번역되었으며, 오류가 있을 수 있습니다. 이 페이지를 영어로 보려면 여기를 클릭하세요.

스튜디오는 사용자 정의 위젯을 생성하고 이를 도구와 확장 기능으로 사용할 수 있는 기능을 제공합니다. 이러한 위젯은 스튜디오 내에서 사용자 정의 창/패널처럼 동작하며, 인터페이스 내부에 도킹하거나 별도의 창으로 떠 있을 수 있습니다.

위젯 UI 만들기

모든 스튜디오 위젯은 DockWidgetPluginGui 객체로 시작되며, 여기에는 텍스트 레이블 및 버튼과 같은 GuiObjects를 채울 수 있습니다. 빈 위젯 GUI를 만들려면, CreateDockWidgetPluginGui() 함수를 호출하고 ID와 DockWidgetPluginGuiInfo 객체를 전달합니다.

DockWidgetPluginGuiInfo.new() 생성자는 매개변수를 특정 순서에 따라 기대하므로 주의해야 합니다:

#속성유형설명
1Enum.InitialDockStateEnumEnum.InitialDockState 열거형 중 하나입니다.
2InitialEnabledBoolean위젯 GUI의 초기 활성화(표시) 상태입니다.
3InitialEnabledShouldOverrideRestoreBoolean참일 경우, InitialEnabled의 값은 이전에 저장된 활성화 상태를 덮어씁니다.
4FloatingXSizeIntegerInitialDockStateEnum.InitialDockState.Float로 설정될 때 GUI의 초기 너비입니다.
5FloatingYSizeIntegerInitialDockStateEnum.InitialDockState.Float로 설정될 때 GUI의 초기 높이입니다.
6MinWidthInteger플랫폼별 변형이 있는 GUI의 최소 너비입니다.
7MinHeightInteger플랫폼별 변형이 있는 GUI의 최소 높이입니다.

-- 새 "DockWidgetPluginGuiInfo" 객체 생성
local widgetInfo = DockWidgetPluginGuiInfo.new(
Enum.InitialDockState.Float, -- 위젯이 플로팅 패널로 초기화됩니다
true, -- 위젯이 초기에는 활성화됩니다
false, -- 이전 활성화 상태를 덮어쓰지 않음
200, -- 플로팅 창의 기본 너비
300, -- 플로팅 창의 기본 높이
150, -- 플로팅 창의 최소 너비
150 -- 플로팅 창의 최소 높이
)
-- 새 위젯 GUI 생성
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "테스트 위젯" -- 선택적 위젯 제목

위젯 UI 사용자화

위젯을 생성한 후에는 GuiObjects를 사용하여 사용자 인터페이스를 사용자화할 수 있습니다. 예를 들어, 다음 코드는 GUI 창에 기본적인 TextButton을 추가합니다:


-- 새 위젯 GUI 생성
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "테스트 위젯" -- 선택적 위젯 제목
local testButton = Instance.new("TextButton")
testButton.BorderSizePixel = 0
testButton.TextSize = 20
testButton.TextColor3 = Color3.new(1,0.2,0.4)
testButton.AnchorPoint = Vector2.new(0.5,0.5)
testButton.Size = UDim2.new(1,0,1,0)
testButton.Position = UDim2.new(0.5,0,0.5,0)
testButton.SizeConstraint = Enum.SizeConstraint.RelativeYY
testButton.Text = "클릭하세요"
testButton.Parent = testWidget

스튜디오 색상 테마 변경

효과적인 스튜디오 위젯은 이상적으로 스튜디오 테마 설정에 맞추어져야 하며, 테마가 변경될 때 동적으로 조정되어야 합니다. 예를 들어, 개발자가 다크 테마를 사용하는 경우, 위젯의 배경 색상, 이미지 및 텍스트 레이블은 스튜디오의 기본 테마 색상과 잘 어울려야 합니다.

다음 코드 추가는 GUI 객체의 배열을 동기화하기 위해 처음에 호출되는 syncGuiColors() 함수를 사용합니다. 함수 내부에 있는 중첩 setColors() 함수는 객체를 반복하며 GetColor()Enum.StudioStyleGuideColor 열거형을 사용해 특정 측면을 동기화합니다. 이 setColors() 함수는 스튜디오 테마와 동기화하기 위해 즉시 실행되며, 이후 테마 변경을 감지하기 위해 ThemeChanged 이벤트와 연결됩니다.


testButton.Parent = testWidget
local function syncGuiColors(objects)
local function setColors()
for _, guiObject in objects do
-- 배경 색상 동기화
guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
-- 텍스트 색상 동기화
guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
end
end
-- 초기 색상 동기화를 위해 'setColors()' 함수 실행
setColors()
-- 'ThemeChanged' 이벤트를 'setColors()' 함수와 연결
settings().Studio.ThemeChanged:Connect(setColors)
end
-- 제공된 객체의 색상 동기화를 위해 'syncGuiColors()' 함수 실행
syncGuiColors({testButton})

마우스 커서 사용자화

위젯 요소와의 상호작용을 개선하기 위해, GUI 이벤트인 MouseEnterMouseLeave에 시스템 특화 마우스 커서를 설정할 수 있습니다. 다음 코드는 testButtonMouseEnterMouseLeave 이벤트에 함수를 연결하여 마우스 커서를 변경하는 방법을 보여줍니다:


local function setCursor(cursorAsset)
plugin:GetMouse().Icon = cursorAsset
end
testButton.MouseEnter:Connect(function()
setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
setCursor("")
end)

다음 표는 마우스 커서와 그 잠재적인 사용 사례 목록을 참조합니다:

마우스 커서 아이콘자산사용 사례
rbxasset://SystemCursors/Arrow기본 클릭 및 선택.
rbxasset://SystemCursors/PointingHand활성 링크/버튼 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/OpenHand드래그 가능한 항목 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/ClosedHand항목이 드래그되는 경우.
rbxasset://SystemCursors/IBeam텍스트 필드 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SizeNS수직 크기 조정 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SizeEW수평 크기 조정 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SizeNESW모서리 크기 조정 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SizeNWSE모서리 크기 조정 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SizeAll다방향 크기 조정 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SplitNS수직 "분할" 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/SplitEW수평 "분할" 핸들 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/Forbidden잠겨있거나 Forbidden된 항목 위에 마우스가 올려진 경우.
rbxasset://SystemCursors/Wait작업이 진행 중임을 나타냅니다.
rbxasset://SystemCursors/Busy시스템이 바쁘다는 것을 나타냅니다.
rbxasset://SystemCursors/Cross정확한 선택 영역 위에 마우스가 올려진 경우.

사용자 입력 수집

TextBoxTextButton과 같은 UI 요소는 스튜디오 위젯에서 정상적으로 작동하며, Roblox에서 일반적으로 만들던 것처럼 인터페이스를 만들 수 있습니다. 그러나 UserInputService는 작동하지 않는데, 이는 이러한 서비스들이 기본 경험 창에 포커스가 있어야 하기 때문입니다.

일반 입력 이벤트에 대한 해결 방법은 투명한 Frame을 생성하여 전체 화면을 덮는 것입니다. 다음 코드 샘플은 프레임을 생성하며, 사용자가 프레임을 클릭하면 GuiObject.InputBegan 이벤트가 프레임에서 키보드 입력을 캡처합니다:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1 -- 프레임을 숨깁니다
frame.Size = UDim2.new(1, 0, 1, 0) -- 화면을 덮습니다
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
-- 입력 객체를 여기에 처리합니다, 예를 들어 키 입력을 감지합니다
end
frame.InputBegan:Connect(onInputBegan)

드래그 앤 드롭 상호작용

위젯에 드래그 앤 드롭 상호작용을 사용하는 것은 데이터 흐름을 개선하는 간단한 방법입니다. 이러한 상호작용을 생성하려면 드래그할 요소를 정의하고, 드래그를 시작하고, 드롭 대상을 만들고, 드롭 작업을 처리해야 합니다.

드래그 소스 만들기

사용자가 UI 요소에서 마우스 버튼을 누르면 Plugin:StartDrag()를 호출하여 드래그 작업을 시작할 수 있습니다. 일반적으로 위젯 내의 TextButton 또는 ImageButton에서 수행됩니다. 다음 코드 샘플은 내부에 텍스트 버튼이 있는 단일 창 위젯을 생성합니다.


-- 먼저 위젯 생성
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("드래그 소스", widgetInfo)
dragSourceWidget.Title = "드래그 소스"
-- 드래그를 시작할 TextButton 생성
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "나를 드래그하세요!"
dragButton.Parent = dragSourceWidget

드래그 시작하기

사용자가 TextButton을 클릭하면, MouseButton1Down() 이벤트를 통해 드래그를 시작할 수 있습니다. 이는 사용자가 마우스 버튼을 누르는 즉시 발생합니다.

연결된 함수 내에서 드래그할 데이터를 결정합니다. 데이터의 유형MimeType 키에 반영되어야 하며, 드래그의 내용Data 키에 반영되어야 하고, 보내는 사람Sender 키에 설명되어야 합니다. 더 많은 세부 정보는 Plugin:StartDrag() 페이지를 참조하십시오.


local function onButton1Down()
local dragInfo = {
Data = "안녕하세요, 세계", -- 드래그되는 데이터
MimeType = "text/plain", -- 데이터의 MIME 유형을 설명합니다
Sender = "SomeDragSource", -- 데이터가 어디에서 originating되었는지 설명합니다
MouseIcon = "", -- 커서에 사용할 이미지 콘텐츠
DragIcon = "", -- 드래그 중 커서 아래에 렌더링할 이미지 콘텐츠
HotSpot = Vector2.zero -- DragIcon에서 커서를 중앙에 둘 위치
}
plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)

드롭 대상 만들기

사용자가 드래그 중 창에서 마우스를 놓으면 PluginGui.PluginDragDropped 이벤트가 발생합니다. 이때 TextLabel이 있는 두 번째 위젯과 같은 드롭 대상을 정의해야 합니다.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("드롭 대상", widgetInfo)
dragTargetWidget.Title = "드롭 대상"
-- 이 TextLabel은 드롭된 내용을 표시합니다
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "여기에 드롭하세요..."
textLabel.Parent = dragTargetWidget

드롭 작업 처리하기

드롭 대상을 만든 후 드롭 대상 위젯에서 PluginGui.PluginDragDropped 이벤트를 연결하십시오:


local function onDragDrop(dragData)
print("PluginDragDropped")
if dragData.MimeType == "text/plain" then
textLabel.Text = dragData.Data
else
textLabel.Text = dragData.MimeType
end
end
dragTargetWidget.PluginDragDropped:Connect(onDragDrop)

드래그가 진행되는 동안 사용자가 마우스를 위젯 위로 이동하면 다음 세 가지 이벤트가 발생합니다:

  • PluginDragEntered – 사용자가 창 위에 마우스를 올릴 때 발생합니다
  • PluginDragMoved – 사용자가 창 위로 마우스를 이동할 때 반복적으로 발생합니다. 이는 "여기에 드롭하세요!" 메시지를 표시하는 데 유용합니다.
  • PluginDragLeft – 사용자의 커서가 창을 떠날 때 발생합니다. 이는 "여기에 드롭하세요!" 메시지를 숨기는 데 유용합니다.
©2026 Roblox Corporation. Roblox 및 Roblox 로고, 'Powering Imagination'은 미국 및 기타 국가 내 당사의 등록 및 미등록 상표입니다.