Dicionários de recurso
Uma interface do usuário de aplicativo multiplataforma do .NET (.NET MAUI) ResourceDictionary é um repositório de recursos usados por um aplicativo .NET MAUI. Recursos típicos armazenados em um ResourceDictionary incluem estilos, modelos de controle, modelos de dados, conversores e cores.
Os recursos XAML armazenados em um ResourceDictionary podem ser referenciados e aplicados a elementos usando a StaticResource extensão de marcação ou DynamicResource . No C#, os recursos também podem ser definidos em um e, em seguida, referenciados e aplicados a elementos usando um ResourceDictionary indexador baseado em cadeia de caracteres.
Dica
No Visual Studio, um arquivo baseado em ResourceDictionary XAML que é apoiado por um arquivo code-behind pode ser adicionado ao seu projeto pelo modelo de item .NET MAUI ResourceDictionary (XAML).
Criar recursos
Cada VisualElement objeto derivado tem uma propriedade, que é uma ResourceDictionaryResources que pode conter recursos. Da mesma forma, um Application objeto derivado tem uma propriedade, que é uma ResourcesResourceDictionary que pode conter recursos.
Um aplicativo .NET Maui pode conter apenas uma única classe derivada do , mas geralmente faz uso de muitas classes que derivam do ApplicationVisualElement, incluindo páginas, layouts e modos de exibição. Qualquer um desses objetos pode ter sua Resources propriedade definida como um ResourceDictionary contendo recursos. Escolhendo onde colocar um determinado ResourceDictionary impacto onde os recursos podem ser usados:
- Os recursos em um que está anexado a um ResourceDictionary modo de exibição, como Button ou Label, só podem ser aplicados a esse objeto específico.
- Os recursos em um anexo a um ResourceDictionary layout, como StackLayout ou Grid, podem ser aplicados ao layout e a todos os filhos desse layout.
- Os recursos em um ResourceDictionary definido no nível da página podem ser aplicados à página e a todos os seus filhos.
- Os recursos em um ResourceDictionary definido no nível do aplicativo podem ser aplicados em todo o aplicativo.
Com exceção dos estilos implícitos, cada recurso no dicionário de recursos deve ter uma chave de cadeia de caracteres exclusiva definida com o x:Key atributo.
O XAML a seguir mostra os recursos definidos em um nível ResourceDictionary de aplicativo no arquivo App.xaml :
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="ResourceDictionaryDemo.App">
<Application.Resources>
<Thickness x:Key="PageMargin">20</Thickness>
<!-- Colors -->
<Color x:Key="AppBackgroundColor">AliceBlue</Color>
<Color x:Key="NavigationBarColor">#1976D2</Color>
<Color x:Key="NavigationBarTextColor">White</Color>
<Color x:Key="NormalTextColor">Black</Color>
<!-- Images -->
<x:String x:Key="BackgroundImage">background</x:String>
<x:String x:Key="MenuIcon">menu.png</x:String>
<x:String x:Key="SearchIcon">search.png</x:String>
<!-- Implicit styles -->
<Style TargetType="NavigationPage">
<Setter Property="BarBackgroundColor"
Value="{StaticResource NavigationBarColor}" />
<Setter Property="BarTextColor"
Value="{StaticResource NavigationBarTextColor}" />
</Style>
<Style TargetType="ContentPage"
ApplyToDerivedTypes="True">
<Setter Property="BackgroundColor"
Value="{StaticResource AppBackgroundColor}" />
</Style>
</Application.Resources>
</Application>
Neste exemplo, o dicionário de recursos define um Thickness recurso, vários Color recursos e dois recursos implícitos Style .
Importante
A inserção de recursos diretamente entre as marcas property-element Resources cria automaticamente um ResourceDictionary objeto. No entanto, também é válido colocar todos os recursos entre tags opcionais ResourceDictionary .
Consumir recursos
Cada recurso tem uma chave que é especificada usando o atributo x:Key , que se torna sua chave de dicionário no ResourceDictionary. A chave é usada para fazer referência a um recurso da ResourceDictionary extensão de marcação com ou StaticResourceDynamicResource XAML.
A StaticResource extensão de marcação é semelhante à DynamicResource extensão de marcação em que ambos usam uma chave de dicionário para fazer referência a um valor de um dicionário de recursos. No entanto, enquanto a extensão de marcação executa uma única pesquisa de dicionário, a extensão de marcação mantém um link para a StaticResourceDynamicResource chave de dicionário. Portanto, se a entrada de dicionário associada à chave for substituída, a alteração será aplicada ao elemento visual. Isso permite que alterações de recursos de tempo de execução sejam feitas em um aplicativo. Para obter mais informações sobre extensões de marcação, consulte Extensões de marcação XAML.
O exemplo XAML a seguir mostra como consumir recursos e também definir um recurso adicional em um StackLayout:
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="ResourceDictionaryDemo.MainPage"
Title="Main page">
<StackLayout Margin="{StaticResource PageMargin}"
Spacing="6">
<StackLayout.Resources>
<!-- Implicit style -->
<Style TargetType="Button">
<Setter Property="FontSize" Value="14" />
<Setter Property="BackgroundColor" Value="#1976D2" />
<Setter Property="TextColor" Value="White" />
<Setter Property="CornerRadius" Value="5" />
</Style>
</StackLayout.Resources>
<Label Text="This app demonstrates consuming resources that have been defined in resource dictionaries." />
<Button Text="Navigate"
Clicked="OnNavigateButtonClicked" />
</StackLayout>
</ContentPage>
Neste exemplo, o objeto consome o ContentPage estilo implícito definido no dicionário de recursos no nível do aplicativo. O StackLayout objeto consome o recurso definido no dicionário de recursos no nível do aplicativo, enquanto o objeto consome o PageMarginButton estilo implícito definido no dicionário de StackLayout recursos. Isso resulta na aparência mostrada na captura de tela a seguir:
Importante
Os recursos específicos de uma única página não devem ser incluídos em um dicionário de recursos no nível do aplicativo, pois esses recursos serão analisados na inicialização do aplicativo em vez de quando exigido por uma página. Para obter mais informações, consulte Reduzir o tamanho do dicionário de recursos do aplicativo.
Comportamento de pesquisa de recursos
O processo de pesquisa a seguir ocorre quando um recurso é referenciado com a StaticResource extensão de marcação ou DynamicResource :
- A chave solicitada é verificada no dicionário de recursos, se existir, para o elemento que define a propriedade. Se a chave solicitada for encontrada, seu valor será retornado e o processo de pesquisa será encerrado.
- Se uma correspondência não for encontrada, o processo de pesquisa pesquisará a árvore visual para cima, verificando o dicionário de recursos de cada elemento pai. Se a chave solicitada for encontrada, seu valor será retornado e o processo de pesquisa será encerrado. Caso contrário, o processo continua para cima até que o elemento raiz seja alcançado.
- Se uma correspondência não for encontrada no elemento raiz, o dicionário de recursos no nível do aplicativo será examinado.
- Se uma correspondência ainda não for encontrada, uma
XamlParseExceptionserá lançada.
Portanto, quando o analisador XAML encontra uma extensão de marcação ou DynamicResource marcação, ele procura uma StaticResource chave correspondente viajando pela árvore visual, usando a primeira correspondência encontrada. Se essa pesquisa terminar na página e a chave ainda não tiver sido encontrada, o analisador XAML pesquisará o anexado ResourceDictionaryApp ao objeto. Se a chave ainda não for encontrada, uma exceção será lançada.
Substituir recursos
Quando os recursos compartilham chaves, os recursos definidos mais abaixo na árvore visual terão precedência sobre os definidos mais acima. Por exemplo, a definição de um recurso para AliceBlue no nível do aplicativo será substituída por um recurso de nível AppBackgroundColor de AppBackgroundColor página definido como Teal. Da mesma forma, um recurso de nível AppBackgroundColor de página será substituído por um recurso de layout ou nível AppBackgroundColor de exibição.
Dicionários de recursos autônomos
Um ResourceDictionary também pode ser criado como um arquivo XAML autônomo que não é apoiado por um arquivo code-behind. Para criar um autônomo, adicione um novo ResourceDictionary arquivo ao projeto com o modelo de ResourceDictionaryitem .NET MAUI ResourceDictionary (XAML) e exclua seu arquivo code-behind. Em seguida, no arquivo XAML, remova o x:ClassResourceDictionary atributo da marca perto do início do arquivo. Além disso, adicione <?xaml-comp compile="true" ?> após o cabeçalho XML para garantir que o XAML será compilado.
Observação
Um autônomo deve ter uma ação de ResourceDictionary compilação de MauiXaml.
O exemplo XAML a ResourceDictionary seguir mostra um autônomo chamado MyResourceDictionary.xaml:
<?xml version="1.0" encoding="UTF-8" ?>
<?xaml-comp compile="true" ?>
<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">
<DataTemplate x:Key="PersonDataTemplate">
<ViewCell>
<Grid RowSpacing="6"
ColumnSpacing="6">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="0.5*" />
<ColumnDefinition Width="0.2*" />
<ColumnDefinition Width="0.3*" />
</Grid.ColumnDefinitions>
<Label Text="{Binding Name}"
TextColor="{StaticResource NormalTextColor}"
FontAttributes="Bold" />
<Label Grid.Column="1"
Text="{Binding Age}"
TextColor="{StaticResource NormalTextColor}" />
<Label Grid.Column="2"
Text="{Binding Location}"
TextColor="{StaticResource NormalTextColor}"
HorizontalTextAlignment="End" />
</Grid>
</ViewCell>
</DataTemplate>
</ResourceDictionary>
Neste exemplo, o ResourceDictionary contém um único recurso, que é um objeto do tipo DataTemplate. MyResourceDictionary.xaml pode ser consumido mesclando-o em outro dicionário de recursos.
Mesclar dicionários de recursos
Os dicionários de recursos podem ser combinados mesclando um ou mais ResourceDictionary objetos em outro ResourceDictionary.
Mesclar dicionários de recursos locais
Um arquivo local ResourceDictionary pode ser mesclado em outro ResourceDictionary criando um ResourceDictionary objeto cuja Source propriedade é definida como o nome do arquivo XAML com os recursos:
<ContentPage ...>
<ContentPage.Resources>
<!-- Add more resources here -->
<ResourceDictionary Source="MyResourceDictionary.xaml" />
<!-- Add more resources here -->
</ContentPage.Resources>
...
</ContentPage>
Essa sintaxe não instancia a MyResourceDictionary classe. Em vez disso, ele faz referência ao arquivo XAML. Por esse motivo, ao definir a Source propriedade, um arquivo code-behind não é necessário e o x:Class atributo pode ser removido da marca raiz do arquivo MyResourceDictionary.xaml .
Importante
A ResourceDictionary.Source propriedade só pode ser definida a partir de XAML.
Mesclar dicionários de recursos de outros assemblies
Um ResourceDictionary também pode ser mesclado em outro ResourceDictionary , adicionando-o MergedDictionaries à propriedade do ResourceDictionary. Essa técnica permite que os dicionários de recursos sejam mesclados, independentemente do assembly em que residem. A mesclagem de dicionários de recursos de assemblies externos requer que o tenha uma ação de compilação definida como MauiXaml, tenha um arquivo code-behind e defina o ResourceDictionaryx:Class atributo na marca raiz do arquivo.
Aviso
A classe ResourceDictionary também define uma propriedade MergedWith. No entanto, essa propriedade foi preterida e não deve mais ser usada.
O exemplo de código a MergedDictionaries seguir mostra dois dicionários de recursos sendo adicionados à coleção de um nível ResourceDictionaryde página:
<ContentPage ...
xmlns:local="clr-namespace:ResourceDictionaryDemo"
xmlns:theme="clr-namespace:MyThemes;assembly=MyThemes">
<ContentPage.Resources>
<ResourceDictionary>
<!-- Add more resources here -->
<ResourceDictionary.MergedDictionaries>
<!-- Add more resource dictionaries here -->
<local:MyResourceDictionary />
<theme:DefaultTheme />
<!-- Add more resource dictionaries here -->
</ResourceDictionary.MergedDictionaries>
<!-- Add more resources here -->
</ResourceDictionary>
</ContentPage.Resources>
...
</ContentPage>
Neste exemplo, um dicionário de recursos do mesmo assembly e um dicionário de recursos de um assembly externo são mesclados no dicionário de recursos no nível da página. Além disso, você também pode adicionar outros objetos dentro das MergedDictionaries tags property-element e outros ResourceDictionary recursos fora dessas tags.
Importante
Pode haver apenas uma MergedDictionaries marca de elemento de propriedade em um ResourceDictionary, mas você pode colocar quantos ResourceDictionary objetos forem necessários.
Quando os recursos mesclados ResourceDictionary compartilham valores de atributo idênticos, o .NET MAUI usa a seguinte precedência de x:Key recurso:
- Os recursos locais para o dicionário de recursos.
- Os recursos contidos nos dicionários de recursos que foram mesclados por meio da
MergedDictionariescoleção, na ordem inversa, eles são listados naMergedDictionariespropriedade.
Dica
Pesquisar dicionários de recursos pode ser uma tarefa computacionalmente intensiva se um aplicativo contiver vários dicionários de recursos grandes. Portanto, para evitar pesquisas desnecessárias, você deve garantir que cada página em um aplicativo use apenas dicionários de recursos apropriados para a página.
Consumir um dicionário de recursos baseado em XAML a partir do código
Os dicionários de recursos definidos em XAML podem ser consumidos em código, desde que o ResourceDictionary seja apoiado por um arquivo code-behind. No Visual Studio, arquivos baseados em ResourceDictionary XAML que são apoiados por arquivos code-behind podem ser adicionados ao seu projeto pelo modelo de item .NET MAUI ResourceDictionary (XAML):
Dicionários de recursos baseados em XAML que são apoiados por arquivos code-behind podem ser consumidos do C# adicionando-os à MergedDictionaries coleção do dicionário de recursos:
Resources.MergedDictionaries.Add(new MyMauiApp.Resources.Styles.MyColors());
Resources.MergedDictionaries.Add(new MyMauiApp.Resources.Styles.MyStyles());
Acessar recursos por chave a partir do código
Você pode acessar recursos em um dicionário de recursos a partir do código como qualquer outro dicionário.
O exemplo a seguir mostra como recuperar e aplicar um recurso do dicionário de recursos de uma página:
// Retrieve the Primary color value which is in the page's resource dictionary
var hasValue = Resources.TryGetValue("Primary", out object primaryColor);
if (hasValue)
{
myLabel.TextColor = (Color)primaryColor;
}
Essa é a abordagem recomendada que garante que o .NET MAUI não lance um se não for possível recuperar um KeyNotFoundException recurso do código. Isso pode ocorrer quando um dicionário de recursos mesclado é composto de recursos definidos em um arquivo XAML e recursos embutidos. Para obter mais informações, consulte o problema #11214 do GitHub.
Observação
Para recuperar recursos de todo o aplicativo a partir do código, acesse o App.Current.Resources dicionário de recursos.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de