Panoramica delle proprietà associate

2025-06-10

Una proprietà collegata è un concetto XAML. Le proprietà associate consentono l'impostazione di coppie proprietà/valore aggiuntive su un oggetto, ma le proprietà non fanno parte della definizione dell'oggetto originale. Le proprietà associate vengono in genere definite come una forma specializzata di proprietà di dipendenza che non dispone di un wrapper di proprietà convenzionale nel modello a oggetti del tipo proprietario.

Prerequisiti

Si presuppone che l'utente comprenda il concetto di base delle proprietà di dipendenza e abbia letto Panoramica delle proprietà di dipendenza.

Proprietà associate in XAML

In XAML le proprietà associate vengono impostate usando la sintassi AttachedPropertyProvider.PropertyName. Ecco un esempio di come impostare Canvas.Left in XAML.

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

Annotazioni

Stiamo solo usando Canvas.Left come proprietà associata di esempio senza spiegare completamente il motivo per cui si dovrebbe usarlo. Se desideri sapere di più su Canvas.Left e su come Canvas gestisce gli elementi figlio nel layout, vedere l'argomento di riferimento Canvas o Definire layout con XAML.

Perché usare le proprietà associate?

Le proprietà associate sono un modo per superare le convenzioni di programmazione che possono impedire a oggetti diversi in una relazione di comunicare le informazioni tra loro durante l'esecuzione. È certamente possibile inserire proprietà su una classe base comune in modo che ogni oggetto possa semplicemente ottenere e impostare tale proprietà. Ma alla fine, l'enorme numero di scenari in cui si potrebbe voler eseguire questa operazione gonfierà le vostre classi di base con proprietà condivisibili. Potrebbe anche introdurre casi in cui solo due tra centinaia di discendenti tentano di usare una proprietà. Questo non è un buon design di classe. Per risolvere questo problema, il concetto di proprietà associata consente a un oggetto di assegnare un valore per una proprietà che non definisce la propria struttura di classi. La classe che definisce può leggere il valore dagli oggetti figlio in fase di esecuzione dopo la creazione dei vari oggetti in un albero di oggetti.

Ad esempio, gli elementi figlio possono usare proprietà associate per informare l'elemento padre di come devono essere presentati nell'interfaccia utente. Questo è il caso della proprietà allegata Canvas.Left. Canvas.Left viene creato come proprietà associata perché è impostato su elementi contenuti all'interno di un elemento Canvas, anziché sul Canvas stesso. Qualsiasi possibile elemento figlio usa quindi Canvas.Left e Canvas.Top per specificare l'offset di layout all'interno dell'elemento padre del contenitore di layout Canvas. Le proprietà associate rendono possibile il funzionamento senza appesantire il modello a oggetti dell'elemento di base con numerose proprietà, ciascuna delle quali si applica solo a uno dei tanti possibili contenitori di layout. Molti dei contenitori di layout implementano invece il proprio set di proprietà associate.

Per implementare la proprietà associata, la classe Canvas definisce un campo statico DependencyProperty denominato Canvas.LeftProperty. Quindi, Canvas fornisce i metodi SetLeft e GetLeft come funzioni di accesso pubbliche per la proprietà associata, per abilitare di impostare XAML e accedere ai valori a runtime. Per XAML e per il sistema di proprietà di dipendenza, questo set di API soddisfa un modello che abilita una sintassi XAML specifica per le proprietà associate e archivia il valore nell'archivio delle proprietà di dipendenza.

Come il tipo proprietario utilizza le proprietà associate

Anche se le proprietà associate possono essere impostate su qualsiasi elemento XAML (o su qualsiasi DependencyObject), ciò non significa automaticamente che l'impostazione della proprietà produca un risultato tangibile o che il valore venga mai utilizzato. Il tipo che definisce la proprietà associata segue in genere uno di questi scenari:

Il tipo che definisce la proprietà associata è l'elemento padre in una relazione di altri oggetti. Gli oggetti figlio impostano i valori per la proprietà collegata. Il tipo di proprietario della proprietà allegata ha un comportamento innato che itera attraverso i suoi elementi figlio, ottiene i valori e agisce su tali valori a un certo punto nel ciclo di vita dell'oggetto (un'azione di layout, SizeChangede così via)
Il tipo che definisce la proprietà associata viene usato come elemento figlio per un'ampia gamma di possibili elementi padre e modelli di contenuto, ma le informazioni non sono necessariamente informazioni di layout.
La proprietà associata segnala informazioni a un servizio, non a un altro elemento dell'interfaccia utente.

Per ulteriori informazioni su questi scenari e tipi di titolarità, vedi la sezione "Altre informazioni su Canvas.Left" di Proprietà associate personalizzate.

Proprietà associate nel codice

Le proprietà associate non hanno i wrapper di proprietà tipici per ottenere e impostare facilmente l'accesso come altre proprietà di dipendenza. Ciò è dovuto al fatto che la proprietà associata non fa necessariamente parte del modello a oggetti centrato sul codice per le istanze in cui è impostata la proprietà. È consentito, anche se non comune, definire una proprietà che sia sia una proprietà associata, che altri tipi possono impostare su se stessi, sia una proprietà con un utilizzo convenzionale nel tipo proprietario.

Esistono due modi per impostare una proprietà associata nel codice: usare le API del sistema delle proprietà o usare le funzioni di accesso del modello XAML. Queste tecniche sono praticamente equivalenti in termini di risultato finale, quindi quello da usare è principalmente una questione di stile di codifica.

Utilizzo del sistema di attributi

Le proprietà associate per Windows Runtime vengono implementate come proprietà di dipendenza, in modo che i valori possano essere archiviati nell'archivio delle proprietà di dipendenza condiviso dal sistema di proprietà. Di conseguenza, le proprietà associate espongono un identificatore di proprietà di dipendenza nella classe proprietaria.

Per impostare una proprietà associata nel codice, chiamare il metodo SetValue e passare il campo DependencyProperty che funge da identificatore per tale proprietà associata. Devi anche passare il valore da impostare.

Per ottenere il valore di una proprietà associata nel codice, chiamare il metodo GetValue , passando di nuovo il campo DependencyProperty che funge da identificatore.

Uso del modello di accesso XAML

Un processore XAML deve essere in grado di impostare i valori delle proprietà associate quando XAML viene analizzato in un albero di oggetti. Il tipo di proprietario della proprietà associata deve implementare metodi di accesso dedicati denominati nel formato GetPropertyName e SetPropertyName. Questi metodi di accesso dedicati sono anche un modo per ottenere o impostare la proprietà associata nel codice. Dal punto di vista del codice, una proprietà associata è simile a un campo sottostante con funzioni di accesso al metodo anziché funzioni di accesso alle proprietà e tale campo sottostante può esistere in qualsiasi oggetto anziché dover essere definito in modo specifico.

L'esempio seguente illustra come impostare una proprietà associata nel codice tramite l'API accessor XAML. In questo esempio, myCheckBox è un'istanza della classe CheckBox. L'ultima riga è il codice che imposta effettivamente il valore; le righe precedenti si limitano a stabilire le istanze e la loro relazione padre-figlio. L'ultima riga non commentata è la sintassi se si usa il sistema di proprietà. L'ultima riga commentata rappresenta la sintassi se si utilizza il pattern di accesso 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);

Proprietà associate personalizzate

Per esempi di codice su come definire proprietà associate personalizzate e altre informazioni sugli scenari per l'uso di una proprietà associata, vedere Proprietà associate personalizzate.

Sintassi speciale per i riferimenti alle proprietà associate

Il punto in un nome di proprietà associato è una parte chiave del modello di identificazione. A volte ci sono ambiguità quando una sintassi o una situazione considera il punto come avere un altro significato. Ad esempio, un punto viene considerato come attraversamento del modello a oggetti per un percorso di associazione. Nella maggior parte dei casi che coinvolgono tale ambiguità, esiste una sintassi speciale per una proprietà associata che consente l'analisi del punto interno come proprietario .proprietà separatore di una proprietà associata.

Per specificare una proprietà associata come parte di un percorso di destinazione per un'animazione, racchiudere il nome della proprietà associata tra parentesi ("()"), ad esempio "(Canvas.Left)". Per ulteriori informazioni, vedere sintassi del property-path.

Avvertimento

Una limitazione esistente dell'implementazione XAML di Windows Runtime è che non è possibile animare una proprietà associata personalizzata.

Per specificare una proprietà associata come proprietà di destinazione per un riferimento a una risorsa da un file di risorse a x:Uid, usa una sintassi speciale che inserisce una dichiarazione nello stile del codice, completamente qualificata utilizzando: all'interno di parentesi quadre ("[]"), per creare deliberatamente un'interruzione di ambito. Si supponga, ad esempio, che esista un elemento <TextBlock x:Uid="Title" />, la chiave di risorsa nel file di risorse destinata al valore Canvas.Top in tale istanza è "Title. [using:Windows.UI.Xaml.Controls]Canvas.Top". Per altre info sui file di risorse e su XAML, vedi Avvio rapido: Traduzione delle risorse dell'interfaccia utente.