Definir e utilizar recursos

Um recurso é como uma constante simbólica de uma linguagem de programação. Você o define em um só lugar e o referencia em todos os lugares que precisar. Seu código é mais fácil de ler porque você usa um nome descritivo em vez de um valor "mágico". Se você precisar alterar o valor, você só precisa atualizar a definição.

Neste módulo, você verá como usar recursos para eliminar valores codificados do Extensible Application Markup Language (XAML) que você usa no .NET Multi-platform App UI (MAUI).

O que é um recurso?

Um recurso é qualquer objeto que pode ser compartilhado em sua interface do usuário. Os exemplos mais comuns são fontes, cores e tamanhos. No entanto, você também pode armazenar objetos complexos, como instâncias Style e OnPlatform como recursos.

Você define um recurso em XAML ou código. Em seguida, você o aplica em XAML ou código. Normalmente, você trabalha inteiramente em XAML, embora mostremos alguns casos mais tarde em que o código é útil.

Considere um exemplo. Suponha que você queira usar os mesmos valores TextColor nos controles em uma página. Se você usasse valores codificados, seu XAML teria a seguinte aparência. Observe como o valor da cor do texto é repetido nos dois controles.

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

Em vez de repetir a cor do texto, você pode defini-la como um recurso. A definição se parece com este XAML:

<Color x:Key="PageControlTextColor">Blue</Color>

Observe como o elemento definido tem uma propriedade x:Key que dá um nome ao recurso. Use essa chave para procurar o recurso em seu XAML.

Antes de poder usar um recurso, você deve armazená-lo em um dicionário de recursos.

O que é ResourceDictionary?

ResourceDictionary é uma classe de biblioteca .NET MAUI personalizada para uso com recursos da interface do usuário. É um dicionário, por isso armazena pares chave/valor. O tipo da chave é limitado a String, enquanto o valor pode ser qualquer objeto.

Cada página .NET MAUI XAML tem uma propriedade chamada Resources que pode conter um objeto ResourceDictionary . A propriedade é null por padrão, portanto, você precisa criar uma instância de dicionário antes de poder usá-la. O código a seguir mostra como você criaria um objeto ResourceDictionary e o atribuiria à propriedade Resources de um ContentPage:

<ContentPage.Resources>
    <ResourceDictionary>
        ...
    </ResourceDictionary>
</ContentPage.Resources>

.NET MAUI XAML tem uma sintaxe de conveniência interna que cria a instância do dicionário automaticamente sempre que você começa a usar a propriedade Resources . O exemplo anterior pode ser simplificado para o seguinte código:

<ContentPage.Resources>
    ...
</ContentPage.Resources>

Cada página em seu aplicativo pode ter seu próprio dicionário. Você usa esses dicionários específicos da página para armazenar recursos que são usados exclusivamente nessa página.

<Label Text="Hello, World!"
        ...
        <Label.Resources>
           ...
        </Label.Resources>
</Label>

Criar um recurso

Para criar um recurso, declare-o dentro da propriedade Resources de uma página. O exemplo a seguir cria o recurso text-color descrito anteriormente

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

Ao selecionar uma chave para o recurso, escolha um nome que reflita o uso em vez do valor do recurso. Por exemplo, para definir o plano de fundo de um rótulo como Vermelho, não use RedColor como chave, use BackgroundColor em vez disso.

Aplicar um recurso usando StaticResource

StaticResource é uma extensão de marcação para procurar recursos em um dicionário de recursos. Você fornece a chave do recurso e a extensão de marcação retorna o valor correspondente. A marcação XAML a seguir mostra um exemplo que cria e usa um Color recurso chamado PageControlTextColor. A marcação XAML para o controle label no exemplo usa a extensão de marcação StaticResource para recuperar o valor.

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

...

<Label TextColor="{StaticResource PageControlTextColor}" ... />

A extensão é chamada StaticResource porque a extensão é avaliada apenas uma vez. A pesquisa de dicionário acontece quando o objeto de destino é criado. A propriedade de destino não será atualizada se o valor do recurso no dicionário for alterado.

Tipos intrínsecos XAML

O exemplo original apresentado no início desta unidade define a propriedade TextColor e a propriedade FontSize :

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

A propriedade FontSize tem o tipo Double. Para criar um recurso para esse valor, use um dos tipos intrínsecos XAML definidos na especificação XAML. A especificação XAML define nomes de tipo para muitos dos tipos simples de C#. O código a seguir mostra recursos de exemplo para cada um dos tipos intrínsecos.

<ContentPage.Resources>
    <x:String x:Key="...">Hello</x:String>
    <x:Char x:Key="...">X</x:Char>
    <x:Single x:Key="...">31.4</x:Single>
    <x:Double x:Key="...">27.1</x:Double>
    <x:Byte x:Key="...">8</x:Byte>
    <x:Int16 x:Key="...">16</x:Int16>
    <x:Int32 x:Key="...">32</x:Int32>
    <x:Int64 x:Key="...">64</x:Int64>
    <x:Decimal x:Key="...">12345</x:Decimal>
    <x:TimeSpan x:Key="...">1.23:5959</x:TimeSpan>
    <x:Boolean x:Key="...">True</x:Boolean>
</ContentPage.Resources>

Definir valores específicos da plataforma para um recurso

É comum precisar ajustar ligeiramente a interface do usuário do seu aplicativo entre plataformas. A maneira padrão de definir os valores específicos da plataforma é usando um objeto OnPlatform quando você define um recurso. Por exemplo, o código a seguir mostra como criar um recurso que faz referência a cores de texto diferentes no iOS, Android, macOS (Mac Catalyst) e Windows (WinUI).

<ContentPage.Resources>
    <OnPlatform x:Key="textColor" x:TypeArguments="Color">
        <On Platform="iOS" Value="Silver" />
        <On Platform="Android" Value="Green" />
        <On Platform="WinUI" Value="Yellow" />
        <On Platform="MacCatalyst" Value="Pink" />
    </OnPlatform> 
</ContentPage.Resources>
...

<Label TextColor="{StaticResource textColor}" ... />