建立工作室 widgets

工作室賦予您創建自訂 widgets 的能力，並將它們用作 Studio 工具和擴展。這些 widget 在 Studio 中行為像自訂窗口/面板,您可以將它們靠近您的介面或將它們作為獨立窗口漂浮。

所有工作室 widget 都會開始為 DockWidgetPluginGui 個對象，您可以使用 GuiObjects 填充，例如文字標籤和按鈕。要創建一個空的 widget GUI，請呼叫 CreateDockWidgetPluginGui() 函數，傳入一個 ID 和一個 DockWidgetPluginGuiInfo 對物件。

注意 DockWidgetPluginGuiInfo.new() 建造器期望其參數在特定順序中如下：

#	屬性	類型	說明
1	Enum.InitialDockState	枚列	一個 Enum.InitialDockState 列表。
2	InitialEnabled	Boolean 值	widget GUI的初始啟用(可見)狀態。
3	InitialEnabledShouldOverrideRestore	Boolean 值	如果真實，則初始啟用的值會覆蓋先前儲存的啟用狀態。
4	FloatingXSize	整數	當 InitialDockState 設為 Enum.InitialDockState.Float 時，GUI 的初始寬度。
5	FloatingYSize	整數	當 InitialDockState 設為 Enum.InitialDockState.Float 時，GUI 的初始高度。
6	MinWidth	整數	最小 GUI 寬度，並有一些平台特異變化。
7	MinHeight	整數	最低 GUI 高度，並有一些平台特異變化。


-- 創建新的「DockWidgetPluginGuiInfo」物件
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float, -- Widget 將在懸浮面板中初始化
	true,   --  widget 將最初啟用
	false,  -- 不要覆蓋以前啟用的狀態
	200,    -- 懸浮窗口的預設寬度
	300,    -- 懸浮窗口的預設高度
	150,    -- 懸浮窗口的最小寬度
	150     -- 懸浮窗口的最低高度
)

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

你無法在遊戲腳本中使用 CreateDockWidgetPluginGui() 功能。你只能從指令欄或插件指令碼本中呼叫它。

一旦您創建了一個 widget，您可以使用 GuiObjects 例如說明性 TextLabels 或互動 ImageButtons 來自定義其用戶介面。例如，下面的代碼會將基本的 TextButton 添加到 GUI 窗口：


-- 創建新的 widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- 可選擇的 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

請注意，你必須將按鈕傳送到體驗中的 widget ，以相同的方式傳送任何經驗內的屏幕GuiObject到ScreenGui。

為了幫助您建立一致且有效的 Studio 工具，Roblox 提供了一個 GitHub 存檔，包含具有標準「Studio」外觀和感覺的 GUI 元素。這包括檢查框、收音按鈕和輸入欄，其中都有 Studio 風格，且全部都支持黑暗主題。

變更工作室顏色主題

有效的 Studio 工具理想地匹配 Studio 主題設置，並在主題變更時動態調整。例個體、實例，如果開發者使用黑暗主題，則應用小工具的背景顏色、圖像和文字標籤應與 Studio 的原生主題顏色一起看起來很好。

以下代碼添加使用初始以同步的GUI對象表中呼叫的syncGuiColors()功能。在功能內，嵌套的功能循環通過對象並使用枚列同步特定方面的它們。這個 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()
	-- 將「主題變更」事件連接到「setColors()」函數
	settings().Studio.ThemeChanged:Connect(setColors)
end

-- 執行「syncGuiColors()」功能以同步提供的對象的顏色
syncGuiColors({testButton})

自訂滑鼠指標

為了改善與 widget 元素的預期互動，您可以將系統特定的滑鼠指針設置為 GUI 事件，例如 MouseEnter 和 MouseLeave。以下代碼展示如何將函數連接到 MouseEnter 和 MouseLeave 事件的 testButton 以更改鼠標指針：


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	將鼠標懸停在精確選擇區域上。

請注意，這些鼠標外觀只是一個近似值 — 實際的鼠標與您的預設操作系統鼠標相匹配。

收集使用者輸入

UI元素，例如TextBox和TextButton在Studio工具中正常工作，您可以像通常在Roblox上一樣構建介面。但是，UserInputService 和 ContextActionService 無法運作，因為這些服務期望主遊戲窗口處於聚焦狀態。

一個通用輸入事件的工作環境是創建透明的 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() 來啟動拖動操作，通常是在Widget中的TextButton或ImageButton內。以下代碼示例創建了一個內含文字按鈕的單獨窗口 widget。


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

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

啟動拖動

當使用者單擊 TextButton 時，您可以通過啟動 MouseButton1Down() 事件來啟動拖動，該事件會在使用者按下滑鼠按鈕時發生。

在連接的功能中，決定要拖動的資料。數據的類型應反映在鍵中，拖動的內容應反映在鍵中，發送者的應在鍵中描述自己。請參閱Plugin:StartDrag()頁面了解更多詳情。


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)

創建掉落目標

在拖動期間，用戶在窗口上釋放鼠標時發生 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

處理掉落行動作

創建了掉落目標後，連接掉落目標 widget 上的 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 – 在使用者的鼠標離開窗口時發生。這有助於隱藏「在此處放置！」訊息。

創建 widget 介面

自訂 widget 介面