Aplicativos de estilo usando folhas de estilo em cascata

Os aplicativos .NET MAUI (interface de aplicativos multiplataforma do .NET) podem ser estilizados usando Folhas de Estilo em Cascata (CSS). Uma folha de estilos consiste em uma lista de regras, com cada regra consistindo em um ou mais seletores e um bloco de declaração. Um bloco de declaração consiste em uma lista de declarações entre chaves, onde cada declaração se compõe de uma propriedade, o símbolo de dois-pontos e um valor. Quando há várias declarações em um bloco, um ponto e vírgula é inserido como separador.

O exemplo a seguir mostra alguns CSS compatíveis com o .NET MAUI:

navigationpage {
    -maui-bar-background-color: lightgray;
}

^contentpage {
    background-color: lightgray;
}

#listView {
    background-color: lightgray;
}

stacklayout {
    margin: 20;
    -maui-spacing: 6;
}

grid {
    row-gap: 6;
    column-gap: 6;
}
.mainPageTitle {
    font-style: bold;
    font-size: 14;
}

.mainPageSubtitle {
    margin-top: 15;
}

.detailPageTitle {
    font-style: bold;
    font-size: 14;
    text-align: center;
}

.detailPageSubtitle {
    text-align: center;
    font-style: italic;
}

listview image {
    height: 60;
    width: 60;
}

stacklayout>image {
    height: 200;
    width: 200;
}

No .NET MAUI, as folhas de estilo do CSS são analisadas e avaliadas em runtime, em vez de tempo de compilação, e folhas de estilo são analisadas novamente no uso.

Importante

Não é possível estilizar totalmente um aplicativo MAUI do .NET usando CSS. No entanto, os estilos XAML podem ser usados para complementar o CSS. Para obter mais informações sobre estilos XAML, consulte Estilizar aplicativos usando XAML.

Consumir uma folha de estilos

O processo para adicionar uma folha de estilos a um aplicativo MAUI do .NET é o seguinte:

1. Adicione um arquivo CSS vazio ao seu projeto de aplicativo .NET MAUI. O arquivo CSS pode ser colocado em qualquer pasta, com a pasta Recursos sendo o local recomendado.
2. Defina a ação de build do arquivo CSS para MauiCss.

Carregando uma folha de estilos

Há várias abordagens que podem ser usadas para carregar uma folha de estilos.

Nota

Não é possível alterar uma folha de estilos em runtime e aplicar a nova folha de estilos.

Carregar uma folha de estilos em XAML

Uma folha de estilos pode ser carregada e processada com a classe StyleSheet antes de ser adicionada a um ResourceDictionary:

<Application ...>
    <Application.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </Application.Resources>
</Application>

A propriedade StyleSheet.Source especifica a folha de estilos como um URI relativo ao local do arquivo XAML delimitado ou relativo à raiz do projeto se o URI começar com um /.

Aviso

O arquivo CSS falhará ao carregar se sua ação de build não estiver definida como mauiCss.

Como alternativa, uma folha de estilos pode ser carregada e analisada com a classe StyleSheet, antes de ser adicionada a um ResourceDictionary, sublinhando-a em uma seção CDATA:

<ContentPage ...>
    <ContentPage.Resources>
        <StyleSheet>
            <![CDATA[
            ^contentpage {
                background-color: lightgray;
            }
            ]]>
        </StyleSheet>
    </ContentPage.Resources>
    ...
</ContentPage>

Para obter mais informações sobre dicionários de recursos, consulte dicionários de recursos.

Carregar uma folha de estilos em C#

Em C#, uma folha de estilos pode ser carregada de um StringReader e adicionada a um ResourceDictionary:

using Microsoft.Maui.Controls.StyleSheets;

public partial class MyPage : ContentPage
{
    public MyPage()
    {
        InitializeComponent();

        using (var reader = new StringReader("^contentpage { background-color: lightgray; }"))
        {
            this.Resources.Add(StyleSheet.FromReader(reader));
        }
    }
}

O argumento para o método StyleSheet.FromReader é o TextReader que leu a folha de estilo.

Selecionar elementos e aplicar propriedades

O CSS usa seletores para determinar quais elementos serão direcionados. Os estilos com seletores correspondentes são aplicados consecutivamente, na ordem de definição. Os estilos definidos em um item específico são sempre aplicados por último. Para obter mais informações sobre seletores com suporte, consulte a referência do seletor .

O CSS usa propriedades para definir o estilo de um elemento selecionado. Cada propriedade tem um conjunto de valores possíveis e algumas propriedades podem afetar qualquer tipo de elemento, enquanto outras se aplicam a grupos de elementos. Para obter mais informações sobre propriedades com suporte, consulte referência de propriedade.

As folhas de estilo filho sempre substituem as folhas de estilo pai se definirem as mesmas propriedades. Portanto, as seguintes regras de precedência são seguidas ao aplicar estilos que definem as mesmas propriedades:

• Um estilo definido nos recursos do aplicativo será substituído por um estilo definido nos recursos da página, se eles definirem as mesmas propriedades.
• Um estilo definido em recursos de página será substituído por um estilo definido nos recursos de controle, se eles definirem as mesmas propriedades.
• Um estilo definido nos recursos do aplicativo será substituído por um estilo definido nos recursos de controle, se eles definirem as mesmas propriedades.

Nota

As variáveis CSS não têm suporte.

Selecionar elementos por tipo

Os elementos na árvore visual podem ser selecionados por tipo com o seletor de element que não diferencia maiúsculas de minúsculas:

stacklayout {
    margin: 20;
}

Esse seletor identifica todos os elementos StackLayout em páginas que consomem a folha de estilos e define suas margens como uma espessura uniforme de 20.

Nota

O seletor de element não identifica subclasses do tipo especificado.

Selecionando elementos por classe base

Os elementos na árvore visual podem ser selecionados pela classe base usando o seletor ^base que não diferencia maiúsculas de minúsculas.

^contentpage {
    background-color: lightgray;
}

Esse seletor identifica todos os elementos ContentPage que consomem a folha de estilos e define a cor da tela de fundo como lightgray.

Nota

O seletor de ^base é específico do .NET MAUI e não faz parte da especificação do CSS.

Selecionando um elemento por nome

Elementos individuais na árvore visual podem ser selecionados com o seletor #id sensível a maiúsculas e minúsculas.

#listView {
    background-color: lightgray;
}

Esse seletor identifica o elemento cuja propriedade StyleId está definida como listView. No entanto, se a propriedade StyleId não estiver definida, o seletor retornará ao uso do x:Name do elemento. Portanto, no exemplo a seguir, o seletor de #listView identificará o ListView cujo atributo x:Name está definido como listViewe definirá a cor da tela de fundo como lightgray.

<ContentPage ...>
    <ContentPage.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </ContentPage.Resources>
    <StackLayout>
        <ListView x:Name="listView">
            ...
        </ListView>
    </StackLayout>
</ContentPage>

Selecionar elementos com um atributo de classe específico

Elementos com um atributo de classe específico podem ser selecionados com o seletor .class, que diferencia maiúsculas de minúsculas.

.detailPageTitle {
    font-style: bold;
    font-size: 14;
    text-align: center;
}

.detailPageSubtitle {
    text-align: center;
    font-style: italic;
}

Uma classe CSS pode ser atribuída a um elemento XAML definindo a propriedade StyleClass do elemento como o nome da classe CSS. Portanto, no exemplo a seguir, os estilos definidos pela classe .detailPageTitle são atribuídos à primeira Label, enquanto os estilos definidos pela classe .detailPageSubtitle são atribuídos ao segundo Label.

<ContentPage ...>
    <ContentPage.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </ContentPage.Resources>
    <ScrollView>
        <StackLayout>
            <Label ... StyleClass="detailPageTitle" />
            <Label ... StyleClass="detailPageSubtitle"/>
        </StackLayout>
    </ScrollView>
</ContentPage>

Selecionar elementos filho

Os elementos filho na árvore visual podem ser selecionados com o seletor de element element sem diferenciação de maiúsculas e minúsculas:

listview image {
    height: 60;
    width: 60;
}

Esse seletor identifica todos os elementos Image filhos de elementos ListView e define sua altura e largura como 60. Portanto, no exemplo XAML a seguir, o seletor de listview image identificará o Image que é filho do ListViewe definirá sua altura e largura como 60.

<ContentPage ...>
    <ContentPage.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </ContentPage.Resources>
    <StackLayout>
        <ListView ...>
            <ListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <Grid>
                            ...
                            <Image ... />
                            ...
                        </Grid>
                    </ViewCell>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </StackLayout>
</ContentPage>

Nota

O seletor de element element não exige que o elemento filho seja um filho direto do pai– o elemento filho pode ter um pai diferente. A seleção ocorre desde que um ancestral seja o primeiro elemento especificado.

Selecionar elementos filho diretos

Os elementos filho diretos na árvore visual podem ser selecionados com o seletor element>element sem distinção entre maiúsculas e minúsculas:

stacklayout>image {
    height: 200;
    width: 200;
}

Esse seletor identifica todos os elementos Image que são filhos diretos de elementos StackLayout e define sua altura e largura como 200. Portanto, no exemplo a seguir, o seletor de stacklayout>image identificará o Image que é um filho direto do StackLayoute definirá sua altura e largura como 200.

<ContentPage ...>
    <ContentPage.Resources>
        <StyleSheet Source="/Resources/styles.css" />
    </ContentPage.Resources>
    <ScrollView>
        <StackLayout>
            ...
            <Image ... />
            ...
        </StackLayout>
    </ScrollView>
</ContentPage>

Nota

O seletor de element>element requer que o elemento filho seja um filho direto do pai.

Referência do seletor

Os seguintes seletores CSS são compatíveis com o MAUI do .NET:

Seletor	Exemplo	Descrição
.class	.header	Seleciona todos os elementos com a propriedade StyleClass que contém 'header'. Esse seletor diferencia maiúsculas de minúsculas.
#id	#email	Seleciona todos os elementos com StyleId definido como email. Se StyleId não estiver definido, será utilizada a alternativa x:Name. Ao usar XAML, x:Name é preferencial em vez de StyleId. Esse seletor diferencia maiúsculas de minúsculas.
*	*	Seleciona todos os elementos.
element	label	Seleciona todos os elementos do tipo Label, mas não subclasses. Esse seletor não diferencia maiúsculas de minúsculas.
^base	^contentpage	Seleciona todos os elementos com ContentPage como a classe base, incluindo ContentPage em si. Esse seletor não diferencia maiúsculas de minúsculas e não faz parte da especificação do CSS.
element,element	label,button	Seleciona todos os elementos Button e todos os elementos Label. Esse seletor é insensível a maiúsculas e minúsculas.
element element	stacklayout label	Seleciona todos os elementos Label dentro de um StackLayout. Esse seletor não diferencia maiúsculas de minúsculas.
element>element	stacklayout>label	Seleciona todos os elementos Label cujo pai direto é StackLayout. Esse seletor não diferencia maiúsculas de minúsculas.
element+element	label+entry	Seleciona todos os elementos Entry que estão imediatamente após um Label. Esse seletor não diferencia maiúsculas de minúsculas.
element~element	label~entry	Seleciona todos os elementos Entry precedidos por um Label. Esse seletor não diferencia maiúsculas de minúsculas.

Os estilos com seletores correspondentes são aplicados consecutivamente, na ordem de definição. Os estilos definidos em um item específico são sempre aplicados por último.

Dica

Os seletores podem ser combinados sem limitação, como StackLayout>ContentView>label.email.

Os seletores a seguir não têm suporte:

• [attribute]
• @media e @supports
• : e ::

Se duas ou mais regras CSS apontarem para o mesmo elemento, o seletor com a mais alta especificidade terá precedência e sua declaração de estilo será aplicada ao elemento. O algoritmo de especificidade calcula o peso de um seletor CSS para determinar qual regra das declarações CSS concorrentes é aplicada ao elemento.

Referência de propriedade

As propriedades CSS a seguir são suportadas pelo .NET MAUI (na coluna de valores , os tipos são em itálico , enquanto os literais de strings são gray):

Propriedade	Aplica-se a	Valores	Exemplo
align-content	FlexLayout	stretch | center | start | end | spacebetween | spacearound | spaceevenly | flex-start | flex-end | space-between | space-around | initial	align-content: space-between;
align-items	FlexLayout	stretch | center | start | end | flex-start | flex-end | initial	align-items: flex-start;
align-self	VisualElement	auto | stretch | center | start | end | flex-start | flex-end | initial	align-self: flex-end;
background-color	VisualElement	cor | initial	background-color: springgreen;
background-image	Page	cadeia de caracteres | initial	background-image: bg.png;
border-color	Button, Frame, ImageButton	cor | initial	border-color: #9acd32;
border-radius	BoxView, Button, Frame, ImageButton	duplo | initial	border-radius: 10;
border-width	Button, ImageButton	duplo | initial	border-width: .5;
color	ActivityIndicator, BoxView, Button, CheckBox, DatePicker, Editor, Entry, Label, Picker, ProgressBar, SearchBar, Switch, TimePicker	de cor | initial	color: rgba(255, 0, 0, 0.3);
column-gap	Grid	duplo | initial	column-gap: 9;
direction	VisualElement	ltr | rtl | inherit | initial	direction: rtl;
flex-direction	FlexLayout	column | columnreverse | row | rowreverse | row-reverse | column-reverse | initial	flex-direction: column-reverse;
flex-basis	VisualElement	float | auto | initial. Além disso, uma porcentagem no intervalo de 0% a 100% pode ser especificada com o sinal de %.	flex-basis: 25%;
flex-grow	VisualElement	float | initial	flex-grow: 1.5;
flex-shrink	VisualElement	flutuante | initial	flex-shrink: 1;
flex-wrap	VisualElement	nowrap | wrap | reverse | wrap-reverse | initial	flex-wrap: wrap-reverse;
font-family	Button, DatePicker, Editor, Entry, Label, Picker, SearchBar, TimePicker, Span	de cadeia de caracteres | initial	font-family: Consolas;
font-size	Button, DatePicker, Editor, Entry, Label, Picker, SearchBar, TimePicker, Span	duplo | initial	font-size: 12;
font-style	Button, DatePicker, Editor, Entry, Label, Picker, SearchBar, TimePicker, Span	bold | italic | initial	font-style: bold;
height	VisualElement	duplo | initial	height: 250;
justify-content	FlexLayout	start | center | end | spacebetween | spacearound | spaceevenly | flex-start | flex-end | space-between | space-around | initial	justify-content: flex-end;
letter-spacing	Button, DatePicker, Editor, Entry, Label, Picker, SearchBar, SearchHandler, Span, TimePicker	duplo | initial	letter-spacing: 2.5;
line-height	Label, Span	duplo | initial	line-height: 1.8;
margin	View	espessura | initial	margin: 6 12;
margin-left	View	espessura | initial	margin-left: 3;
margin-top	View	espessura | initial	margin-top: 2;
margin-right	View	espessura | initial	margin-right: 1;
margin-bottom	View	espessura | initial	margin-bottom: 6;
max-lines	Label	int | initial	max-lines: 2;
min-height	VisualElement	duplo | initial	min-height: 50;
min-width	VisualElement	duplo | initial	min-width: 112;
opacity	VisualElement	duplo | initial	opacity: .3;
order	VisualElement	int | initial	order: -1;
padding	Button, ImageButton, Layout, Page	espessura | initial	padding: 6 12 12;
padding-left	Button, ImageButton, Layout, Page	duplo | initial	padding-left: 3;
padding-top	Button, ImageButton, Layout, Page	duplo | initial	padding-top: 4;
padding-right	Button, ImageButton, Layout, Page	duplo | initial	padding-right: 2;
padding-bottom	Button, ImageButton, Layout, Page	duplo | initial	padding-bottom: 6;
position	FlexLayout	relative | absolute | initial	position: absolute;
row-gap	Grid	duplo | initial	row-gap: 12;
text-align	Entry, EntryCell, Label, SearchBar	left | top | right | bottom | start | center | middle | end | initial. left e right devem ser evitados em ambientes da direita para a esquerda.	text-align: right;
text-decoration	Label, Span	none | underline | strikethrough | line-through | initial	text-decoration: underline, line-through;
text-transform	Button,Editor, Entry, Label, SearchBar, SearchHandler	none | default | uppercase | lowercase | initial	text-transform: uppercase;
transform	VisualElement	none, rotate, rotateX, rotateY, scale, scaleX, scaleY, translate, translateX, translateY, initial	transform: rotate(180), scaleX(2.5);
transform-origin	VisualElement	duplo, duplo | initial	transform-origin: 7.5, 12.5;
vertical-align	Label	left | top | right | bottom | start | center | middle | end | initial	vertical-align: bottom;
visibility	VisualElement	true | visible | false | hidden | collapse | initial	visibility: hidden;
width	VisualElement	duplo | initial	width: 320;

Nota

initial é um valor válido para todas as propriedades. Ele limpa o valor (reinicia para o padrão) que foi definido por outro estilo.

As seguintes propriedades não têm suporte:

• all: initial.
• Propriedades de layout (caixa ou grade).
• Propriedades abreviadas, como fonte border.

Além disso, não há valor inherit e, portanto, a herança não é suportada. Portanto, não é possível, por exemplo, definir a propriedade font-size em um layout e esperar que todas as instâncias Label no layout herdem o valor. A única exceção é a propriedade direction, que tem um valor padrão de inherit.

Importante

Span elementos não podem ser direcionados usando CSS.

Propriedades específicas do .NET MAUI

Há suporte para as seguintes propriedades CSS específicas do .NET MAUI (na coluna Valores, os tipos são itálico, enquanto os literais de texto são gray):

Propriedade	Aplica-se a	Valores	Exemplo
-maui-bar-background-color	NavigationPage, TabbedPage	cor | initial	-maui-bar-background-color: teal;
-maui-bar-text-color	NavigationPage, TabbedPage	cor | initial	-maui-bar-text-color: gray
-maui-horizontal-scroll-bar-visibility	ScrollView	default | always | never | initial	-maui-horizontal-scroll-bar-visibility: never;
-maui-max-length	Entry, Editor, SearchBar	int | initial	-maui-max-length: 20;
-maui-max-track-color	Slider	cor | initial	-maui-max-track-color: red;
-maui-min-track-color	Slider	de cor | initial	-maui-min-track-color: yellow;
-maui-orientation	ScrollView, StackLayout	horizontal | vertical | both | initial. both só tem suporte em um ScrollView.	-maui-orientation: horizontal;
-maui-placeholder	Entry, Editor, SearchBar	| initial citação de texto entre aspas	-maui-placeholder: Enter name;
-maui-placeholder-color	Entry, Editor, SearchBar	cor | initial	-maui-placeholder-color: green;
-maui-spacing	StackLayout	duplo | initial	-maui-spacing: 8;
-maui-shadow	VisualElement	Os formatos válidos são: cor, deslocamento X, deslocamento Y | deslocamento X, deslocamento Y, raio, cor | deslocamento X, deslocamento Y, raio, cor, opacidade	-maui-shadow: #000000 4 4;
-maui-thumb-color	Slider, Switch	cor | initial	-maui-thumb-color: limegreen;
-maui-vertical-scroll-bar-visibility	ScrollView	default | always | never | initial	-maui-vertical-scroll-bar-visibility: always;
-maui-vertical-text-alignment	Label	start | center | end | initial	-maui-vertical-text-alignment: end;
-maui-visual	VisualElement	cadeia de caracteres | initial	-maui-visual: material;

Propriedades específicas do Shell do .NET MAUI

Também há suporte para as seguintes propriedades CSS específicas do Shell do .NET MAUI (na coluna Valores, os tipos são itálico, enquanto os literais de strings são gray):

Propriedade	Aplica-se a	Valores	Exemplo
-maui-flyout-background	Shell	cor | initial	-maui-flyout-background: red;
-maui-shell-background	Element	cor | initial	-maui-shell-background: green;
-maui-shell-disabled	Element	cor | initial	-maui-shell-disabled: blue;
-maui-shell-foreground	Element	de cor | initial	-maui-shell-foreground: yellow;
-maui-shell-tabbar-background	Element	de cor | initial	-maui-shell-tabbar-background: white;
-maui-shell-tabbar-disabled	Element	cor | initial	-maui-shell-tabbar-disabled: black;
-maui-shell-tabbar-foreground	Element	de cor | initial	-maui-shell-tabbar-foreground: gray;
-maui-shell-tabbar-title	Element	cor | initial	-maui-shell-tabbar-title: lightgray;
-maui-shell-tabbar-unselected	Element	Cor | initial	-maui-shell-tabbar-unselected: cyan;
-maui-shell-title	Element	Cor | initial	-maui-shell-title: teal;
-maui-shell-unselected	Element	cor | initial	-maui-shell-unselected: limegreen;

Cor

Há suporte para os seguintes valores de color:

• X11 cores, que correspondem às cores CSS e .NET MAUI. Esses valores de cor não diferenciam maiúsculas de minúsculas.
• cores hexadecimais: #rgb, #argb, #rrggbb, #aarrggbb
• cores rgb: rgb(255,0,0), rgb(100%,0%,0%). Os valores estão no intervalo de 0 a 255 ou 0%-100%.
• Cores de rgba: rgba(255, 0, 0, 0.8), rgba(100%, 0%, 0%, 0.8). O valor de opacidade está no intervalo 0.0-1.0.
• cores hsl: hsl(120, 100%, 50%). O valor h está no intervalo de 0 a 360, enquanto s e l estão no intervalo 0%-100%.
• cores hsla: hsla(120, 100%, 50%, .8). O valor de opacidade está no intervalo 0.0-1.0.

Espessura

Há suporte para um, dois, três ou quatro valores de thickness, cada um separado por espaço em branco:

• Um único valor indica espessura uniforme.
• Dois valores indicam espessura vertical e horizontal.
• Três valores indicam a espessura superior, depois a horizontal (esquerda e direita) e, por último, a inferior.
• Quatro valores indicam a espessura superior, direita, inferior e esquerda.

Nota

Os valores de thickness do CSS diferem dos valores de Thickness XAML. Por exemplo, em XAML, um Thickness de dois valores indica espessura horizontal e vertical, enquanto um Thickness de quatro valores indica a espessura esquerda, superior, direita e inferior. Além disso, os valores de Thickness XAML são delimitados por vírgula.

Funções

Gradientes lineares e radiais podem ser especificados usando as funções CSS linear-gradient() e radial-gradient(), respectivamente. O resultado dessas funções deve ser atribuído à propriedade background de um controle.