Panoramica delle proprietà associateAttached properties overview

Una proprietà associata è un concetto di XAML.An attached property is a XAML concept. Le proprietà associate consentono l'impostazione di ulteriori coppie proprietà/valore su un oggetto, ma non fanno parte della definizione dell'oggetto originale.Attached properties enable additional property/value pairs to be set on an object, but the properties are not part of the original object definition. Le proprietà associate in genere vengono 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.Attached properties are typically defined as a specialized form of dependency property that doesn't have a conventional property wrapper in the owner type's object model.

PrerequisitiPrerequisites

In questo argomento partiamo dal presupposto che tu conosca il concetto di base di proprietà di dipendenza e abbia letto l'argomento Panoramica delle proprietà di dipendenza.We assume that you understand the basic concept of dependency properties, and have read Dependency properties overview.

Proprietà associate in XAMLAttached properties in XAML

In XAML è possibile impostare le proprietà associate usando la sintassi ProviderProprietàAssociata. PropertyName.In XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName. Di seguito è riportato un esempio di come è possibile impostare Canvas. Left in XAML.Here is an example of how you can set Canvas.Left in XAML.

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

Nota

Si sta usando Canvas. Left come proprietà associata di esempio senza spiegare il motivo per cui si usa.We're just using Canvas.Left as an example attached property without fully explaining why you'd use it. Per altre informazioni sullo scopo di Canvas.Left e su come Canvas gestisce gli elementi figlio del layout, vedi l'articolo di riferimento su Canvas oppure Definire layout con XAML.If you want to know more about what Canvas.Left is for and how Canvas handles its layout children, see the Canvas reference topic or Define layouts with XAML.

Perché usare proprietà associate?Why use attached properties?

Le proprietà associate consentono di evitare le convenzioni di codifica che possono impedire ai vari oggetti di una relazione di scambiarsi informazioni in fase di esecuzione.Attached properties are a way to escape the coding conventions that might prevent different objects in a relationship from communicating information to each other at run time. Certamente è possibile definire proprietà su una classe base comune, affinché tutti gli oggetti possano impostarle e recuperarle.It's certainly possible to put properties on a common base class so that each object could just get and set that property. Tuttavia, a causa dell'altissimo numero di scenari in cui può essere necessario utilizzare questa tecnica, le classi base raggiungerebbero dimensioni eccessive a causa delle proprietà condivisibili.But eventually the sheer number of scenarios where you might want to do this will bloat your base classes with shareable properties. Possono addirittura venirsi a creare situazioni in cui una determinata proprietà viene usata solo da due discendenti su centinaia.It might even introduce cases where there might just be two of hundreds of descendants trying to use a property. Questa progettazione delle classi non è certo ottimale.That's not good class design. Per risolvere il problema, il concetto di proprietà associata permette a un oggetto di assegnare un valore a una proprietà che non viene definita dalla struttura della propria classe.To address this, the attached property concept enables an object to assign a value for a property that its own class structure doesn't define. La classe di definizione può leggere il valore dagli oggetti figlio in fase di esecuzione, dopo la creazione dei vari oggetti in un albero di oggetti.The defining class can read the value from child objects at run time after the various objects are created in an object tree.

Gli elementi figlio possono ad esempio usare le proprietà associate per comunicare all'elemento padre il modo in cui devono essere presentati nell'interfaccia utente.For example, child elements can use attached properties to inform their parent element of how they are to be presented in the UI. Questo è il caso della proprietà associata Canvas. Left .This is the case with the Canvas.Left attached property. La proprietà Canvas.Left viene creata come proprietà associata perché è impostata sugli elementi contenuti all'interno di un elemento Canvas invece che sull'oggetto Canvas stesso.Canvas.Left is created as an attached property because it is set on elements that are contained within a Canvas element, rather than on the Canvas itself. Tutti i possibili elementi figlio usano quindi Canvas.Left e Canvas.Top per specificare l'offset del layout all'interno dell'elemento padre del contenitore di layout Canvas.Any possible child element then uses Canvas.Left and Canvas.Top to specify its layout offset within the Canvas layout container parent. Le proprietà associate rendono possibile il funzionamento di questo scenario senza aggiungere al modello a oggetti dell'elemento base un numero eccessivo di proprietà, ognuna delle quali si applica solo a uno dei numerosi contenitori di layout possibili.Attached properties make it possible for this to work without cluttering the base element's object model with lots of properties that each apply to only one of the many possible layout containers. Al contrario molti dei contenitori di layout implementano un insieme di proprietà associate specifico.Instead, many of the layout containers implement their own attached property set.

Per implementare la proprietà associata, la classe Canvas definisce un campo DependencyProperty statico denominato Canvas.LeftProperty.To implement the attached property, the Canvas class defines a static DependencyProperty field named Canvas.LeftProperty. Successivamente, la classe Canvas fornisce i metodi SetLeft e GetLeft come funzioni di accesso pubbliche per la proprietà associata, per consentire l'accesso al valore dell'impostazione XAML e di runtime.Then, Canvas provides the SetLeft and GetLeft methods as public accessors for the attached property, to enable both XAML setting and run-time value access. Per XAML e per il sistema delle proprietà di dipendenza, questo insieme di API consente di soddisfare un modello che abilita una sintassi XAML specifica per le proprietà associate e archivia il valore nell'archivio delle proprietà di dipendenza.For XAML and for the dependency property system, this set of APIs satisfies a pattern that enables a specific XAML syntax for attached properties, and stores the value in the dependency property store.

In che modo il tipo proprietario usa le proprietà associateHow the owning type uses attached properties

Sebbene sia possibile impostare le proprietà associate su qualsiasi elemento XAML (o su qualsiasi oggetto DependencyObjectsottostante), questo non significa automaticamente che l'impostazione della proprietà produce un risultato tangibile o che si accede al valore.Although attached properties can be set on any XAML element (or any underlying DependencyObject), that doesn't automatically mean that setting the property produces a tangible result, or that the value is ever accessed. Il tipo che definisce la proprietà associata in genere si basa su uno di questi scenari:The type that defines the attached property typically follows one of these scenarios:

  • Il tipo che definisce la proprietà associata è l'oggetto padre in una relazione fra altri oggetti.The type that defines the attached property is the parent in a relationship of other objects. Gli oggetti figlio definiscono i valori per la proprietà associata.The child objects will set values for the attached property. Il tipo proprietario della proprietà associata dispone di un comportamento intrinseco, che gli consente di eseguire un'iterazione sui propri elementi figlio, ottenere i valori e utilizzare tali valori in un determinato momento del ciclo di vita dell'oggetto, ad esempio tramite un'azione sul layout, SizeChanged e così via.The attached property owner type has some innate behavior that iterates through its child elements, obtains the values, and acts on those values at some point in object lifetime (a layout action, SizeChanged, etc.)
  • Il tipo che definisce la proprietà associata viene usato come elemento figlio per numerosi elementi padre e modelli di contenuto possibili, ma le informazioni contenute non riguardano necessariamente il layout.The type that defines the attached property is used as the child element for a variety of possible parent elements and content models, but the info isn't necessarily layout info.
  • La proprietà associata fornisce informazioni a un servizio, non a un altro elemento dell'interfaccia utente.The attached property reports info to a service, not to another UI element.

Per altre info su questi scenari e sui tipi proprietari, vedi la sezione "Ulteriori informazioni su Canvas.Left" dell'argomento Proprietà associate personalizzate.For more info on these scenarios and owning types, see the "More about Canvas.Left" section of Custom attached properties.

Proprietà associate nel codiceAttached properties in code

Le proprietà associate non dispongono di wrapper di proprietà tipici per ottenere o impostare l'accesso in modo semplice come le altre proprietà di dipendenza.Attached properties don't have the typical property wrappers for easy get and set access like other dependency properties do. Infatti, la proprietà associata non è necessariamente parte del modello a oggetti basato sul codice per le istanze in cui la proprietà è impostata.This is because the attached property is not necessarily part of the code-centered object model for instances where the property is set. Sebbene sia insolito, è possibile definire una proprietà che sia una proprietà associata che altri tipi possono impostare su se stessi e che inoltre sia utilizzata in modo convenzionale sul tipo proprietario.(It is permissible, though uncommon, to define a property that is both an attached property that other types can set on themselves, and that also has a conventional property usage on the owning type.)

Una proprietà associata può essere impostata nel codice in due modi: usano le API del sistema di proprietà oppure usando le funzioni di accesso dei modelli XAML.There are two ways to set an attached property in code: use the property-system APIs, or use the XAML pattern accessors. Le due tecniche sono quasi equivalenti per quanto riguarda il risultato finale, di conseguenza la scelta della tecnica da utilizzare è perlopiù una questione di stile di codifica.These techniques are pretty much equivalent in terms of their end result, so which one to use is mostly a matter of coding style.

Utilizzo del sistema di proprietàUsing the property system

Le proprietà associate per Windows Runtime vengono implementate come proprietà di dipendenza, per cui il sistema di proprietà può archiviare i valori nell'archivio delle proprietà di dipendenza condiviso.Attached properties for the Windows Runtime are implemented as dependency properties, so that the values can be stored in the shared dependency-property store by the property system. Pertanto, le proprietà associate espongono un identificatore delle proprietà di dipendenza nella classe proprietaria.Therefore attached properties expose a dependency property identifier on the owning class.

Per impostare una proprietà associata nel codice, chiama il metodo SetValue e passa il campo DependencyProperty che funziona da identificatore per la proprietà associataTo set an attached property in code, you call the SetValue method, and pass the DependencyProperty field that serves as the identifier for that attached property. (passa anche il valore da impostare).(You also pass the value to set.)

Per ottenere il valore di una proprietà associata nel codice, chiamare il metodo GetValue , passando nuovamente il campo DependencyProperty che funge da identificatore.To get the value of an attached property in code, you call the GetValue method, again passing the DependencyProperty field that serves as the identifier.

Utilizzo del modello della funzione di accesso XAMLUsing the XAML accessor pattern

Un processore XAML deve essere in grado di impostare i valori delle proprietà associate quando il codice XAML viene analizzato in un albero di oggetti.A XAML processor must be able to set attached property values when XAML is parsed into an object tree. Il tipo proprietario della proprietà associata deve implementare metodi delle funzioni di accesso dedicati denominati sotto forma di GetPropertyName e SetPropertyName.The owner type of the attached property must implement dedicated accessor methods named in the form GetPropertyName and SetPropertyName. Tali metodi costituiscono inoltre un modo per ottenere o impostare la proprietà associata nel codice.These dedicated accessor methods are also one way to get or set the attached property in code. Dal punto di vista del codice, una proprietà associata è simile a un campo di supporto che dispone di funzioni di accesso al metodo anziché di funzioni di accesso alla proprietà. Tale campo di supporto può essere presente su qualsiasi oggetto invece di dover essere definito in modo specifico.From a code perspective, an attached property is similar to a backing field that has method accessors instead of property accessors, and that backing field can exist on any object rather than having to be specifically defined.

L'esempio seguente mostra come impostare una proprietà associata nel codice tramite l'API della funzione di accesso XAML.The next example shows how you can set an attached property in code via the XAML accessor API. In questo esempio, myCheckBox è un'istanza della classe CheckBox .In this example, myCheckBox is an instance of the CheckBox class. L'ultima riga è il codice che imposta effettivamente il valore, le righe precedenti definiscono semplicemente le istanze e il relativo rapporto tra padre e figlio.The last line is the code that actually sets the value; the lines before that just establish the instances and their parent-child relationship. L'ultima riga non commentata è la sintassi per l'uso del sistema di proprietà.The uncommented last line is the syntax if you use the property system. L'ultima riga commentata è la sintassi per l'uso del modello di funzione di accesso XAML.The commented last line is the syntax if you use the XAML accessor pattern.

    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 personalizzateCustom attached properties

Per informazioni sugli esempi di codice per la definizione di proprietà associate personalizzate e sugli scenari per l'uso di una proprietà associata, vedi Proprietà associate personalizzate.For code examples of how to define custom attached properties, and more info about the scenarios for using an attached property, see Custom attached properties.

Sintassi speciale per i riferimenti alle proprietà associateSpecial syntax for attached property references

Il punto nel nome della proprietà associata è la parte principale del modello di identificazione.The dot in an attached property name is a key part of the identification pattern. Quando in una sintassi o situazione al punto viene attribuito un significato diverso, possono verificarsi ambiguità.Sometimes there are ambiguities when a syntax or situation treats the dot as having some other meaning. Ad esempio, un punto viene trattato come modello a oggetti trasversale per un percorso di associazione.For example, a dot is treated as an object-model traversal for a binding path. Nella maggior parte dei casi in cui si verifica tale ambiguità, esiste una sintassi speciale per la proprietà associata che rende possibile l'analisi del punto interno come separatore owner.property di una proprietà associata.In most cases involving such ambiguity, there is a special syntax for an attached property that enables the inner dot still to be parsed as the owner.property separator of an attached property.

  • Per specificare una proprietà associata nell'ambito di un percorso di destinazione per un'animazione, racchiudi il nome della proprietà associata tra parentesi ("()"), ad esempio, "(Canvas.Left)".To specify an attached property as part of a target path for an animation, enclose the attached property name in parentheses ("()")—for example, "(Canvas.Left)". Per altre info, vedi Sintassi proprietà-percorso.For more info, see Property-path syntax.

Avviso

Una limitazione esistente dell'implementazione di Windows Runtime XAML è che non è possibile aggiungere un'animazione a una proprietà associata personalizzata.An existing limitation of the Windows Runtime XAML implementation is that you cannot animate a custom attached property.

  • Per specificare una proprietà associata come proprietà di destinazione per un riferimento a una risorsa da un file di risorse a x:UID, utilizzare una sintassi speciale che inserisce un tipo di codice, completo utilizzando: la dichiarazione racchiusa tra parentesi quadre (" [ ] "), per creare un'interruzioni di ambito intenzionale.To specify an attached property as the target property for a resource reference from a resource file to x:Uid, use a special syntax that injects a code-style, fully qualified using: declaration inside square brackets ("[]"), to create a deliberate scope break. Ad esempio, supponendo che esista un elemento <TextBlock x:Uid="Title" /> , la chiave di risorsa nel file di risorse che ha come destinazione il valore Canvas. Top in tale istanza è "title. [ utilizzando: Windows. UI. XAML. Controls ] Canvas. Top ".For example, assuming there exists an element <TextBlock x:Uid="Title" />, the resource key in the resource file that targets the Canvas.Top value on that instance is "Title.[using:Windows.UI.Xaml.Controls]Canvas.Top". Per altre informazioni sui file di risorse, vedi Guida introduttiva: Traduzione delle risorse dell'interfaccia utente.For more info on resource files and XAML, see Quickstart: Translating UI resources.