Estilização da UI

A estilização da UI é uma solução da Roblox para folhas de estilo, semelhante ao CSS, que permite declarar e aplicar globalmente substituições nas propriedades da instância da UI. Este suporte em nível de motor é a base para o Editor de Estilos e o pipeline de tokens de ponta a ponta.

Conceitos

As regras de estilo (parte de uma StyleSheet) se aplicam a cada instância que corresponde à definição de Selector da regra para combinar características como nome de classe, nome de instância e relacionamentos hierárquicos. Veja a documentação de Selector para mais detalhes.

Os tokens de estilo, definidos por meio de atributos de um token StyleSheet, representam variáveis de propriedades da UI que podem ser usadas em estilos e componentes, por exemplo, uma cor comum para Frame.BackgroundColor3, TextLabel.TextColor3 e UIStroke.Color. Os tokens são comparáveis a variáveis do CSS.

Os temas de estilo, configurados por meio de atributos de um tema StyleSheet, consistem em conjuntos de tokens específicos que podem ser trocados, por exemplo, tokens de cor que definem um tema "claro" e "escuro". Temas relacionados devem ter o mesmo conjunto de tokens para funcionar corretamente.

As consultas de estilo permitem que você aplique estilos condicionalmente com base no contexto ou ambiente da UI. Estes são comparáveis a consultas de contêiner e consultas de mídia do CSS, permitindo que a UI se adapte ao tamanho da tela, tipos de entrada ou configurações de acessibilidade do usuário.

Propagação de regras

Uma instância StyleLink conecta uma StyleSheet e suas regras associadas a um ScreenGui pai e a todos os GuiObjects dentro dele. Apenas uma StyleSheet pode se aplicar a uma determinada árvore.

Definições de seletor

Em um nível alto, a correspondência e modificação de instâncias através da definição do Selector de uma regra operam por meio de:

• Seletores de classe Roblox que visam todas as instâncias de uma determinada classe GuiObject, por exemplo, Frame, ImageLabel, TextButton, etc.
• Tags de instância aplicadas a objetos de UI específicos através de CollectionService.
• Seleção de nome de instância de acordo com o valor do Instance.Name do objeto da UI.
• Modificadores de instância, semelhantes a pseudo-elementos CSS, aplicados através de UIComponents fantasma, como UICorner ou UIStroke.
• Seletores de estado de GuiObject, semelhantes a seletores de pseudo-classe CSS, que correspondem a um dos quatro valores do enum GuiState, como Hover.
• Seletores de consulta Roblox, semelhantes a consultas de contêiner e mídia CSS, que usam o prefixo @ para aplicar estilos somente enquanto uma instância StyleQuery ou pseudo-instância com o mesmo nome estiver ativa.

A configuração a seguir mostra como tokens de tamanho e cor, um tema e um seletor de classe de "Frame" produzem um Frame magenta de tamanho 200×200 pixels.

Seletor de Classe da UI
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"))

-- TemaA
local themeA = Instance.new("StyleSheet")
themeA.Name = "ThemeA"
themeA.Parent = ReplicatedStorage
local tokensDerive = Instance.new("StyleDerive")
tokensDerive.StyleSheet = tokens  -- Derivar tokens globais
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  -- Derivar tokens globais
tokensDerive.Parent = themeB
themeB:SetAttribute("FrameSize", "$SquareL")
themeB:SetAttribute("FrameColor", "$Magenta")

-- Folha de Design
local designSheet = Instance.new("StyleSheet")
designSheet.Name = "DesignSheet"
designSheet.Parent = ReplicatedStorage
local themeDerive = Instance.new("StyleDerive")
themeDerive.StyleSheet = themeB  -- Derivar de ThemeB
themeDerive.Parent = designSheet

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

-- Configurar regra
local rule = Instance.new("StyleRule")
rule.Selector = "Frame"  -- Seletor de classe
rule.Parent = designSheet

-- Definir propriedades da regra
rule:SetProperties({
	["BackgroundColor3"] = "$FrameColor",
	["Size"] = "$FrameSize",
	["BorderSizePixel"] = 0
})

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

Propriedades modificadas

As propriedades da instância afetadas pela estilização são sinalizadas com um ⚠ na janela Propriedades, e passar o mouse sobre uma propriedade afetada mostra qual estilo a está influenciando. Por exemplo, se uma regra de estilo disser a um Frame marcado para usar um AnchorPoint de 0.5, 0.5, essa propriedade do objeto mostrará o valor padrão de 0, 0, mas seu AnchorPoint real usará o valor estilizado da regra.

Quando um valor de propriedade padrão ou estilizado é alterado ainda mais para um objeto de UI específico, ele fica negrito para indicar um valor substituído. Por exemplo — assumindo um AnchorPoint padrão de 0, 0 — definir essa propriedade para 1, 1 para uma instância específica revela uma substituição em negrito:

Para qualquer valor de propriedade substituído, você pode clicar com o botão direito sobre ele na janela Propriedades e selecionar Reverter para Padrão para revertê-lo ao valor estilizado ou ao valor de propriedade padrão se ele não foi estilizado.