Stile UI | Documentazione - Roblox Hub Creatori

Lo stile UI è una soluzione di Roblox per i fogli di stile, simile al CSS, che ti consente di dichiarare e applicare globalmente le sovrascritture delle proprietà delle istanze UI. Questo supporto a livello di motore è la base per il Style Editor e il pipeline dei token end-to-end.

Concetti

Le regole di stile (parte di un StyleSheet) si applicano a ogni istanza che corrisponde alla definizione Selector della regola per abbinare caratteristiche come nome della classe, nome dell'istanza e relazioni gerarchiche. Vedi la documentazione Selector per dettagli.

I token di stile, definiti tramite attributi di un StyleSheet di token, rappresentano variabili di proprietà UI che possono essere utilizzate attraverso stili e componenti, ad esempio un colore comune per un Frame.BackgroundColor3, TextLabel.TextColor3, e UIStroke.Color. I token sono comparabili alle variabili del CSS.

I temi di stile, configurati tramite attributi di un StyleSheet di tema, consistono in insiemi di specifici token che possono essere scambiati, ad esempio token di colore che definiscono un tema "chiaro" e "scuro". I temi correlati devono avere lo stesso insieme di token per funzionare correttamente.

Le query di stile ti permettono di applicare stili condizionalmente in base al contesto o all'ambiente dell'UI. Questi sono comparabili alle query di contenitore e query di media del CSS, che consentono all'UI di adattarsi alla dimensione dello schermo, ai tipi di input o alle impostazioni di accessibilità dell'utente.

Propagazione delle regole

Un'istanza di StyleLink collega un StyleSheet e le sue regole associate a un ScreenGui padre e a tutti i GuiObjects al suo interno. Solo un StyleSheet può applicarsi a un dato albero.

Definizioni dei selettori

A un alto livello, l'abbinamento e la modifica delle istanze tramite la definizione Selector di una regola operano attraverso:

Selettori di classe di Roblox che mirano a tutte le istanze della data classe GuiObject, ad esempio Frame, ImageLabel, TextButton, ecc.
Tag di istanza applicati a oggetti UI specifici tramite CollectionService.
Selezione del nome dell'istanza in base al valore del Instance.Name dell'oggetto UI.
Modificatori di istanza, simili ai pseudo-elementi del CSS, applicati tramite UIComponents fantasma come UICorner o UIStroke.
Selettori di stato di GuiObject, simili ai selettori di pseudo-classe del CSS, che corrispondono a uno dei quattro valori dell'enum GuiState, come Hover.
Selettori di query di Roblox, simili alle query di contenitore e media del CSS, che usano il prefisso @ per applicare stili solo mentre un'istanza o pseudo‑istanza StyleQuery con lo stesso nome è attiva.

Il seguente setup mostra come i token di dimensione e colore, un tema e un selettore di classe di "Frame" producono un Frame magenta di dimensione 200×200 pixel.

Codice Equivalente

Selettore di classe UI
local CollectionService = game:GetService("CollectionService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local screenGui = script.Parent

-- Token
local tokens = Instance.new("StyleSheet")
tokens.Name = "Tokens"
tokens.Parent = ReplicatedStorage
tokens:SetAttribute("SquareS", UDim2.fromOffset(50, 50))
tokens:SetAttribute("SquareM", UDim2.fromOffset(100, 100))
tokens:SetAttribute("SquareL", UDim2.fromOffset(200, 200))
tokens:SetAttribute("Fit", UDim2.fromScale(1, 1))
tokens:SetAttribute("Magenta", Color3.fromHex("FF0099"))
tokens:SetAttribute("Gold", Color3.fromHex("FFCC00"))
tokens:SetAttribute("Aqua", Color3.fromHex("0093F0"))

-- TemaA
local themeA = Instance.new("StyleSheet")
themeA.Name = "ThemeA"
themeA.Parent = ReplicatedStorage
local tokensDerive = Instance.new("StyleDerive")
tokensDerive.StyleSheet = tokens  -- Deriva dai token globali
tokensDerive.Parent = themeA
themeA:SetAttribute("FrameSize", "$SquareM")
themeA:SetAttribute("FrameColor", "$Aqua")

-- TemaB
local themeB = Instance.new("StyleSheet")
themeB.Name = "ThemeB"
themeB.Parent = ReplicatedStorage
local tokensDerive = Instance.new("StyleDerive")
tokensDerive.StyleSheet = tokens  -- Deriva dai token globali
tokensDerive.Parent = themeB
themeB:SetAttribute("FrameSize", "$SquareL")
themeB:SetAttribute("FrameColor", "$Magenta")

-- DesignSheet
local designSheet = Instance.new("StyleSheet")
designSheet.Name = "DesignSheet"
designSheet.Parent = ReplicatedStorage
local themeDerive = Instance.new("StyleDerive")
themeDerive.StyleSheet = themeB  -- Deriva da ThemeB
themeDerive.Parent = designSheet

-- Collega DesignSheet a ScreenGui
local styleLink = Instance.new("StyleLink")
styleLink.StyleSheet = designSheet
styleLink.Parent = screenGui

-- Configura la regola
local rule = Instance.new("StyleRule")
rule.Selector = "Frame"  -- Selettore di classe
rule.Parent = designSheet

-- Imposta le proprietà della regola
rule:SetProperties({
	["BackgroundColor3"] = "$FrameColor",
	["Size"] = "$FrameSize",
	["BorderSizePixel"] = 0
})

local frame = Instance.new("Frame")
frame.Parent = screenGui

Proprietà modificate

Le proprietà delle istanze influenzate dallo stile sono contrassegnate con un ⚠ nella finestra Proprietà, e passando il mouse su una proprietà interessata si vedrà quale stile la sta influenzando. Ad esempio, se una regola di stile dice a un Frame contrassegnato di utilizzare un AnchorPoint di 0.5, 0.5, quella proprietà dell'oggetto mostrerà il valore predefinito di 0, 0 ma il suo effettivo AnchorPoint utilizzerà il valore stilizzato della regola.

Quando un valore di proprietà predefinito o stilizzato viene ulteriormente modificato per un oggetto UI specifico, diventa grassetto per indicare un valore sovrascritto. Ad esempio — assumendo un AnchorPoint predefinito di 0, 0 — impostare quella proprietà a 1, 1 per un'istanza specifica rivela un'override in grassetto:

Per qualsiasi valore di proprietà sovrascritto, puoi fare clic destro su di esso nella finestra Proprietà e selezionare Reimposta su Predefinito per ripristinarlo al valore stilizzato, o al valore di proprietà predefinito se non è stato stilizzato.