Definir e usar recursos

Um recurso é como uma constante simbólica de uma linguagem de programação. Você o define em um lugar e faz referência a ele em qualquer lugar que precise dele. 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, será necessário apenas atualizar a definição.

Neste módulo, você verá como usar recursos para eliminar valores embutidos em código da Extensible Application Markup Language (XAML) que você usa na .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 de Estilo e OnPlatform como recursos.

Você pode definir um recurso em XAML ou código. Então você o aplica em XAML ou código. Normalmente, você trabalha inteiramente em XAML, embora mostremos alguns casos mais adiante em que o código é útil.

Considere um exemplo. Suponha que você queira usar os mesmos valores TextColor entre os controles em uma página. Se você usar valores embutidos em código, seu XAML terá a seguinte aparência. Observe como o valor para a cor do texto é repetido em 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 é semelhante a este XAML:

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

Observe como o elemento definido tem uma propriedade x:Key que dá um nome ao recurso. Você usa essa chave para pesquisar o recurso no XAML.

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

O que é um ResourceDictionary?

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

Cada página XAML do .NET MAUI tem uma propriedade chamada Resources que pode conter um objeto ResourceDictionary . A propriedade é nula por padrão, portanto, você precisa criar uma instância do dicionário antes de 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>

O .NET MAUI XAML tem uma sintaxe de conveniência interna que cria a instância de 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 do aplicativo pode ter o próprio dicionário. Use esses dicionários específicos de 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 para 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 a chave, use BackgroundColor.

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 de rótulo 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 ocorre quando o objeto de destino é criado. A propriedade de destino não será atualizada se o valor de recurso no dicionário mudar.

Tipos intrínsecos do 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 de 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 um pouco 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 diferentes cores de texto no iOS, no Android, no macOS (Mac Catalyst) e no 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}" ... />