Sintaxe de Property-pathProperty-path syntax

Você pode usar a classe PropertyPath e a sintaxe de cadeia de caracteres para instanciar um valor PropertyPath vem XAML ou em código.You can use the PropertyPath class and the string syntax to instantiate a PropertyPath value either in XAML or in code. Valores PropertyPath são usados por vinculação de dados.PropertyPath values are used by data binding. Uma sintaxe semelhante é usada para direcionar animações em storyboard.A similar syntax is used for targeting storyboarded animations. Nos dois cenários, um caminho de propriedade descreve uma passagem de uma ou mais relações objeto-propriedade que eventualmente são resolvidas para uma única propriedade.For both scenarios, a property path describes a traversal of one or more object-property relationships that eventually resolve to a single property.

Você pode definir uma cadeia de caracteres de caminho de propriedade a um atributo em XAML.You can set a property path string directly to an attribute in XAML. Você pode usar a mesma sintaxe de cadeia de caracteres para construir um PropertyPath que define uma Associação em código ou definir um destino de animação em código usando SetTargetProperty.You can use the same string syntax to construct a PropertyPath that sets a Binding in code, or to set an animation target in code using SetTargetProperty. Há duas áreas de recurso diferentes no Windows Runtime que usam um caminho de propriedade: vinculação de dados e direcionamento de animação.There are two distinct feature areas in the Windows Runtime that use a property path: data binding, and animation targeting. O direcionamento da animação não cria valores de sintaxe de Property-path subjacentes na implementação do Tempo de Execução do Windows; ele mantém as informações como uma cadeia de caracteres, mas os conceitos de passagem objeto-propriedade são bastante semelhantes.Animation targeting doesn't create underlying Property-path syntax values in the Windows Runtime implementation, it keeps the info as a string, but the concepts of object-property traversal are very similar. A vinculação de dados e o direcionamento da animação avaliam um caminho de propriedade de maneira um pouco diferente, então vamos descrever a sintaxe do caminho de propriedade separadamente para cada um.Data binding and animation targeting each evaluate a property path slightly differently, so we describe property path syntax separately for each.

Caminho de propriedade para objetos na vinculação de dadosProperty path for objects in data binding

No Tempo de Execução do Windows, você pode associar ao valor de destino de qualquer propriedade de dependência.In Windows Runtime, you can bind to the target value of any dependency property. O valor de propriedade de origem para uma vinculação de dados não precisa ser uma propriedade de dependência; pode ser uma propriedade em um objeto comercial (por exemplo, uma classe escrita em linguagem Microsoft .NET ou C++).The source property value for a data binding doesn't have to be a dependency property; it can be a property on a business object (for example a class written in a Microsoft .NET language or C++). Ou o objeto de origem do valor da associação pode ser um objeto de dependência existente já definido pelo aplicativo.Or, the source object for the binding value can be an existing dependency object already defined by the app. A fonte pode ser referenciada por um simples nome de propriedade ou por um percurso das relações objeto-propriedade no gráfico do objeto do objeto comercial.The source can be referenced either by a simple property name, or by a traversal of the object-property relationships in the object graph of the business object.

Você pode associar a um valor de propriedade individual ou pode associar a uma propriedade de destino que mantenha listas ou coleções.You can bind to an individual property value, or you can bind to a target property that holds lists or collections. Se sua fonte for uma coleção ou se caminho especificar uma propriedade de coleção, o mecanismo de vinculação de dados corresponde aos itens de coleção da fonte do destino de associação, resultando em comportamentos como popular um ListBox com uma lista de itens de uma coleção de fonte de dados sem precisar prever os itens específicos em tal coleção.If your source is a collection, or if the path specifies a collection property, the data-binding engine matches the collection items of the source to the binding target, resulting in behavior such as populating a ListBox with a list of items from a data source collection without needing to anticipate the specific items in that collection.

Passando um gráfico de objetoTraversing an object graph

O elemento da sintaxe que indica o percurso de uma relação objeto-propriedade em um gráfico de objeto é o caractere ponto (.).The element of the syntax that denotes the traversal of an object-property relationship in an object graph is the dot (.) character. Cada ponto em uma cadeia de caracteres de caminho de propriedade indica uma divisão entre um objeto (à esquerda do ponto) e uma propriedade desse objeto (à direita do ponto).Each dot in a property path string indicates a division between an object (left side of the dot) and a property of that object (right side of the dot). A cadeia de caracteres é avaliada da esquerda para a direita, o que permite passar por várias relações objeto-propriedade.The string is evaluated left-to-right, which enables stepping through multiple object-property relationships. Vejamos um exemplo:Let's look at an example:

"{Binding Path=Customer.Address.StreetAddress1}"

Veja como esse caminho é avaliado:Here's how this path is evaluated:

  1. O objeto de contexto de dados (ou uma Fonte especificada pela mesma Associação) é pesquisado por uma propriedade chamada "Customer".The data context object (or a Source specified by the same Binding) is searched for a property named "Customer".
  2. O objeto que é o valor da propriedade "Customer" é pesquisado por uma propriedade chamada "Address".The object that is the value of the "Customer" property is searched for a property named "Address".
  3. O objeto que é o valor da propriedade "Address" é pesquisado por uma propriedade chamada "StreetAddress1".The object that is the value of the "Address" property is searched for a property named "StreetAddress1".

Em cada um dessas etapas, o valor é tratados como um objeto.At each of these steps, the value is treated as an object. O tipo do resultado só é verificado quando a associação é aplicada a uma propriedade específica.The type of the result is checked only when the binding is applied to a specific property. Esse exemplo falharia se "Address" fosse apenas um valor de cadeia de caracteres que não expusesse que parte da cadeia é o endereço da rua.This example would fail if "Address" were just a string value that didn't expose what part of the string was the street address. Normalmente, a associação aponta para os valores de propriedade aninhados específicos de um objeto de negócios que tem uma estrutura de informações conhecida e clara.Typically, the binding is pointing to the specific nested property values of a business object that has a known and deliberate information structure.

Regras de propriedades em um caminho de propriedade de vinculação de dadosRules for the properties in a data-binding property path

  • Todas as propriedades referenciadas por um caminho de propriedade devem ser públicas no objeto de negócios da origem.All properties referenced by a property path must be public in the source business object.
  • A propriedade final (a propriedade que é nomeada por último no caminho) deve ser pública e mutável – não é possível associar a valores estáticos.The end property (the property that is the last named property in the path) must be public and must be mutable – you can't bind to static values.
  • A propriedade final deve ser ler/escrever se esse caminho é usado como a informação Path para uma associação de bidirecional.The end property must be read/write if this path is used as the Path information for a two-way binding.

IndexadoresIndexers

Um caminho de propriedade para vinculação de dados pode incluir referências a propriedade indexadas.A property path for data-binding can include references to indexed properties. Isso habilita a associação a listas/vetores ordenados ou a dicionários/mapas.This enables binding to ordered lists/vectors, or to dictionaries/maps. Use caracteres de colchetes " [ ] " para indicar uma propriedade indexada.Use square brackets "[]" characters to indicate an indexed property. O conteúdo desses colchetes pode ser um inteiro (em uma lista ordenada) ou uma cadeia de caracteres sem aspas (em dicionários).The contents of these brackets can be either an integer (for ordered list) or an unquoted string (for dictionaries). Você também pode associar a um dicionário onde a chave é um inteiro.You can also bind to a dictionary where the key is an integer. É possível usar diferentes propriedades indexadas no mesmo caminho com um ponto separando o objeto-propriedade.You can use different indexed properties in the same path with a dot separating the object-property.

Por exemplo, considere um objeto comercial em que haja uma lista de "Times" (lista ordenada), cada uma tendo um dicionário de "Jogadores" onde cada jogador é citado pelo último nome.For example, consider a business object where there is a list of "Teams" (ordered list), each of which has a dictionary of "Players" where each player is keyed by last name. Um caminho de propriedade de exemplo para um player específico na segunda equipe é: "Teams [ 1 ] . Jogadores [ Smith ] ".An example property path to a specific player on the second team is: "Teams[1].Players[Smith]". (Você usa 1 para indicar o segundo item em "Times" porque a lista é indexada com zero.)(You use 1 to indicate the second item in "Teams" because the list is zero-indexed.)

Observação    O suporte à indexação para fontes de dados C++ é limitado; consulte a ligação de dados em profundidade.Note  Indexing support for C++ data sources is limited; see Data binding in depth.

Propriedades anexadasAttached properties

Os caminhos de propriedade podem incluir referências a propriedades anexadas.Property paths can include references to attached properties. Como o nome que identifica uma propriedade anexada já inclui um ponto, todos os nomes de propriedades anexadas devem estar entre parênteses para que o ponto não seja tratado como uma etapa de objeto-propriedade.Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. Por exemplo, a cadeia de caracteres em que você quer usar Canvas.ZIndex como caminho de associação é "(Canvas.ZIndex)".For example, the string to specify that you want to use Canvas.ZIndex as a binding path is "(Canvas.ZIndex)". Para saber mais sobre as propriedades anexadas, consulte Visão geral das propriedades anexadas.For more info on attached properties see Attached properties overview.

Combinando a sintaxe de caminho de propriedadeCombining property path syntax

Você pode combinar vários elementos da sintaxe de caminho de propriedade em uma única cadeia de caracteres.You can combine various elements of property path syntax in a single string. Por exemplo, é possível definir um caminho de propriedade que referencia uma propriedade indexada anexada, se sua fonte de dados tem uma propriedade assim.For example, you can define a property path that references an indexed attached property, if your data source had such a property.

Depurando um caminho de propriedade de associaçãoDebugging a binding property path

Por um caminho de propriedade ser interpretado por um mecanismo de associação e depender de informações que talvez estejam presentes somente no tempo de execução, você deve eliminar erros com frequência de um caminho de propriedade para associação sem poder depender do tempo de design convencional ou suporte de tempo de compilação nas ferramentas de desenvolvimento.Because a property path is interpreted by a binding engine and relies on info that may be present only at run-time, you must often debug a property path for binding without being able to rely on conventional design-time or compile-time support in the development tools. Em muitos casos, o resultado do tempo de execução da falha ao resolver um caminho de propriedade é um valor em branco sem erro, porque esse é o comportamento de fallback por design da resolução da associação.In many cases the run-time result of failing to resolve a property path is a blank value with no error, because that is the by-design fallback behavior of binding resolution. Felizmente, o Microsoft Visual Studio fornece um modo de saída de depuração que pode isolar a parte de um caminho de propriedade que especifica uma fonte de associação com falha para a resolução.Fortunately, Microsoft Visual Studio provides a debug output mode that can isolate which part of a property path that's specifying a binding source failed to resolve. Para saber mais sobre como usar esse recurso da ferramenta de desenvolvimento, consulte a seção "Depuração" em Associação de dados em detalhes.For more info on using this development tool feature, see "Debugging" section of Data binding in depth.

Caminho de propriedade para direcionamento da animaçãoProperty path for animation targeting

As animações dependem do direcionamento de uma propriedade de dependência onde valores de storyboard são aplicados quando a animação é reproduzida.Animations rely on targeting a dependency property where storyboarded values are applied when the animation runs. Para identificar o objeto no qual a propriedade que deve ser animada existe, a animação direciona um ele por nome (atributo x:Name).To identify the object where the property to be animated exists, the animation targets an element by name (x:Name attribute). Costuma ser necessário definir um caminho de propriedade que inicia com o objeto identificado como Storyboard.TargetName e termina com o valor de propriedade de dependência particular em que a animação deve ser aplicada.It is often necessary to define a property path that starts with the object identified as the Storyboard.TargetName, and ends with the particular dependency property value where the animation should apply. Tal caminho de propriedade é usada como o valor de Storyboard.TargetProperty.That property path is used as the value for Storyboard.TargetProperty.

Para saber mais sobre como definir animações em XAML, consulte Animações de storyboard.For more info on the how to define animations in XAML, see Storyboarded animations.

Direcionamento simplesSimple targeting

Se você está animando uma propriedade que existe no próprio objeto direcionado, e se o tipo de propriedade pode ter uma animação aplicada diretamente a ela (em vez de em uma subpropriedade de um valor de propriedade), então você pode simplesmente nomear a propriedade sendo animada sem nenhuma outra qualificação.If you are animating a property that exists on the targeted object itself, and that property's type can have an animation applied directly to it (rather than to a sub-property of a property's value) then you can simply name the property being animated without any further qualification. Por exemplo, se você estiver direcionando uma subclasse Shape como Rectangle, e estiver aplicando um Color animado à propriedade Fill, o seu caminho de propriedade pode ser "Fill".For example, if you are targeting a Shape subclass such as Rectangle, and you are applying an animated Color to the Fill property, your property path can be "Fill".

Direcionamento indireto de propriedadeIndirect property targeting

Você pode animar uma propriedade que é subpropriedade do objeto de destino.You can animate a property that is a sub-property of the target object. Em outras palavras, se existe uma propriedade do objeto de destino que é um objeto, e esse objeto tem propriedades, você deve definir um caminho de propriedade que explique como passar por essa relação objeto-propriedade.In other words, if there's a property of the target object that's an object itself, and that object has properties, you must define a property path that explains how to step through that object-property relationship. Sempre que você estiver especificando um objeto cuja subpropriedade quiser animar, coloque o nome da propriedade em parênteses e especifique a propriedade em formato typename.propertyname.Whenever you are specifying an object where you want to animate a sub-property, you enclose the property name in parentheses, and you specify the property in typename.propertyname format. Por exemplo, para especificar que você quer um valor de objeto da propriedade RenderTransform de um objeto de destino, especifique "(UIElement.RenderTransform)" como a primeira etapa no caminho de propriedade.For example, to specify that you want the object value of a target object's RenderTransform property, you specify "(UIElement.RenderTransform)" as the first step in the property path. Esse não é um caminho muito completo porque não há animações aplicáveis a um valor Transform diretamente.This isn't yet a complete path, because there are no animations that can apply to a Transform value directly. Então, nesse exemplo, você conclui o caminho de propriedade agora para que a propriedade final seja propriedade de uma Transform que pode ser animada por um valor Double: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"So for this example, you now complete the property path so that the end property is a property of a Transform subclass that can be animated by a Double value: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"

Especificando um filho em particular em uma coleçãoSpecifying a particular child in a collection

Para especificar um item filho em uma propriedade de coleção, você pode usar um indexador numérico.To specify a child item in a collection property, you can use a numeric indexer. Use caracteres de colchetes " [ ] " em volta do valor de índice inteiro.Use square brackets "[]" characters around the integer index value. Você pode fazer referência apenas a listas ordenadas, não a dicionários.You can reference only ordered lists, not dictionaries. Como uma coleção não é um valor que pode ser animado, o uso de um indexador nunca pode ser a propriedade final em um caminho de propriedade.Because a collection isn't a value that can be animated, an indexer usage can never be the end property in a property path.

Por exemplo, para especificar que você deseja animar a primeira cor de parada de cor em um LinearGradientBrush aplicado à propriedade de segundo plano de um controle, este é o caminho da propriedade: "(Control. Background). (GradientBrush. GradientStops) [ 0 ] . ( GradientStop. Color) ".For example, to specify that you want to animate the first color stop color in a LinearGradientBrush that is applied to a control's Background property, this is the property path: "(Control.Background).(GradientBrush.GradientStops)[0].(GradientStop.Color)". Observe que o indexador não é a última etapa do caminho e que a última etapa deve fazer referência à propriedade GradientStop.Color do item 0 da coleção para aplicar um valor animado Color a ela.Note how the indexer is not the last step in the path, and that the last step particularly must reference the GradientStop.Color property of item 0 in the collection to apply a Color animated value to it.

Animando uma propriedade anexadaAnimating an attached property

Não é comum, mas é possível animar uma propriedade anexada, desde que ela tenha um valor de propriedade que corresponda a um tipo de animação.It isn't a common scenario, but it is possible to animate an attached property, so long as that attached property has a property value that matches an animation type. Como o nome que identifica uma propriedade anexada já inclui um ponto, todos os nomes de propriedades anexadas devem estar entre parênteses para que o ponto não seja tratado como uma etapa de objeto-propriedade.Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. Por exemplo, a cadeia de caracteres para especificar que você quer animar a propriedade anexada Grid.Row em um objeto, use o caminho de propriedade "(Grid.Row)".For example, the string to specify that you want to animate the Grid.Row attached property on an object, use the property path "(Grid.Row)".

Observação    Para este exemplo, o valor de Grid. Row é um tipo de propriedade Int32 .Note  For this example, the value of Grid.Row is an Int32 property type. então, você não pode animá-lo com uma animação Double.so you can't animate it with a Double animation. Em vez disso, você definiria um ObjectAnimationUsingKeyFrames que tem componentes DiscreteObjectKeyFrame, onde o ObjectKeyFrame.Value é definido como um inteiro como "0" ou "1".Instead, you'd define an ObjectAnimationUsingKeyFrames that has DiscreteObjectKeyFrame components, where the ObjectKeyFrame.Value is set to an integer such as "0" or "1".

Regras para as propriedades em um caminho de propriedade de direcionamento de animaçãoRules for the properties in an animation targeting property path

  • O suposto ponto de partida de um caminho de propriedade é o objeto identificado por um Storyboard.TargetName.The assumed starting point of the property path is the object identified by a Storyboard.TargetName.
  • Todos os objetos e todas as propriedades referenciados ao longo do caminho de propriedade devem ser públicos.All objects and properties referenced along the property path must be public.
  • A propriedade final (a propriedade que é nomeada por último no caminho) deve ser pública, de leitura-gravação e ser uma propriedade de dependência.The end property (the property that is the last named property in the path) must be public, be read-write, and be a dependency property.
  • A propriedade final deve ter um tipo de propriedade capaz de ser animado por uma das amplas classes de tipos de animação, animações (Color, animações Double, animações Point, ObjectAnimationUsingKeyFrames).The end property must have a property type that is able to be animated by one of the broad classes of animation types (Color animations, Double animations, Point animations, ObjectAnimationUsingKeyFrames).

A classe PropertyPathThe PropertyPath class

A classe PropertyPath é o tipo de propriedade subjacente de Binding.Path para a situação de associação.The PropertyPath class is the underlying property type of Binding.Path for the binding scenario.

Na maioria das vezes, é possível aplicar um PropertyPath em XAML sem usar nenhum código.Most of the time, you can apply a PropertyPath in XAML without using any code at all. Mas, em alguns casos, pode ser que você queria definir um objeto PropertyPath usando um código e atribuí-lo a uma propriedade em tempo de execução.But in some cases you may want to define a PropertyPath object using code and assign it to a property at run-time.

PropertyPath tem um construtor PropertyPath(String), mas não tem um construtor padrão.PropertyPath has a PropertyPath(String) constructor, and doesn't have a default constructor. A cadeia de caracteres que você passa para esse construtores é definida usando uma sintaxe de caminho de propriedade, como explicado anteriormente.The string you pass to this constructor is a string that's defined using the property path syntax as we explained earlier. Ela também é a mesma cadeia de caracteres que você usaria para atribuir Path como atributo XAML.This is also the same string you'd use to assign Path as a XAML attribute. O único outro API da classe PropertyPath na propriedade Path, que é somente para leitura.The only other API of the PropertyPath class is the Path property, which is read-only. Você poderia usar essa propriedade como a cadeia de caracteres de construção para outra instância PropertyPath.You could use this property as the construction string for another PropertyPath instance.