Visão geral das propriedades anexadasAttached properties overview

Uma propriedade anexada é um conceito de XAML.An attached property is a XAML concept. As propriedades anexadas habilitam pares de propriedade/valor adicionais a serem definidas em um objeto, mas as propriedades não fazem parte da definição do objeto original.Attached properties enable additional property/value pairs to be set on an object, but the properties are not part of the original object definition. Tipicamente, as propriedades anexadas são definidas como uma forma especializada de propriedade de dependência que não tem um wrapper de propriedade convencional no modelo de objeto do tipo de proprietário.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.

Pré-requisitosPrerequisites

Consideramos que você entende o conceito básico das propriedades de dependência e já leu a Visão geral das propriedades de dependência.We assume that you understand the basic concept of dependency properties, and have read Dependency properties overview.

Propriedades anexadas em XAMLAttached properties in XAML

Em XAML, você define as propriedades anexadas usando a sintaxe AttachedPropertyProvider. PropertyName.In XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName. Veja um exemplo de como é possível definir Canvas.Left em XAML.Here is an example of how you can set Canvas.Left in XAML.

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

Observação

Estamos apenas usando Canvas. Left como uma propriedade anexada de exemplo sem explicar totalmente por que você a usaria.We're just using Canvas.Left as an example attached property without fully explaining why you'd use it. Se quiser saber mais sobre a finalidade de Canvas.Left e como Canvas manipula seus filhos de layout, consulte o tópico de referência Canvas ou Definir layouts com 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.

Por que usar propriedades anexadas?Why use attached properties?

As propriedades anexadas são uma maneira de evitar as convenções de codificação que podem impedir que objetos diferentes em um relacionamento transmitam informações entre si em tempo de execução.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 possível colocar as propriedades em uma classe base comum para que cada objeto possa simplesmente obter e definir essa propriedade.It's certainly possible to put properties on a common base class so that each object could just get and set that property. Mas por fim o grande número de cenários em que você pode querer fazer isso inchará suas classes base com propriedades compartilháveis.But eventually the sheer number of scenarios where you might want to do this will bloat your base classes with shareable properties. Isso pode inclusive introduzir casos em que talvez haja duas centenas de descendentes tentando usar uma propriedade.It might even introduce cases where there might just be two of hundreds of descendants trying to use a property. Isso não é um ótimo design de classe.That's not good class design. Para resolver isso, o conceito de propriedade anexada habilita um objeto para atribuir um valor a uma propriedade cuja estrutura de classe não define.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. A classe de definição pode ler o valor de objetos filho em tempo de execução depois que vários objetos são criados em uma árvore de objetos.The defining class can read the value from child objects at run time after the various objects are created in an object tree.

Por exemplo, elementos filho podem usar propriedades anexadas para informar o elemento pai sobre o modo como são apresentados na interface do usuário.For example, child elements can use attached properties to inform their parent element of how they are to be presented in the UI. Esse é o caso com a propriedade anexada Canvas.Left.This is the case with the Canvas.Left attached property. Canvas.Left é criada como uma propriedade anexada porque ela define elementos contidos dentro de um elemento Canvas, em vez de dentro da Canvas propriamente dita.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. Qualquer elemento filho possível então usa Canvas.Left e Canvas.Top para especificar seu deslocamento de layout dentro do pai do contêiner de layout Canvas.Any possible child element then uses Canvas.Left and Canvas.Top to specify its layout offset within the Canvas layout container parent. As propriedades anexadas possibilitam que isso funcione sem desorganizar o modelo de objeto do elemento base com muitas propriedades que se aplicam somente a um dos muitos contêineres de layout possíveis.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. Em vez disso, muitos contêineres de layout implementam seu próprio conjunto de propriedades anexadas.Instead, many of the layout containers implement their own attached property set.

Para implementar a propriedade anexada, a classe Canvas define um campo estático DependencyProperty chamado Canvas.LeftProperty.To implement the attached property, the Canvas class defines a static DependencyProperty field named Canvas.LeftProperty. Em seguida, Canvas fornece os métodos SetLeft e GetLeft como acessadores públicos para a propriedade anexada, para habilitar a configuração de XAML e o acesso do valor de tempo de execução.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. Para XAML e para o sistema de propriedades de dependência, esse conjunto de APIs satisfaz um padrão que habilita uma sintaxe XAML específica para propriedades anexadas e armazena o valor no repositório de propriedades de dependência.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.

Como o tipo proprietário usa as propriedades anexadasHow the owning type uses attached properties

Embora as propriedades anexadas possam ser definidas em qualquer elemento XAML (ou em qualquer DependencyObject subjacente), isso não significa automaticamente que a configuração da propriedade produz um resultado tangível ou que o valor seja acessado.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. O tipo que define a propriedade anexada normalmente é semelhante a um destes cenários:The type that defines the attached property typically follows one of these scenarios:

  • O tipo que define a propriedade anexada é o pai em um relacionamento de outros objetos.The type that defines the attached property is the parent in a relationship of other objects. Os objetos filho definirão valores para a propriedade anexada.The child objects will set values for the attached property. O tipo proprietário da propriedade anexada tem algum comportamento inato que itera por meio de seus elementos filho, obtém os valores e atua sobre esses valores em algum momento na vida útil do objeto (uma ação de layout, SizeChanged etc.)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.)
  • O tipo que define a propriedade anexada é usado como elemento filho de uma variedade de possíveis elementos pai e modelos de conteúdo, mas as informações não são necessariamente informações de 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.
  • A propriedade anexada relata informações para um serviço, e não para outro elemento de interface do usuário.The attached property reports info to a service, not to another UI element.

Para saber mais sobre esses cenários e tipos de propriedade, consulte a seção "Mais sobre Canvas.Left" de Propriedades anexadas personalizadas.For more info on these scenarios and owning types, see the "More about Canvas.Left" section of Custom attached properties.

Propriedades anexadas no códigoAttached properties in code

Propriedades anexadas não têm os wrappers de propriedade típicos para fácil acesso de obtenção e definição, se comparadas às propriedades de dependência.Attached properties don't have the typical property wrappers for easy get and set access like other dependency properties do. Isso acontece porque a propriedade anexada não necessariamente faz parte do modelo de objeto focado no código para instâncias onde a propriedade foi definida.This is because the attached property is not necessarily part of the code-centered object model for instances where the property is set. (É possível, mas incomum, definir uma propriedade que seja uma propriedade anexada que outros tipos possam definir por si só e que, ao mesmo tempo, tenha um uso de propriedade convencional no tipo proprietário.)(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.)

Há duas formas de definir uma propriedade anexada em código: usar as APIs do sistema de propriedades ou usar os acessadores de padrão XAML.There are two ways to set an attached property in code: use the property-system APIs, or use the XAML pattern accessors. As duas técnicas são bastante equivalentes em termos de resultado final. Assim, a escolha é basicamente uma questão de estilo de codificação.These techniques are pretty much equivalent in terms of their end result, so which one to use is mostly a matter of coding style.

Usando o sistema de propriedadesUsing the property system

As propriedades anexadas do Windows Runtime são implementadas como propriedades de dependência, portanto, o sistema de propriedades pode armazenar os valores no repositório de propriedades de dependência.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. Sendo assim, as propriedades anexadas expõem um identificador de propriedade de dependência na classe proprietária.Therefore attached properties expose a dependency property identifier on the owning class.

Para definir uma propriedade anexada no código, chame o método SetValue e passe o campo DependencyProperty que serve como identificador dessa propriedade anexada.To 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. (Você também passa o valor a ser definido.)(You also pass the value to set.)

Para obter o valor de uma propriedade anexada no código, chame o método GetValue e passe novamente o campo DependencyProperty que serve como identificador dessa propriedade anexada.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.

Usando o padrão de acessador XAMLUsing the XAML accessor pattern

Um processador XAML deve ser capaz de definir esses valores de propriedade anexada quando o XAML é analisado em uma árvore de objetos.A XAML processor must be able to set attached property values when XAML is parsed into an object tree. O tipo proprietário da propriedade anexada deve implementar métodos acessadores dedicados denominados segundo a forma GetNomeDaPropriedade e SetNomeDaPropriedade.The owner type of the attached property must implement dedicated accessor methods named in the form GetPropertyName and SetPropertyName. Esses métodos acessadores dedicados também são uma boa maneira de obter ou definir a propriedade anexada em código.These dedicated accessor methods are also one way to get or set the attached property in code. Sob a perspectiva de código, uma propriedade anexada é similar a um campo existente que contém acessadores de método em vez de acessadores de propriedade. Esse campo existente pode existir em qualquer objeto, não sendo necessário defini-lo especificamente.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.

O próximo exemplo mostra como você pode definir uma propriedade anexada no código usando a API do acessador XAML.The next example shows how you can set an attached property in code via the XAML accessor API. Neste exemplo, myCheckBox é uma instância da classe CheckBox.In this example, myCheckBox is an instance of the CheckBox class. A última linha é o código que efetivamente define o valor; as linhas anteriores apenas estabelecem as instâncias e o relacionamento pai-filho.The last line is the code that actually sets the value; the lines before that just establish the instances and their parent-child relationship. A última linha não comentada será a sintaxe se você usar o sistema de propriedades.The uncommented last line is the syntax if you use the property system. A última linha comentada será a sintaxe se você usar o padrão do acessador 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);

Propriedades anexadas personalizadasCustom attached properties

Para obter exemplos de código sobre como definir propriedades anexadas personalizadas e saber mais sobre os cenários que as utilizam, consulte Propriedades anexadas personalizadas.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.

Sintaxe especial para referências de propriedades anexadasSpecial syntax for attached property references

O ponto no nome de uma propriedade anexada é uma parte essencial do padrão de identificação.The dot in an attached property name is a key part of the identification pattern. Ocorrem ambiguidades quando uma sintaxe ou situação considera que o ponto tem outro significado.Sometimes there are ambiguities when a syntax or situation treats the dot as having some other meaning. Por exemplo, o ponto é considerado como a passagem de um modelo-objeto para um caminho de associação.For example, a dot is treated as an object-model traversal for a binding path. Na maioria dos casos que envolvem essa ambiguidade, há uma sintaxe especial para uma propriedade anexada que habilita o ponto interno a ser analisado como o separador proprietário.propriedade de uma propriedade anexada.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.

  • Para especificar uma propriedade anexada como parte de um caminho de destino para uma animação, coloque o nome da propriedade anexada entre parênteses ("()") — por exemplo, "(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)". Para obter mais informações, consulte Sintaxe do Property-path.For more info, see Property-path syntax.

Aviso

Uma limitação existente da implementação Windows Runtime XAML é que você não pode animar uma propriedade anexa personalizada.An existing limitation of the Windows Runtime XAML implementation is that you cannot animate a custom attached property.

  • Para especificar uma propriedade anexada como a propriedade de destino para uma referência de recurso de um arquivo de recurso para x:Uid, use uma sintaxe especial que injeta um estilo de código, totalmente qualificado usando: declaração dentro de colchetes (" [ ] "), para criar uma quebra de escopo deliberada.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. Por exemplo, supondo que exista um elemento <TextBlock x:Uid="Title" /> , a chave de recurso no arquivo de recurso que tem como alvo o valor Canvas. Top nessa instância é "title. [ usando: 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". Para obter mais informações sobre arquivos de recurso e XAML, consulte Início rápido: Traduzindo recursos da interface do usuário.For more info on resource files and XAML, see Quickstart: Translating UI resources.