UI-styling | Documentatie - Roblox Creator Hub

UI-styling is een Roblox-oplossing voor stylesheets, vergelijkbaar met CSS, die je in staat stelt om overrides voor UI-instantie-eigenschappen te declareren en globaal toe te passen. Deze engine-niveau ondersteuning vormt de basis voor de Style Editor en de end-to-end tokenpipeline.

Concepten

Stijl regels (onderdeel van een StyleSheet) zijn van toepassing op elke instantie die overeenkomt met de definitie van de regel's Selector om kenmerken zoals de klassenaam, instantienaam en hiërarchische relaties te matchen. Zie de documentatie van Selector voor details.

Stijl tokens, gedefinieerd via attributen van een token StyleSheet, vertegenwoordigen UI-eigenschap variabelen die kunnen worden gebruikt in stijlen en componenten, bijvoorbeeld een gemeenschappelijke kleur voor een Frame.BackgroundColor3, TextLabel.TextColor3, en UIStroke.Color. Tokens zijn vergelijkbaar met CSS variabelen.

Stijl thema's, geconfigureerd via attributen van een thema StyleSheet, bestaan uit sets van specifieke tokens die kunnen worden verwisseld, bijvoorbeeld kleurtokens die een "lichte" en "donkere" thema definiëren. Gerelateerde thema's moeten dezelfde set tokens hebben om correct te functioneren.

Stijl queries stellen je in staat om stijlen conditioneel toe te passen op basis van de context of omgeving van de UI. Deze zijn vergelijkbaar met CSS container queries en media queries, waardoor de UI kan aanpassen aan schermgrootte, invoertypen of gebruikers toegankelijkheidsinstellingen.

Regelpropagatie

Een StyleLink instantie koppelt een StyleSheet en de bijbehorende regels aan een ouder ScreenGui en alle GuiObjects daarin. Slechts één StyleSheet kan van toepassing zijn op een gegeven boom.

Selector definities

Op hoog niveau werkt het matchen en wijzigen van instanties via de definitie van een regel's Selector door:

Roblox klasse selectors die alle instanties van een gegeven GuiObject klasse targeten, bijvoorbeeld Frame, ImageLabel, TextButton, enz.
Instantie tags toegepast op specifieke UI-objecten via CollectionService.
Instantie naam selectie volgens de waarde van de UI-object's Instance.Name.
Instantie modifiers, vergelijkbaar met CSS pseudo-elementen, toegepast via phantom UIComponents zoals UICorner of UIStroke.
GuiObject staat selectors, vergelijkbaar met CSS pseudo-class selectors, die overeenkomen met een van de vier GuiState enum waarden zoals Hover.
Roblox query selectors, vergelijkbaar met CSS container en media queries, die de @ prefix gebruiken om stijlen alleen toe te passen terwijl een StyleQuery instantie of pseudo-instantie met dezelfde naam actief is.

De volgende setup toont hoe grootte- en kleurtokens, een thema, en een klasse-selector van "Frame" een magenta Frame van grootte 200×200 pixels produceert.

Code Equivalent

UI Class Selector

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  -- Derive global tokens
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  -- Derive global tokens
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  -- Derive from ThemeB
themeDerive.Parent = designSheet

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

-- Configure rule
local rule = Instance.new("StyleRule")
rule.Selector = "Frame"  -- Class selector
rule.Parent = designSheet

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

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

Gewijzigde eigenschappen

Instantie-eigenschappen die door styling worden beïnvloed, zijn gemarkeerd met een ⚠ in het Eigenschappen venster, en wanneer je met de muis over een beïnvloede eigenschap beweegt, wordt weergegeven welke stijl deze beïnvloedt. Bijvoorbeeld, als een stijlregel een getagde Frame vertelt om een AnchorPoint van 0.5, 0.5 te gebruiken, zal die objecteigenschap de standaard waarde van 0, 0 tonen, maar zijn werkelijke AnchorPoint zal de gestylede waarde van de regel gebruiken.

Wanneer een standaard of gestylede eigenschapswaarde verder wordt gewijzigd voor een specifiek UI-object, wordt deze vetgedrukt om een overschreven waarde aan te geven. Bijvoorbeeld — aangenomen dat een standaard AnchorPoint van 0, 0 — het instellen van die eigenschap op 1, 1 voor een specifieke instantie onthult een override in vetgedrukt:

Voor elke overschreven eigenschapswaarde kun je er met de rechtermuisknop op klikken in het Eigenschappen venster en Reset naar Standaard selecteren om deze terug te zetten naar de gestylede waarde, of naar de standaard eigenschapswaarde als deze niet is gestyled.