Partager via

Vue d’ensemble des propriétés jointes

Une propriété jointe est un concept XAML. Les propriétés jointes permettent de définir des paires propriété/valeur supplémentaires sur un objet, mais les propriétés ne font pas partie de la définition d’objet d’origine. Les propriétés attachées sont généralement définies comme une forme spécialisée de propriété dépendante qui n’a pas d'encapsulation classique dans le modèle objet du type propriétaire.

Prerequisites

Nous partons du principe que vous comprenez le concept de base des propriétés de dépendance et que vous avez lu la vue d’ensemble des propriétés de dépendance.

Propriétés jointes en XAML

En XAML, vous définissez les propriétés jointes à l’aide de la syntaxe AttachedPropertyProvider.PropertyName. Voici un exemple de définition de Canvas.Left en XAML.

<Canvas>
  <Button Canvas.Left="50">Hello</Button>
</Canvas>

Note

Nous utilisons simplement Canvas.Left comme exemple de propriété jointe sans expliquer entièrement pourquoi vous l’utiliseriez. Si vous souhaitez en savoir plus sur à quoi sert Canvas.Left et comment Canvas gère ses enfants de disposition, consultez la rubrique de référence Canvas ou Définir des mises en page avec XAML.

Pourquoi utiliser des propriétés jointes ?

Les propriétés jointes permettent d’échapper aux conventions de codage qui peuvent empêcher différents objets d’une relation de communiquer des informations entre elles au moment de l’exécution. Il est certainement possible de placer des propriétés sur une classe de base commune afin que chaque objet puisse simplement obtenir et définir cette propriété. Mais finalement, le nombre de scénarios où vous souhaiterez peut-être le faire va gonfler vos classes de base avec des propriétés partageables. Il peut même introduire des cas où il peut y avoir seulement deux centaines de descendants essayant d’utiliser une propriété. Ce n’est pas une bonne conception de classe. Pour résoudre ce problème, le concept de propriété jointe permet à un objet d’affecter une valeur pour une propriété que sa propre structure de classe ne définit pas. La classe de définition peut lire la valeur des objets enfants au moment de l’exécution après la création des différents objets dans une arborescence d’objets.

Par exemple, les éléments enfants peuvent utiliser des propriétés jointes pour informer leur élément parent de la façon dont ils doivent être présentés dans l’interface utilisateur. Il s’agit du cas de la propriété jointe Canvas.Left . Canvas.Left est créé en tant que propriété jointe, car elle est définie sur les éléments contenus dans un élément Canvas , plutôt que sur le canevas lui-même. Tout élément enfant possible utilise ensuite Canvas.Left et Canvas.Top pour spécifier son décalage de disposition dans le conteneur de disposition parent Canvas. Les propriétés jointes permettent que cela fonctionne sans encombrer le modèle objet de l’élément de base avec de nombreuses propriétés, chacune appliquée uniquement à un des nombreux conteneurs de disposition possibles. Au lieu de cela, la plupart des conteneurs de disposition implémentent leur propre jeu de propriétés jointes.

Pour implémenter la propriété jointe, la classe Canvas définit un champ DependencyProperty statique nommé Canvas.LeftProperty. Ensuite, Canvas fournit les méthodes SetLeft et GetLeft en tant qu’accesseurs publics pour la propriété jointe, afin d’activer à la fois le paramètre XAML et l’accès aux valeurs d’exécution. Pour XAML et pour le système de propriétés de dépendance, cet ensemble d’API satisfait à un modèle qui active une syntaxe XAML spécifique pour les propriétés jointes et stocke la valeur dans le magasin de propriétés de dépendance.

Comment le type propriétaire utilise les propriétés jointes

Bien que les propriétés jointes puissent être définies sur n’importe quel élément XAML (ou tout DependencyObject sous-jacent), cela ne signifie pas automatiquement que la définition de la propriété produit un résultat tangible ou que la valeur est jamais accessible. Le type qui définit la propriété jointe suit généralement l’un des scénarios suivants :

  • Le type qui définit la propriété attachée est le parent dans une relation avec d'autres objets. Les objets enfants vont définir des valeurs pour la propriété attachée. Le type de propriétaire de propriété attaché a un comportement inné qui itère par le biais de ses éléments enfants, obtient les valeurs et agit sur ces valeurs à un moment donné dans la durée de vie de l’objet (une action de disposition, SizeChanged, etc.)
  • Le type qui définit la propriété attachée est utilisé comme élément enfant pour une variété d'éléments parents et modèles de contenu possibles, mais les informations ne sont pas nécessairement des informations de mise en page.
  • La propriété jointe signale des informations à un service, et non à un autre élément d’interface utilisateur.

Pour plus d’informations sur ces scénarios et types propriétaires, consultez la section « Plus sur Canvas.Left » des propriétés jointes personnalisées.

Propriétés jointes dans le code

Les propriétés jointes n'ont pas les enveloppes de propriétés classiques permettant un accès facile comme les autres propriétés de dépendance. Cela est dû au fait que la propriété jointe ne fait pas nécessairement partie du modèle objet centré sur le code pour les instances où la propriété est définie. (Il est permis, bien que rare, de définir une propriété qui est à la fois une propriété attachée que d’autres types peuvent définir sur eux-mêmes, et qui a également un usage de propriété conventionnel sur le type propriétaire.)

Il existe deux façons de définir une propriété jointe dans le code : utiliser les API du système de propriétés ou utiliser les accesseurs de modèle XAML. Ces techniques sont assez équivalentes en termes de résultat final, de sorte qu’il s’agit principalement d’une question de style de codage.

Utilisation du système de propriétés

Les propriétés jointes pour Windows Runtime sont implémentées en tant que propriétés de dépendance, afin que les valeurs puissent être stockées dans le magasin de propriétés de dépendance partagé par le système de propriétés. Par conséquent, les propriétés attachées exposent un identificateur de propriété de dépendance dans la classe propriétaire.

Pour définir une propriété jointe dans le code, vous appelez la méthode SetValue et transmettez le champ DependencyProperty qui sert d’identificateur pour cette propriété jointe. (Vous passez également la valeur à définir.)

Pour obtenir la valeur d’une propriété jointe dans le code, vous appelez la méthode GetValue , en passant à nouveau le champ DependencyProperty qui sert d’identificateur.

Utilisation du modèle d’accesseur XAML

Un processeur XAML doit être en mesure de définir des valeurs de propriété jointes lorsque XAML est analysé dans une arborescence d’objets. Le type de propriétaire de la propriété jointe doit implémenter des méthodes d’accesseur dédiées nommées sous la forme GetPropertyName et SetPropertyName. Ces méthodes d’accesseur dédiées permettent également d’obtenir ou de définir la propriété jointe dans le code. Du point de vue du code, une propriété jointe est similaire à un champ de stockage qui a des accesseurs de méthode au lieu des accesseurs de propriété, et ce champ de stockage peut exister sur n’importe quel objet plutôt que d’avoir à être spécifiquement défini.

L’exemple suivant montre comment définir une propriété jointe dans le code via l’API d’accesseur XAML. Dans cet exemple, myCheckBox est une instance de la classe CheckBox . La dernière ligne est le code qui définit réellement la valeur ; les lignes avant cela établissent simplement les instances et leur relation parent-enfant. La dernière ligne noncommentée est la syntaxe si vous utilisez le système de propriétés. La dernière ligne commentée est la syntaxe si vous utilisez le modèle d’accesseur XAML.

    Canvas myC = new Canvas();
    CheckBox myCheckBox = new CheckBox();
    myCheckBox.Content = "Hello";
    myC.Children.Add(myCheckBox);
    myCheckBox.SetValue(Canvas.TopProperty,75);
    //Canvas.SetTop(myCheckBox, 75);

    Dim myC As Canvas = New Canvas()
    Dim myCheckBox As CheckBox= New CheckBox()
    myCheckBox.Content = "Hello"
    myC.Children.Add(myCheckBox)
    myCheckBox.SetValue(Canvas.TopProperty,75)
    ' Canvas.SetTop(myCheckBox, 75)

Canvas myC;
CheckBox myCheckBox;
myCheckBox.Content(winrt::box_value(L"Hello"));
myC.Children().Append(myCheckBox);
myCheckBox.SetValue(Canvas::TopProperty(), winrt::box_value(75));
// Canvas::SetTop(myCheckBox, 75);

    Canvas^ myC = ref new Canvas();
    CheckBox^ myCheckBox = ref new CheckBox();
    myCheckBox->Content="Hello";
    myC->Children->Append(myCheckBox);
    myCheckBox->SetValue(Canvas::TopProperty,75);
    // Canvas::SetTop(myCheckBox, 75);

Propriétés jointes personnalisées

Pour obtenir des exemples de code montrant comment définir des propriétés jointes personnalisées et plus d’informations sur les scénarios d’utilisation d’une propriété jointe, consultez Propriétés jointes personnalisées.

Syntaxe spéciale pour les références de propriétés jointes

Le point dans un nom de propriété attaché est une partie clé du modèle d’identification. Parfois, il existe des ambiguïtés lorsqu’une syntaxe ou une situation traite le point comme ayant une autre signification. Par exemple, un point est traité comme un parcours du modèle objet pour un chemin de liaison. Dans la plupart des cas impliquant une telle ambiguïté, il existe une syntaxe spéciale pour une propriété attachée qui permet l’analyse syntaxique du point interne en tant que séparateur propriétaire.propriété d’une propriété attachée.

  • Pour spécifier une propriété jointe dans le cadre d’un chemin d’accès cible pour une animation, placez le nom de la propriété jointe entre parenthèses (), par exemple (Canvas.Left). Pour plus d’informations, consultez la syntaxe property-path.

Avertissement

Une limitation existante de l’implémentation XAML Windows Runtime est que vous ne pouvez pas animer une propriété jointe personnalisée.

  • Pour spécifier une propriété jointe comme propriété cible pour une référence de ressource depuis un fichier de ressources vers x:Uid, utilisez une syntaxe spéciale qui injecte une déclaration using: entièrement qualifiée à l'intérieur de crochets (« [] ») pour créer une rupture d'étendue délibérée. Par exemple, en supposant qu’il existe un élément <TextBlock x:Uid="Title" />, la clé de ressource dans le fichier de ressources qui cible la valeur Canvas.Top sur cette instance est Title.\[using:Microsoft.UI.Xaml.Controls\]Canvas.Top. Pour plus d’informations sur les fichiers de ressources et XAML, consultez Localiser les chaînes dans votre interface utilisateur.
  • Last updated on