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

  • Article

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

Prérequis

Avant de lire cet article, il est important que vous connaissiez 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 couvre pas les concepts de liaison de données. Pour une discussion sur les concepts de liaison de données, consultez la vue d’ensemble de 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 Value, où Name est le nom de la Binding propriété et Value 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 propriétés et Path les Source propriétés.

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

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

Syntaxe de l’é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, il n’existe aucun avantage particulier à utiliser l’extension de balisage ou la syntaxe de l’élément objet. Toutefois, lorsque l’extension de balisage ne prend pas en charge votre scénario, par exemple lorsque la valeur de votre propriété est d’un type non chaîne pour lequel aucune conversion de type n’existe, vous devez utiliser la syntaxe de l’élément objet.

La section précédente a montré comment établir une liaison avec une extension XAML. L’exemple suivant illustre l’exécution de la même liaison, mais utilise la syntaxe de l’é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 La 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 pourquoi vous devez utiliser la syntaxe de l’élément objet si vous déclarez un MultiBinding ou un PriorityBinding élément 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 à affecter 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 définit ce qui suit 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 d’être affecté à la propriété cible.

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

L’exemple précédent utilise un type d’objet de données simple de Person. 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 à lier à :

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

  • Les sous-propriétés d’une propriété peuvent être spécifiées par une syntaxe similaire comme en 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 établir une liaison à la propriété DockPanel.Dockjointe, 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 actif 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.

  • Si vous le souhaitez, 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

  • À l’intérieur des indexeurs ([ ]), le caractère d’insertion (^) échappe au caractère suivant.

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

    • Permet &amp; d’échapper au caractère «& ».

    • Permet &gt; d’é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 d’une barre oblique inverse \) des caractères spéciaux à 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 la direction de la liaison. Les modes suivants sont les options disponibles pour les mises à jour de liaison :

Mode de liaison Description
BindingMode.TwoWay Mises à jour la propriété cible ou la propriété chaque fois que la propriété cible ou la propriété source change.
BindingMode.OneWay Mises à jour la propriété cible uniquement lorsque la propriété source change.
BindingMode.OneTime Mises à jour la propriété cible uniquement lorsque l’application démarre ou quand elle DataContext subit une modification.
BindingMode.OneWayToSource Met à jour la propriété source quand la propriété cible change.
BindingMode.Default Provoque 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 sources (applicables aux liaisons OneWay 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 Fournir des notifications de modification.

Pour TwoWay ou OneWayToSource liaisons, vous pouvez contrôler le minutage des mises à jour sources 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 ConverterCulturepas, le moteur de liaison utilise la Language propriété de l’objet cible de liaison. En XAML, cette valeur par défaut en-US est ou hérite de la valeur de l’élément racine (ou d’un élément) de la page, si une valeur a été définie explicitement.

  • Tant que la liaison possède 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é par ce contexte est approprié pour la liaison sans nécessiter de modification de chemin d’accès supplémentaire, une déclaration de liaison ne peut avoir aucune clause du tout : {Binding} Il s’agit souvent de la façon 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 entre une méthode unidirectionnelle et bidirectionnelle en fonction de la propriété de dépendance liée. 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, par défaut, les liaisons bidirectionnelle, mais la plupart des autres propriétés sont par défaut des liaisons unidirectionnelle.

  • La valeur par défaut UpdateSourceTrigger varie entre PropertyChanged et LostFocus dépend également 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