UI-Stilgestaltung | Dokumentation

UI-Stilgestaltung ist eine Roblox-Lösung für Stylesheets, ähnlich wie CSS, die es Ihnen ermöglicht, Überschreibungen von UI-Instanzeigenschaften zu deklarieren und global anzuwenden. Diese Unterstützung auf Engine-Ebene bildet die Grundlage für den Style Editor und die End-to-End-Token-Pipeline.

Konzepte

Stil regeln (Teil eines StyleSheet) gelten für jede Instanz, die der Selector-Definition der Regel entspricht, um Merkmale wie Klassennamen, Instanznamen und Hierarchiebeziehungen zu entsprechen. Weitere Einzelheiten finden Sie in der Dokumentation zu Selector.

Stil tokens, die über Attribute eines Token StyleSheet definiert sind, stellen Variablen für UI-Eigenschaften dar, die in Stilen und Komponenten verwendet werden können, z. B. eine gemeinsame Farbe für ein Frame.BackgroundColor3, TextLabel.TextColor3 und UIStroke.Color. Tokens sind vergleichbar mit CSS Variablen.

Stil themen, die über Attribute eines Themen-StyleSheet konfiguriert sind, bestehen aus Sets spezifischer Tokens, die ausgetauscht werden können, z. B. Farbtokens, die ein "helles" und "dunkles" Thema definieren. Verwandte Themen müssen dasselbe Set an Tokens haben, um korrekt zu funktionieren.

Stil abfragen ermöglichen es Ihnen, Stile bedingt basierend auf dem Kontext oder der Umgebung der UI anzuwenden. Diese sind vergleichbar mit CSS Container- und Medienabfragen, die es der UI ermöglichen, sich an die Bildschirmgröße, Eingabetypen oder Benutzereinstellungen zur Barrierefreiheit anzupassen.

Regelweitergabe

Eine StyleLink-Instanz verknüpft ein StyleSheet und seine zugehörigen Regeln mit einem übergeordneten ScreenGui und allen GuiObjects, die darin enthalten sind. Nur ein StyleSheet kann auf einen bestimmten Baum angewendet werden.

Selector-Definitionen

Auf einer hohen Ebene erfolgt die Übereinstimmung und Modifikation von Instanzen über die Selector-Definition einer Regel:

Roblox klassen-Selektoren, die alle Instanzen einer bestimmten GuiObject-Klasse ansprechen, z. B. Frame, ImageLabel, TextButton usw.
Instanz tags, die auf bestimmten UI-Objekten über CollectionService angewendet werden.
Auswahl anhand des Instanz namen gemäß dem Wert des Instance.Name der UI-Instanz.
Instanz modifizierer, ähnlich wie CSS-Pseudo-Elemente, die über phantomhafte UIComponents wie UICorner oder UIStroke angewendet werden.
GuiObject Zustands-Selektoren, ähnlich wie CSS-Pseudo-Klassen Selektoren, die einem der vier GuiState-Wertenum-Werte wie Hover entsprechen.
Roblox abfrage-Selektoren, ähnlich wie CSS-Container- und Medienabfragen, die das @-Präfix verwenden, um Stile nur anzuwenden, während eine StyleQuery-Instanz oder Pseudo-Instanz mit demselben Namen aktiv ist.

Die folgende Konfiguration zeigt, wie Größen- und Farbtokens, ein Thema und ein Klassen-Selektor von "Frame" einen magentafarbenen Frame mit der Größe 200×200 Pixel erzeugen.

Code-Äquivalent

UI Klassen-Selektor
local CollectionService = game:GetService("CollectionService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local screenGui = script.Parent

-- Tokens
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"))

-- ThemeA
local themeA = Instance.new("StyleSheet")
themeA.Name = "ThemeA"
themeA.Parent = ReplicatedStorage
local tokensDerive = Instance.new("StyleDerive")
tokensDerive.StyleSheet = tokens  -- Globale Tokens ableiten
tokensDerive.Parent = themeA
themeA:SetAttribute("FrameSize", "$SquareM")
themeA:SetAttribute("FrameColor", "$Aqua")

-- ThemeB
local themeB = Instance.new("StyleSheet")
themeB.Name = "ThemeB"
themeB.Parent = ReplicatedStorage
local tokensDerive = Instance.new("StyleDerive")
tokensDerive.StyleSheet = tokens  -- Globale Tokens ableiten
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  -- Von ThemeB ableiten
themeDerive.Parent = designSheet

-- DesignSheet mit ScreenGui verknüpfen
local styleLink = Instance.new("StyleLink")
styleLink.StyleSheet = designSheet
styleLink.Parent = screenGui

-- Regel konfigurieren
local rule = Instance.new("StyleRule")
rule.Selector = "Frame"  -- Klassen-Selektor
rule.Parent = designSheet

-- Regel-Eigenschaften festlegen
rule:SetProperties({
	["BackgroundColor3"] = "$FrameColor",
	["Size"] = "$FrameSize",
	["BorderSizePixel"] = 0
})

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

Modifizierte Eigenschaften

Instanzeigenschaften, die von der Stilgestaltung betroffen sind, sind im Eigenschaften-Fenster mit einem ⚠ gekennzeichnet, und das Hovering über eine betroffene Eigenschaft zeigt an, welcher Stil sie beeinflusst. Wenn beispielsweise eine Stilregel einem getaggten Frame sagt, dass es einen AnchorPoint von 0.5, 0.5 verwenden soll, wird der Objektwert die Standard-Wert von 0, 0 anzeigen, aber sein tatsächlicher AnchorPoint wird den gestylten Wert der Regel verwenden.

Wenn ein Standard- oder gestylter Eigenschaftswert für ein bestimmtes UI-Objekt weiter modifiziert wird, wird er fett angezeigt, um einen überschriebenen Wert anzuzeigen. Beispiel — unter der Annahme eines Standard-AnchorPoint von 0, 0 — wird das Setzen dieser Eigenschaft auf 1, 1 für eine bestimmte Instanz eine Überschreibung in Fettdruck anzeigen:

Für jeden überschriebenen Eigenschaftswert können Sie mit der rechten Maustaste darauf im Eigenschaften-Fenster klicken und Zurücksetzen auf Standard auswählen, um ihn auf den gestylten Wert oder den Standardwert zurückzusetzen, wenn er nicht gestylt wurde.