Widget dello Studio

*Questo contenuto è tradotto usando AI (Beta) e potrebbe contenere errori. Per visualizzare questa pagina in inglese, clicca qui.

Lo Studio ti offre la possibilità di creare widget personalizzati e utilizzarli come strumenti ed estensioni. Questi widget si comportano come finestre/pannelli personalizzati nello Studio e puoi ancorarli all'interno della tua interfaccia o farli galleggiare come finestre separate.

Crea interfacce per i widget

Tutti i widget dello Studio iniziano come oggetti DockWidgetPluginGui che puoi riempire con GuiObjects, come etichette di testo e pulsanti. Per creare una GUI di widget vuota, chiama la funzione CreateDockWidgetPluginGui(), passando un ID e un oggetto DockWidgetPluginGuiInfo.

Nota che il costruttore DockWidgetPluginGuiInfo.new() si aspetta i suoi parametri in un ordine specifico come segue:

#ProprietàTipoDescrizione
1Enum.InitialDockStateEnumUna delle enumerazioni Enum.InitialDockState.
2InitialEnabledBooleanoLo stato iniziale abilitato (visibile) della GUI del widget.
3InitialEnabledShouldOverrideRestoreBooleanoSe vero, il valore di InitialEnabled sovrascrive lo stato abilitato salvato in precedenza.
4FloatingXSizeInteroLa larghezza iniziale della GUI quando InitialDockState è impostato su Enum.InitialDockState.Float.
5FloatingYSizeInteroAltezza iniziale della GUI quando InitialDockState è impostato su Enum.InitialDockState.Float.
6MinWidthInteroLa larghezza minima della GUI, con alcune variazioni specifiche della piattaforma.
7MinHeightInteroAltezza minima della GUI, con alcune variazioni specifiche della piattaforma.

-- Crea un nuovo oggetto "DockWidgetPluginGuiInfo"
local widgetInfo = DockWidgetPluginGuiInfo.new(
Enum.InitialDockState.Float, -- Il widget verrà inizializzato in un pannello galleggiante
true, -- Il widget sarà inizialmente abilitato
false, -- Non sovrascrivere lo stato abilitato precedente
200, -- Larghezza predefinita della finestra galleggiante
300, -- Altezza predefinita della finestra galleggiante
150, -- Larghezza minima della finestra galleggiante
150 -- Altezza minima della finestra galleggiante
)
-- Crea una nuova GUI per il widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget di Test" -- Titolo opzionale del widget

Personalizza l'interfaccia del widget

Una volta creato un widget, puoi personalizzare la sua interfaccia utente con GuiObjects, come informative TextLabels o interattivi ImageButtons. Ad esempio, il seguente codice aggiunge un semplice TextButton alla finestra della GUI:


-- Crea una nuova GUI per il widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget di Test" -- Titolo opzionale del 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 = "Cliccami"
testButton.Parent = testWidget

Cambia i temi di colore dello Studio

Widget dello Studio efficaci idealmente corrispondono all'impostazione del tema dello Studio e si adattano dinamicamente quando il tema cambia. Ad esempio, se un sviluppatore sta utilizzando il tema scuro, il colore di sfondo del widget, le immagini e le etichette di testo dovrebbero apparire gradevoli in combinazione con i colori del tema nativo dello Studio.

Il seguente codice aggiuntivo utilizza una funzione syncGuiColors() che viene inizialmente chiamata insieme a un elenco di oggetti GUI da sincronizzare. All'interno della funzione, una funzione annidata setColors() scorre attraverso gli oggetti e sincronizza specifici aspetti di essi utilizzando GetColor() con le enumerazioni Enum.StudioStyleGuideColor. Questa funzione setColors() viene eseguita immediatamente per sincronizzare il tema dello Studio, poi è connessa all'evento ThemeChanged per rilevare futuri cambiamenti di tema.


testButton.Parent = testWidget
local function syncGuiColors(objects)
local function setColors()
for _, guiObject in objects do
-- Sincronizza il colore di sfondo
guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
-- Sincronizza il colore del testo
guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
end
end
-- Esegui la funzione 'setColors()' per sincronizzare inizialmente i colori
setColors()
-- Collega l'evento 'ThemeChanged' alla funzione 'setColors()'
settings().Studio.ThemeChanged:Connect(setColors)
end
-- Esegui la funzione 'syncGuiColors()' per sincronizzare i colori degli oggetti forniti
syncGuiColors({testButton})

Personalizza i cursori del mouse

Per migliorare l'interazione attesa con gli elementi del widget, puoi impostare cursori del mouse specifici per il sistema sugli eventi GUI, come MouseEnter e MouseLeave. Il seguente codice dimostra come connettere una funzione agli eventi MouseEnter e MouseLeave del testButton per cambiare il cursore del mouse:


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

Fai riferimento alla seguente tabella per un elenco di cursori del mouse e dei loro potenziali casi d'uso:

Icona del cursore del mouseAssetCaso d'uso
rbxasset://SystemCursors/ArrowSelezione e clic predefiniti.
rbxasset://SystemCursors/PointingHandPassando sopra un link/pulsante attivo.
rbxasset://SystemCursors/OpenHandPassando sopra un elemento trascinabile.
rbxasset://SystemCursors/ClosedHandTrascinando un elemento.
rbxasset://SystemCursors/IBeamPassando sopra un campo di testo.
rbxasset://SystemCursors/SizeNSPassando sopra un'impugnatura di ridimensionamento verticale.
rbxasset://SystemCursors/SizeEWPassando sopra un'impugnatura di ridimensionamento orizzontale.
rbxasset://SystemCursors/SizeNESWPassando sopra un'impugnatura di ridimensionamento angolare.
rbxasset://SystemCursors/SizeNWSEPassando sopra un'impugnatura di ridimensionamento angolare.
rbxasset://SystemCursors/SizeAllPassando sopra un'impugnatura di ridimensionamento multidirezionale.
rbxasset://SystemCursors/SplitNSPassando sopra un'impugnatura di "divisione" verticale.
rbxasset://SystemCursors/SplitEWPassando sopra un'impugnatura di "divisione" orizzontale.
rbxasset://SystemCursors/ForbiddenPassando sopra un elemento bloccato/forbidden.
rbxasset://SystemCursors/WaitIndicando che un'azione è in corso.
rbxasset://SystemCursors/Busy Indicando che il sistema è occupato.
rbxasset://SystemCursors/CrossPassando sopra un'area di selezione puntiforme.

Raccogli input degli utenti

Elementi UI come TextBox e TextButton funzionano normalmente nei widget dello Studio e puoi costruire interfacce proprio come faresti normalmente su Roblox. Tuttavia, UserInputService non funziona poiché questi servizi si aspettano che la finestra principale dell'esperienza sia a fuoco.

Una soluzione per gli eventi di input generici è creare un Frame trasparente e sovrapporlo all'intero schermo. Il seguente campione di codice crea un frame e quando l'utente fa clic sul frame, l'evento GuiObject.InputBegan cattura l'input da tastiera sul frame fino a quando l'utente non fa clic altrove:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1 -- Nascondi il frame
frame.Size = UDim2.new(1, 0, 1, 0) -- Copri lo schermo
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
-- Elabora l'oggetto di input qui, ad esempio rileva i tasti premuti
end
frame.InputBegan:Connect(onInputBegan)

Interazione di trascinamento e rilascio

Utilizzare interazioni di trascinamento e rilascio per i tuoi widget è un modo semplice per migliorare il flusso di dati. Per creare questa interazione, devi definire l'elemento da trascinare, avviare il trascinamento, creare un obiettivo di rilascio e elaborare l'azione di rilascio.

Crea sorgente di trascinamento

Puoi avviare un'azione di trascinamento chiamando Plugin:StartDrag() quando l'utente preme un pulsante del mouse su un qualche elemento UI, tipicamente un TextButton o un ImageButton all'interno di un widget. Il seguente campione di codice crea un widget a finestra singola con un pulsante di testo al suo interno.


-- Crea prima il widget
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Sorgente di Trascinamento", widgetInfo)
dragSourceWidget.Title = "Sorgente di Trascinamento"
-- Crea un TextButton che avvierà il trascinamento
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Trascinami!"
dragButton.Parent = dragSourceWidget

Iniziare il trascinamento

Quando l'utente fa clic sul TextButton, puoi avviare il trascinamento attraverso l'evento MouseButton1Down() che si attiva non appena l'utente preme il pulsante del mouse.

All'interno della funzione connessa, determina i dati da trascinare. Il tipo dei dati dovrebbe essere riflesso nella chiave MimeType, il contenuto del trascinamento dovrebbe essere riflesso all'interno della chiave Data, e il mittente dovrebbe descrivere se stesso nella chiave Sender. Vedi la pagina Plugin:StartDrag() per ulteriori dettagli.


local function onButton1Down()
local dragInfo = {
Data = "Ciao, mondo", -- I dati da trascinare
MimeType = "text/plain", -- Descrive il tipo MIME dei dati
Sender = "SomeDragSource", -- Descrive da dove provengono i dati
MouseIcon = "", -- Contenuto dell'immagine da usare per il cursore
DragIcon = "", -- Contenuto dell'immagine da visualizzare sotto il cursore durante il trascinamento
HotSpot = Vector2.zero -- Dove centrare il cursore sull'icona di trascinamento
}
plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)

Crea obiettivo di rilascio

L'evento PluginGui.PluginDragDropped si attiva quando l'utente rilascia il mouse su una finestra durante un trascinamento. Quando si verifica questo evento, devi definire un obiettivo di rilascio come un secondo widget con un TextLabel per rilevare i rilasci.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Obiettivo di Rilascio", widgetInfo)
dragTargetWidget.Title = "Obiettivo di Rilascio"
-- Questa TextLabel visualizzerà ciò che è stato rilasciato
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Rilascia qui..."
textLabel.Parent = dragTargetWidget

Elaborare l'azione di rilascio

Dopo aver creato un obiettivo di rilascio, collega l'evento PluginGui.PluginDragDropped al widget dell'obiettivo di rilascio:


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)

Mentre un trascinamento è ancora in corso, questi tre eventi si attivano mentre l'utente muove il mouse sopra un widget:

  • PluginDragEntered – si attiva quando l'utente passa il mouse sopra una finestra
  • PluginDragMoved – si attiva ripetutamente mentre l'utente muove il mouse sopra una finestra. Questo è utile per mostrare un messaggio "Rilascia qui!".
  • PluginDragLeft – si attiva quando il cursore dell'utente esce da una finestra. Questo è utile per nascondere un messaggio "Rilascia qui!".
© 2026 Roblox Corporation. Roblox, il logo Roblox e Powering Imagination sono tra i nostri marchi registrati e non registrati negli Stati Uniti. e altri paesi.