Liaisons de secours

Parcourir l'exemple

Une liaison de données échoue parfois car la source de la liaison ne peut pas être résolue ou parce que la liaison réussit mais retourne une valeur null. De tels scénarios peuvent être gérés avec des convertisseurs de valeurs ou du code supplémentaire, mais il est possible de renforcer les liaisons de données en définissant des valeurs de repli à utiliser si le processus de liaison échoue. Dans une application .NET Multi-Platform App UI (.NET MAUI), vous pouvez le faire en définissant les propriétés FallbackValue et TargetNullValue dans une expression de liaison. Comme ces propriétés résident dans la classe BindingBase, elles peuvent être utilisées avec des liaisons, des liaisons multiples, des liaisons compilées et l’extension de balisage Binding.

Remarque

L’utilisation des propriétés FallbackValue et TargetNullValue dans une expression de liaison est facultative.

Définir une valeur de secours

La propriété FallbackValue permet de définir une valeur de repli à utiliser si la source de la liaison ne peut pas être résolue. Un scénario courant pour définir cette propriété est lors d’une liaison à des propriétés de source qui n’existent peut-être pas sur tous les objets d’une collection liée de types hétérogènes.

L’exemple suivant illustre la définition de la propriété FallbackValue :

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

La liaison sur l’objet Label définit une valeur FallbackValue (délimitée par des guillemets simples) qui sera définie sur la cible si la source de la liaison ne peut pas être résolue. Par conséquent, la valeur définie par la propriété FallbackValue s’affiche si la propriété Population n’existe pas sur l’objet lié.

Au lieu de définir des valeurs de propriété FallbackValue incluses, il est recommandé de les définir en tant que ressources dans un ResourceDictionary. L’avantage de cette approche est que ces valeurs sont définies une seule fois dans un emplacement unique et sont plus facilement localisables. Les ressources peuvent ensuite être récupérées à l’aide de l’extension de balisage StaticResource :

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

Remarque

Il n’est pas possible de définir la propriété FallbackValue avec une expression de liaison.

Lorsque la propriété FallbackValue n’est pas définie dans une expression de liaison et que le chemin de liaison ou une partie de ce chemin n’est pas résolu(e), BindableProperty.DefaultValue est défini sur la cible. Toutefois, lorsque la propriété FallbackValue est définie et que le chemin de liaison ou une partie de ce chemin n’est pas résolu(e), la valeur de la propriété FallbackValue est définie sur la cible :

Par conséquent, dans cet exemple, le Label affiche « Population size unknown » (Taille de la population inconnue), car l’objet lié n’a pas de propriété Population.

Important

Un convertisseur de valeurs défini n’est pas exécuté dans une expression de liaison lorsque la propriété FallbackValue est définie.

Définir une valeur de remplacement null

La propriété TargetNullValue permet de définir une valeur de remplacement à utiliser si la source de la liaison est résolue mais que la valeur est null. Un scénario courant pour définir cette propriété est lors d’une liaison à des propriétés de source qui peuvent être null dans une collection liée.

L’exemple suivant illustre la définition de la propriété 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>

Les liaisons sur Image et Label définissent toutes les deux des valeurs TargetNullValue (délimitée par des guillemets simples) qui seront appliquées si le chemin de liaison retourne null. Par conséquent, les valeurs définies par les propriétés TargetNullValue seront affichées pour tous les objets dans la collection où les propriétés ImageUrl et Location ne sont pas définies.

Au lieu de définir des valeurs de propriété TargetNullValue incluses, il est recommandé de les définir en tant que ressources dans un ResourceDictionary. L’avantage de cette approche est que ces valeurs sont définies une seule fois dans un emplacement unique et sont plus facilement localisables. Les ressources peuvent ensuite être récupérées à l’aide de l’extension de balisage StaticResource :

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

Remarque

Il n’est pas possible de définir la propriété TargetNullValue avec une expression de liaison.

Lorsque la propriété TargetNullValue n’est pas définie dans une expression de liaison, une valeur source null est convertie si un convertisseur de valeurs est défini, formatée si un StringFormat est défini, et le résultat est ensuite défini sur la cible. Toutefois, lorsque la propriété TargetNullValue est définie, une valeur source null est convertie si un convertisseur de valeurs est défini, et si elle est encore null après la conversion, la valeur de la propriété TargetNullValue est définie sur la cible.

Par conséquent, dans cet exemple, les objets Image et Label affichent leur TargetNullValue lorsque leurs objets sources sont null.

Important

Le formatage de chaîne n’est pas appliqué dans une expression de liaison lorsque la propriété TargetNullValue est définie.

Comparaison TargetNullValue et FallbackValue

Les propriétés TargetNullValue et FallbackValue sont toutes les deux utilisées dans les liaisons de données pour gérer les scénarios où la valeur liée est null ou lorsque la liaison échoue. Savoir quand utiliser chacune des propriétés permet de garantir une expérience utilisateur fluide.

TargetNullValue

Utilisez la propriété TargetNullValue pour spécifier une valeur à afficher lorsque la liaison réussit, mais que la propriété liée est null :

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

Dans cet exemple, si FirstName est null, le Label affiche « No name available » (Aucun nom disponible).

FallbackValue

Utilisez la propriété FallbackValue pour fournir une valeur lorsque le processus de liaison échoue entièrement, par exemple en cas de chemin d’accès incorrect ou de contexte de liaison manquant :

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

Dans cet exemple, si la liaison échoue, le Label affiche « Binding failed » (Échec de la liaison).

Utilisation combinée

Les propriétés TargetNullValue et FallbackValue peuvent être combinées dans une expression de liaison unique :

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