建立工作室 widget | 文件 - Roblox 創作者中心

Studio 讓您擁有能創建自訂 widget 並將它們作為 Studio 工具和擴展機的使用。這些 widget 會以自訂的視窗/面板在 Studio 中行為，您可以將它們內置在您的界面或將它們作為獨立視窗。

所有 Studio widget 都從 DockWidgetPluginGui 對象開始，這些對象可以用 GuiObjects 填滿，例如文字標籤和按鈕。要創建空的 widget GUI ，請呼叫 Class.Plugin:CreateDockWidgetPluginGui()|CreateDockWidgetP物件ugin

注意 DockWidgetPluginGuiInfo.new() 建造器預期參數在特定順序為：

#	屬性	類型	說明
1	Enum.InitialDockState	枚	一些 Enum.InitialDockState 列表。
2	InitialEnabled	Boolean	初始啟用 (可見) 狀態的 widget GUI。
3	InitialEnabledShouldOverrideRestore	Boolean	如果是，初始啟用的值會覆蓋以前儲存的啟用狀態。
4	FloatingXSize	整數	初始碼頭狀態設為 Enum.InitialDockState.Float 時，GUI 的初始寬度為 Container.InitDockState.Float。
5	FloatingYSize	整數	初始碼頭狀態設為 Enum.InitialDockState.Float 時，GUI 的初始高度為 Container.InitDockState.Float。
6	MinWidth	整數	GUI 的最小寬度，有一些平台專屬變體。
7	MinHeight	整數	GUI 的最低高度，有一些平台特定變體。


-- 創建新 "DockWidgetPluginGuiInfo" 物件
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float,  -- 小部件將在漂浮控制板中初始化
	true,   -- 此部分將會先啟用
	false,  -- 不要覆蓋以前啟用的狀態
	200,    -- 漂浮窗口的預設寬度
	300,    -- 漂浮窗的預設高度
	150,    -- 漂浮窗的最小寬度
	150     -- 漂浮窗的最小高度
)

-- 創建新的控制器 GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- Optional widget title

您不能在遊戲腳本中使用 CreateDockWidgetPluginGui() 功能。您只能從命令欄或插件指令碼令欄中呼叫。

自訂控制器使用者介面

一旦你創建了一小工具 widget，你可以自訂其使用者介面有 GuiObjects ，例如資訊 TextLabels 或互動 ImageButtons 。為例，下列代碼將基本 1> Class.TextButton1> 添加到 GUI 窗口：


-- 創建新的控制器 GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- 可選擇的標題

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 = "Click Me"
testButton.Parent = testWidget

注意，你必須將按鈕親子到同一個方式，在任何體驗屏幕上親子到 Class.GuiObject 到 Class.ScreenGui。

為了幫助您建立一致的、有效的 Studio 部件，Roblox 提供一個 GitHub 儲存庫，其中包含具有標準 "Studio" 外觀和感覺的 GUI 元素。這些包括檢查框、音頻按鈕和輸入字段，其中具有 Studio 風格，並且支持黑暗主題。

變更工作室顏色主題

有效的 Studio 小部件通常會在 Studio 的主題主題設定和動態調整時匹配。例個體、實例，如果開發人員使用黑色主題，則小小工具的背景顏色、圖像和文字標籤應該與 Studio 的原始主題顏色相配。

下列代碼中的追加代碼使用 syncGuiColors() 函數，其初始名稱與一個表的 GUI 對象同步。在功能內，內部的 set


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

自訂滑鼠指針

要改善與 widget 元素的預期互動，您可以將系統-specific 滑鼠指針設置為 GUI 事件，例如 MouseEnter 和 Class.GuiObject


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	將鼠標指针擺在鎖定/禁止的道具目上。
	rbxasset://SystemCursors/Wait	指示有一個進行中的操作。
	rbxasset://SystemCursors/Busy	表示系統忙碌。
	rbxasset://SystemCursors/Cross	將鼠標指针移動到選擇區域上。

注意，這些指针只是估算值 — 實際指针與您的預設操作系統指數器匹配。

收集使用者輸入

Class.abet 和 Class.TextButton 工作正常在 Studio widgets，您可以像您通常會在 Roblox 上做的一樣建立界面。但 Class.UserInputService 和 1> Class.ContextActionService1> 不會工作，因為這些服務期望主要遊戲窗口位於專注模式。

對於一般輸入事件的工作方式之一是創建一個透明 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)

拖曳和放下互動

使用拖曳和放下互動為您的 widget 是一種簡單的方法來改善資料的流量。要創建此互動，您必須定義要拖曳的元素、啟動拖曳、創建放下目標和處理放下操動作。

創建拖曳來源

您可以開始拖動行動，呼叫 Plugin:StartDrag() 當使用者按一下某個 UI 元素上的鼠標按鈕，通常是 TextButton 或 ImageButton 內的拖動按小工具。以下代碼示例創建了單個窗口 widget ，內含一個文字按鈕。


-- 請先創建小部件
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
dragSourceWidget.Title = "Drag Source"

-- 創建一個 TextButton 會啟動拖曳
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Drag me!"
dragButton.Parent = dragSourceWidget

拖動開始

當使用者點擊 TextButton 時，您可以啟動拖曳通過 MouseButton1Down() 事件，發射時間會在使用者按下滑鼠按鈕時立即執行。

內部的連接函數中，確定要拖曳的資料。資料的類型應該在 MimeType 鍵中反射，拖曳內容在 Content 鍵中反射，並且發送器在 2>Send2> ��


local function onButton1Down()
	local dragInfo = {
		Data = "Hello, world",      -- 正在拖曳資料
		MimeType = "text/plain",    -- 描述資料的 MIME 類型
		Sender = "SomeDragSource",  -- 說明資料從哪裡來源
		MouseIcon = "",             -- 可用滑鼠內容
		DragIcon = "",              -- 拖曳時可以在曲標下顯示圖像內容
		HotSpot = Vector2.zero -- 在拖曳圖示中央化鼠標
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

創建一個掉落目標

Class.PluginGui.PluginDragDropped 事件會在用戶在拖動時在窗口上放置鼠標時發生。當這發生時，您需要定義一個放置目標，例如第二個 widget 與 TextLabel 來偵測捕捉。


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
dragTargetWidget.Title = "Drop Target"

-- 這個文字標籤會顯示掉落的內容
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..."
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 – 發射窗口時，當使用者的鼠標離開時。這是一種有用的隱藏“放棄這裡！”的訊息。