Vue d’ensemble des déclarations de liaison (WPF .NET)

En général, les développeurs déclarent les liaisons directement dans le balisage XAML des éléments d’interface utilisateur auxquels ils veulent lier des données. Toutefois, vous pouvez également déclarer des liaisons dans le code. Cet article explique comment déclarer des liaisons dans XAML et dans le code.

Prérequis

Avant de lire cet article, il est important que vous soyez familiarisé avec le concept et l’utilisation des extensions de balisage. Pour plus d’informations sur les extensions de balisage, consultez Extensions de balisage et XAML WPF.

Cet article ne traite pas des concepts de liaison de données. Pour plus d’informations sur les concepts de liaison de données, consultez vue d’ensemblede la liaison de données.

Déclarer une liaison en XAML

Binding est une extension de balisage. Lorsque vous utilisez l’extension de liaison pour déclarer une liaison, la déclaration se compose d’une série de clauses suivant le mot-clé Binding et séparées par des virgules (,). Les clauses dans la déclaration de liaison peuvent être dans n’importe quel ordre et il existe de nombreuses combinaisons possibles. Les clauses sont des paires nom= -valeur , où nom est le nom de la Binding propriété et valeur est la valeur que vous définissez pour la propriété.

Lorsque vous créez des chaînes de déclaration de liaison dans le balisage, elles doivent être jointes à la propriété de dépendance spécifique d’un objet cible. L’exemple suivant montre comment lier la TextBox.Text propriété à l’aide de l’extension de liaison, en spécifiant les Source Propriétés et Path .

<TextBlock Text="{Binding Source={StaticResource myDataSource}, Path=Name}"/>

Vous pouvez spécifier la plupart des propriétés de la Binding classe de cette manière. pour plus d’informations sur l’extension de liaison et pour obtenir la liste des propriétés qui ne peuvent pas être définies à l’aide de l’extension de liaison, consultez la vue d’ensemble de Binding l’extension de balisage de liaison (.NET Framework) .

Syntaxe d’élément objet

La syntaxe d’élément objet est une alternative à la création de la déclaration de liaison. Dans la plupart des cas, l’utilisation de l’extension de balisage ou de la syntaxe d’élément objet ne présente aucun avantage particulier. Toutefois, lorsque l’extension de balisage ne prend pas en charge votre scénario, par exemple lorsque la valeur de votre propriété est un type autre qu’une chaîne pour laquelle aucune conversion de type n’existe, vous devez utiliser la syntaxe d’élément objet.

La section précédente a montré comment effectuer une liaison avec une extension XAML. L’exemple suivant illustre l’utilisation de la même liaison, mais utilise la syntaxe d’élément objet :

<TextBlock>
    <TextBlock.Text>
        <Binding Source="{StaticResource myDataSource}" Path="Name"/>
    </TextBlock.Text>
</TextBlock>

Pour plus d’informations sur les différents termes, consultez syntaxe XAML en détail (.NET Framework).

MultiBinding et PriorityBinding

MultiBinding et PriorityBinding ne prennent pas en charge la syntaxe d’extension XAML. C’est la raison pour laquelle vous devez utiliser la syntaxe d’élément objet si vous déclarez un MultiBinding ou un PriorityBinding en XAML.

Créer une liaison dans du code

Une autre façon de spécifier une liaison consiste à définir des propriétés directement sur un Binding objet dans le code, puis d’assigner la liaison à une propriété. L’exemple suivant montre comment créer un Binding objet dans le code.

private void Window_Loaded(object sender, RoutedEventArgs e)
{
    // Make a new data source object
    var personDetails = new Person()
    {
        Name = "John",
        Birthdate = DateTime.Parse("2001-02-03")
    };

    // New binding object using the path of 'Name' for whatever source object is used
    var nameBindingObject = new Binding("Name");

    // Configure the binding
    nameBindingObject.Mode = BindingMode.OneWay;
    nameBindingObject.Source = personDetails;
    nameBindingObject.Converter = NameConverter.Instance;
    nameBindingObject.ConverterCulture = new CultureInfo("en-US");

    // Set the binding to a target object. The TextBlock.Name property on the NameBlock UI element
    BindingOperations.SetBinding(NameBlock, TextBlock.TextProperty, nameBindingObject);
}
Private Sub Window_Loaded(sender As Object, e As RoutedEventArgs)

    ' Make a new data source object
    Dim personDetails As New Person() With {
        .Name = "John",
        .Birthdate = Date.Parse("2001-02-03")
    }

    ' New binding object using the path of 'Name' for whatever source object is used
    Dim nameBindingObject As New Binding("Name")

    ' Configure the binding
    nameBindingObject.Mode = BindingMode.OneWay
    nameBindingObject.Source = personDetails
    nameBindingObject.Converter = NameConverter.Instance
    nameBindingObject.ConverterCulture = New CultureInfo("en-US")

    ' Set the binding to a target object. The TextBlock.Name property on the NameBlock UI element
    BindingOperations.SetBinding(NameBlock, TextBlock.TextProperty, nameBindingObject)

End Sub

Le code précédent a défini les éléments suivants sur la liaison :

  • Chemin d’accès de la propriété sur l’objet source de données.
  • Mode de la liaison.
  • La source de données, dans ce cas, une instance d’objet simple représentant une personne.
  • Convertisseur facultatif qui traite la valeur entrante à partir de l’objet source de données avant qu’elle ne soit assignée à la propriété cible.

Lorsque l’objet que vous liez est FrameworkElement ou FrameworkContentElement , vous pouvez appeler la SetBinding méthode sur votre objet directement au lieu d’utiliser BindingOperations.SetBinding . Pour obtenir un exemple, consultez Comment : créer une liaison dans le code.

L’exemple précédent utilise un type d’objet de Person données simple. Voici le code de cet objet :

class Person
{
    public string Name { get; set; }
    public DateTime Birthdate { get; set; }
}
Public Class Person

    Public Property Name As String
    Public Property Birthdate As DateTime
    
End Class

Syntaxe du chemin de liaison

Utilisez la Path propriété pour spécifier la valeur source que vous souhaitez lier :

  • Dans le cas le plus simple, la Path valeur de propriété est le nom de la propriété de l’objet source à utiliser pour la liaison, telle que Path=PropertyName .

  • Les sous-propriétés d’une propriété peuvent être spécifiées à l’aide d’une syntaxe similaire à celle de C#. Par exemple, la clause Path=ShoppingCart.Order définit la liaison à la sous-propriété Order de l’objet ou la propriété ShoppingCart.

  • Pour lier à une propriété jointe, placez des parenthèses autour de la propriété. Par exemple, pour effectuer une liaison à la propriété DockPanel.Dock jointe, la syntaxe est Path=(DockPanel.Dock) .

  • Des indexeurs de propriété peuvent être spécifiés entre crochets après le nom de la propriété où l’indexeur est appliqué. Par exemple, la clause Path=ShoppingCart[0] définit la liaison à l’index qui correspond à la façon dont l’indexation interne de votre propriété gère la chaîne littérale « 0 ». Les indexeurs imbriqués sont également pris en charge.

  • Les indexeurs et les sous-propriétés peuvent être combinés en une clause Path ; par exemple, Path=ShoppingCart.ShippingInfo[MailingAddress,Street].

  • À l’intérieur des indexeurs. Vous pouvez avoir plusieurs paramètres d’indexeur séparés par des virgules ( , ). Le type de chaque paramètre peut être spécifié avec des parenthèses. Par exemple, vous pouvez avoir Path="[(sys:Int32)42,(sys:Int32)24]", où sys est mappé à l’espace de noms System.

  • Lorsque la source est une vue de collection, l’élément actuel peut être spécifié avec une barre oblique ( / ). Par exemple, la clause Path=/ définit la liaison à l’élément actuel dans la vue. Lorsque la source est une collection, cette syntaxe spécifie l’élément actuel de la vue de collection par défaut.

  • Les barres obliques et les noms de propriété peuvent être combinés pour parcourir les propriétés qui sont des collections. Par exemple, Path=/Offices/ManagerName spécifie l’élément actuel de la collection source, qui contient une propriété Offices qui est également une collection. Son élément actuel est un objet qui contient une propriété ManagerName.

  • Éventuellement, un chemin d’accès de point ( . ) peut être utilisé pour établir une liaison à la source actuelle. Par exemple, Text="{Binding}" équivaut à Text="{Binding Path=.}".

Mécanisme d’échappement

  • Dans les indexeurs ( [ ] ), le signe insertion ( ^ ) échappe le caractère suivant.

  • Si vous définissez Path en XAML, vous devez également échapper (à l’aide d’entités XML) certains caractères qui sont spécifiques à la définition de langage XML :

    • Utilisez &amp; pour échapper le caractère « & ».

    • Utilisez &gt; pour échapper à la balise de fin « > ».

  • En outre, si vous décrivez la liaison entière dans un attribut à l’aide de la syntaxe d’extension de balisage, vous devez échapper (à l’aide de la barre oblique inverse \ ) les caractères qui sont spécifiques à l’analyseur d’extension de balisage WPF :

    • La barre oblique inverse (\) est le caractère d’échappement lui-même.

    • Le signe égal (=) sépare le nom et la valeur de la propriété.

    • La virgule (,) sépare les propriétés.

    • L’accolade fermante (}) marque la fin d’une extension de balisage.

Sens de la liaison

Utilisez la Binding.Mode propriété pour spécifier le sens de la liaison. Les modes suivants sont les options disponibles pour les mises à jour de liaison :

Mode de liaison Description
BindingMode.TwoWay Met à jour la propriété ou la propriété cible chaque fois que la propriété cible ou la propriété source change.
BindingMode.OneWay Met à jour la propriété cible uniquement lorsque la propriété source change.
BindingMode.OneTime Met à jour la propriété cible uniquement lorsque l’application démarre ou lorsque le DataContext subit une modification.
BindingMode.OneWayToSource Met à jour la propriété source quand la propriété cible change.
BindingMode.Default Entraîne l’utilisation de la valeur par défaut Mode de la propriété cible.

Pour plus d’informations, consultez l’énumération BindingMode.

L’exemple suivant montre comment définir la Mode propriété :

<TextBlock Name="IncomeText" Text="{Binding Path=TotalIncome, Mode=OneTime}" />

Pour détecter les modifications de la source (applicables aux OneWay liaisons et TwoWay ), la source doit implémenter un mécanisme de notification de modification de propriété approprié, tel que INotifyPropertyChanged . Pour plus d’informations, consultez fourniture de notifications de modifications.

Pour TwoWay les liaisons ou OneWayToSource , vous pouvez contrôler le minutage des mises à jour de la source en définissant la UpdateSourceTrigger propriété. Pour plus d’informations, consultez UpdateSourceTrigger.

Comportements par défaut

Le comportement par défaut est le suivant s’il n’est pas spécifié dans la déclaration :

  • Un convertisseur de valeur par défaut est créé pour effectuer une conversion de type entre la valeur de source de liaison et la valeur de cible de liaison. Si une conversion ne peut pas être effectuée, le convertisseur par défaut retourne null.

  • Si vous ne définissez ConverterCulture pas, le moteur de liaison utilise la Language propriété de l’objet de cible de liaison. En XAML, la valeur par défaut en-US est ou hérite de la valeur de l’élément racine (ou de tout élément) de la page, si celle-ci a été définie explicitement.

  • Tant que la liaison a déjà un contexte de données (par exemple, le contexte de données hérité provenant d’un élément parent) et quel que soit l’élément ou la collection retournés par ce contexte est approprié pour la liaison sans nécessiter de modification de chemin supplémentaire, une déclaration de liaison ne peut pas avoir de clauses : {Binding} . C’est souvent la manière dont une liaison est spécifiée pour le style des données, où la liaison agit sur une collection. Pour plus d’informations, consultez utilisation d’objets entiers comme source de liaison.

  • La valeur par défaut Mode varie en fonction de la propriété de dépendance en cours de liaison. Vous pouvez toujours déclarer explicitement le mode de liaison pour garantir que votre liaison a le comportement souhaité. En général, les propriétés de contrôle modifiables par l’utilisateur, telles que TextBox.Text et RangeBase.Value , sont par défaut des liaisons bidirectionnelles, mais la plupart des autres propriétés ont par défaut des liaisons unidirectionnelles.

  • La valeur par défaut UpdateSourceTrigger varie PropertyChangedLostFocus en fonction de la propriété de dépendance liée. La valeur par défaut de la plupart des propriétés de dépendance est PropertyChanged, tandis que celle de la propriété TextBox.Text a comme valeur par défaut LostFocus.

Voir aussi