Fallbacks de associação

Procurar no exemplo

Às vezes, as associações de dados falham porque a origem da associação não pode ser resolvida ou porque a associação tem êxito, mas retorna um valor null. Embora esses cenários possam ser manipulados com conversores de valor ou outro código adicional, as associações de dados poderão se tornar mais robustas com a definição de valores de fallback a serem usados se o processo de associação falhar. Em um aplicativo .NET MAUI (.NET Multi-platform App UI), isso pode ser feito definindo as propriedades FallbackValue e TargetNullValue em uma expressão de associação. Como essas propriedades residem na classe BindingBase, elas podem ser usadas com associações, assocoações múltiplas, associações compiladas e com a extensão de marcação Binding.

Observação

O uso das propriedades FallbackValue e TargetNullValue em uma expressão de associação é opcional.

Definição de um valor de fallback

A propriedade FallbackValue permite a definição de um valor de fallback que será usado quando a origem da associação não puder ser resolvida. Um cenário comum para definir essa propriedade é ao fazer a associação a propriedades de origem que podem não existir em todos os objetos em uma coleção associada de tipos heterogêneos.

O exemplo a seguir demonstra como definir a propriedade FallbackValue:

<Label Text="{Binding Population, FallbackValue='Population size unknown'}"
       ... />   

A associação no Label definirá um valor FallbackValue (delimitado por caracteres de aspas simples) que será definido no destino se a origem da associação não puder ser resolvida. Portanto, o valor definido pela propriedade FallbackValue será exibido se a propriedade Population não existir no objeto associado.

Em vez de definir os valores da propriedade FallbackValue de forma embutida, recomendamos defini-los como recursos em um ResourceDictionary. A vantagem dessa abordagem é que esses valores são definidos uma única vez em uma só localização e são mais facilmente localizáveis. Em seguida, os recursos podem ser recuperados usando a extensão de marcação StaticResource:

<Label Text="{Binding Population, FallbackValue={StaticResource populationUnknown}}"
       ... />  

Observação

Não é possível definir a propriedade FallbackValue com uma expressão de associação.

Quando a propriedade FallbackValue não está definida em uma expressão de associação e o caminho de associação ou parte do caminho não está resolvido, BindableProperty.DefaultValue é definido no destino. No entanto, quando a propriedade FallbackValue está definida e o caminho de associação ou parte do caminho não está resolvido, o valor da propriedade de valor FallbackValue é definido no destino:

Portanto, neste exemplo, Label exibe "Tamanho da população desconhecido", porque o objeto associado não tem uma propriedade Population.

Importante

Um conversor de valor definido não é executado em uma expressão de associação quando a propriedade FallbackValue está definida.

Definição de um valor de substituição nulo

A propriedade TargetNullValue permite a definição de um valor de substituição que será usado quando a origem da associação for resolvida, mas o valor for null. Um cenário comum para definir essa propriedade é ao associar as propriedades de origem que podem ser null em uma coleção associada.

O exemplo a seguir demonstra como definir a propriedade TargetNullValue:

<ListView ItemsSource="{Binding Monkeys}"
          ...>
    <ListView.ItemTemplate>
        <DataTemplate>
            <ViewCell>
                <Grid>
                    ...
                    <Image Source="{Binding ImageUrl, TargetNullValue='https://upload.wikimedia.org/wikipedia/commons/2/20/Point_d_interrogation.jpg'}"
                           ... />
                    ...
                    <Label Text="{Binding Location, TargetNullValue='Location unknown'}"
                           ... />
                </Grid>
            </ViewCell>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

As associações no Image e Label definem valores TargetNullValue (delimitados por caracteres de aspas simples) que serão aplicados se o caminho de associação retornar null. Portanto, os valores definidos pelas propriedades TargetNullValue serão exibidos para todos os objetos na coleção em que as propriedades ImageUrl e Location não estiverem definidas.

Em vez de definir os valores da propriedade TargetNullValue de forma embutida, recomendamos defini-los como recursos em um ResourceDictionary. A vantagem dessa abordagem é que esses valores são definidos uma única vez em uma só localização e são mais facilmente localizáveis. Em seguida, os recursos podem ser recuperados usando a extensão de marcação StaticResource:

<Image Source="{Binding ImageUrl, TargetNullValue={StaticResource fallbackImageUrl}}"
       ... />
<Label Text="{Binding Location, TargetNullValue={StaticResource locationUnknown}}"
       ... />

Observação

Não é possível definir a propriedade TargetNullValue com uma expressão de associação.

Quando a propriedade TargetNullValue não estiver definida em uma expressão de associação, um valor de origem igual a null será convertido se um conversor de valor for definido, formatado se um StringFormat for definido e o resultado será então definido no destino. No entanto, quando a propriedade TargetNullValue for definida, um valor de origem igual a null será convertido se um conversor de valor for definido e se ele ainda for null após a conversão, o valor da propriedade TargetNullValue será definido no destino:

Portanto, neste exemplo, os objetos Image e Label exibem seus TargetNullValue quando seus objetos de origem são null.

Importante

A formatação de cadeia de caracteres não é aplicada em uma expressão de associação quando a propriedade TargetNullValue está definida.

Comparação de TargetNullValue e FallbackValue

Ambos TargetNullValue e FallbackValue são usados em associações de dados para lidar com cenários em que o valor associado é null ou quando a associação falha. Saber quando usar cada um ajuda a garantir uma boa experiência de usuário.

TargetNullValue

Use a propriedade TargetNullValue para especificar um valor a ser exibido quando a associação for bem-sucedida, mas a propriedade associada for null:

<Label Text="{Binding FirstName, TargetNullValue='No name available'}" />

Neste exemplo, se FirstName for null o Label exibirá "Nenhum nome disponível".

FallbackValue

Use a propriedade FallbackValue para fornecer um valor quando o processo de associação falhar completamente, como um caminho incorreto ou um contexto de associação ausente:

<Label Text="{Binding FirstName, FallbackValue='Binding failed'}" />

Neste exemplo, se a associação falhar, o Label exibirá "Falha na associação".

Utilização combinada

As propriedades TargetNullValue e FallbackValue podem ser combinadas em uma única expressão de associação:

<Label Text="{Binding FirstName, TargetNullValue='No name available', FallbackValue='Binding failed'}" />