Studio 小工具

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

Studio 給予您創造自訂 小工具 的能力,並將它們用作工具和擴展。這些小工具在 Studio 中的行為就像自訂視窗/面板,您可以將它們停靠在您的介面內部,或者作為獨立視窗浮動。

創建小工具 UI

所有 Studio 小工具都以 DockWidgetPluginGui 物件開始,您可以填充 GuiObjects,例如文字標籤和按鈕。要創建一個空的小工具 GUI,請調用 CreateDockWidgetPluginGui() 函數,傳遞一個 ID 和一個 DockWidgetPluginGuiInfo 物件。

請注意 DockWidgetPluginGuiInfo.new() 建構函數對其參數有 特定的順序,如下所示:

#屬性類型描述
1Enum.InitialDockStateEnumEnum.InitialDockState 列舉中的一個。
2InitialEnabled布林值小工具 GUI 的初始啟用(可見)狀態。
3InitialEnabledShouldOverrideRestore布林值如果為真,InitialEnabled 的值將覆蓋之前保存的啟用狀態。
4FloatingXSize整數InitialDockState 設定為 Enum.InitialDockState.Float 時 GUI 的初始寬度。
5FloatingYSize整數InitialDockState 設定為 Enum.InitialDockState.Float 時 GUI 的初始高度。
6MinWidth整數GUI 的最小寬度,具有一些平台特定的變異。
7MinHeight整數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 自訂其使用者介面,例如信息性 TextLabels 或互動式 ImageButtons。例如,以下代碼將基礎的 TextButton 添加到 GUI 視窗中:


-- 創建新的小工具 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

更改 Studio 顏色主題

有效的 Studio 小工具應理想地與 Studio 主題 設定相匹配,並在主題變更時動態調整。例如,如果開發人員使用的是黑暗主題,則小工具的背景顏色、圖像和文字標籤應與 Studio 的原生主題顏色搭配良好。

以下代碼添加了 syncGuiColors() 函數,該函數最初與需要同步的 GUI 物件表一起調用。在函數內部,嵌套的 setColors() 函數循環遍歷物件並使用 GetColor()Enum.StudioStyleGuideColor 列舉同步它們的特定層面。此 setColors() 函數立即運行以同步 Studio 主題,然後它連接到 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懸停於鎖定/禁止的項目上。
rbxasset://SystemCursors/Wait指示操作正在進行中。
rbxasset://SystemCursors/Busy指示系統正在忙碌。
rbxasset://SystemCursors/Cross懸停於精確選擇區域上。

收集用戶輸入

UI 元素如 TextBoxTextButton 在 Studio 小工具中正常運作,您可以像在 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() 開始拖動操作,通常是在小工具中的 TextButtonImageButton 上。以下代碼示例創建了一個單窗口小工具,並在其中放置了一個文本按鈕。


-- 首先創建小工具
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 = "某個拖動源", -- 描述數據的來源
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 是我們在美國及其他國家地區的部分註冊與未註冊商標。