Sintaxe de caminhos de propriedades

Sintaxe de caminhos de propriedades

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Você pode usar a classe PropertyPath e a sintaxe de cadeia de caracteres para criar uma instância de um valor de PropertyPath no XAML ou no código. Os valores de PropertyPath são usados pela vinculação de dados. Uma sintaxe semelhante é usada para direcionar animações de storyboard. Porém, o direcionamento da animação não cria valores de PropertyPath subjacentes, mas mantém as informações como uma cadeia de caracteres. 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.

Você pode definir uma cadeia de caracteres de caminho de propriedade diretamente para um atributo no XAML. Você pode usar a mesma sintaxe de cadeia de caracteres para construir um PropertyPath que definir uma Binding no código ou para definir um destino da animação no código usando SetTargetProperty. Existem duas áreas de recursos diferentes no Tempo de Execução do Windows que usam um caminho de propriedade: a vinculação de dados e o direcionamento da animação. O direcionamento da animação não cria valores de PropertyPath 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. 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.

Caminho de propriedade para objetos na vinculação de dados

No Tempo de Execução do Windows, você pode associar ao valor de destino de qualquer propriedade de dependência. O valor da propriedade de origem de uma vinculação de dados não precisa ser uma propriedade de dependência; pode ser uma propriedade em um objeto de negócios (por exemplo, uma classe escrita em uma linguagem do Microsoft .NET ou em C++). Ou o objeto de origem do valor da associação pode ser um objeto de dependência existente já definido pelo aplicativo. A origem pode ser referenciada por um nome de propriedade simples ou por uma passagem das relações objeto-propriedade no gráfico do objeto de negócios.

Você pode associar a um valor de propriedade individual ou pode associar a uma propriedade de destino que mantenha listas ou coleções. Se a sua fonte é uma coleção ou se o caminho especifica uma propriedade de coleção, o mecanismo de vinculação de dados faz a correspondência dos itens da coleção da origem com o destino da associação. Isso resulta em um comportamento como o preenchimento de uma ListBox com uma lista de itens de uma coleção de fontes de dados, sem precisar antecipar os itens específicos nessa coleção.

Passando um gráfico de objeto

O elemento da sintaxe que indica a passagem de uma relação objeto-propriedade em um gráfico de objeto é o caractere de ponto (.). 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). A cadeia de caracteres é avaliada da esquerda para a direita, o que permite passar por várias relações objeto-propriedade. Vamos ver um exemplo:

<Binding Path="Customer.Address.StreetAddress1"

Veja como este caminho é avaliado:

  1. No objeto do contexto de dados (ou uma Source especificada pela mesma Binding), é pesquisada uma propriedade chamada "Customer".
  2. No objeto que é o valor da propriedade "Customer", é pesquisada uma propriedade chamada "Address".
  3. No objeto que é o valor da propriedade "Address", é pesquisada uma propriedade chamada "StreetAddress1".

Em cada uma dessas etapas, o valor é tratado como um objeto. O tipo do resultado é verificado apenas quando a associação é aplicada a uma propriedade específica. Esse exemplo falharia se "Address" fosse apenas um valor de cadeia de caracteres que não expusesse qual parte da cadeia de caracteres é o endereço. 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.

Regras de propriedades em um caminho de propriedade de vinculação de dados

  • Todas as propriedades referenciadas por um caminho de propriedade devem ser públicas no objeto de negócios da origem.
  • 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.
  • A propriedade final deve ser de leitura/gravação se esse caminho é usado como informações de Path para uma associação bidirecional.

Indexadores

Um caminho de propriedade de uma vinculação de dados pode incluir referências a propriedades indexadas. Isso permite a associação com listas/vedores ordenados ou a dicionários/mapas. Use colchetes "[]" para indicar uma propriedade indexada. O conteúdo desses colchetes pode ser um inteiro (para uma lista ordenada) ou uma cadeia de caracteres sem aspas (para dicionários). Você também pode associar a um dicionário onde a chave é um inteiro. É possível usar diferentes propriedades indexadas no mesmo caminho com um ponto separando o objeto-propriedade.

Por exemplo, considere um objeto de negócios onde há uma lista de "Equipes" (lista ordenada); cada uma delas tem um dicionário de "Jogadores", onde cada jogador é inserido por sobrenome. Um caminho de propriedade de exemplo para um jogador específico da segunda equipe é: "Equipes[1].Jogadores[Silva]". (Use 1 para indicar o segundo item em "Equipes" porque a lista é indexada a partir do zero.)

Observação  O suporte de indexação para origens de dados C++ é limitado; veja Visão geral da vinculação de dados.
 

Propriedades anexadas

Os caminhos de propriedade podem incluir referências a propriedades anexadas. 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. Por exemplo, a cadeia de caracteres para especificar que você quer usar Canvas.ZIndex como caminho de associação é "(Canvas.ZIndex)". Para saber mais sobre as propriedades anexadas, veja Visão geral das propriedades anexadas.

Combinando a sintaxe de caminho de propriedade

Você pode combinar vários elementos da sintaxe de caminho de propriedade em uma única cadeia de caracteres. Por exemplo, é possível definir um caminho de propriedade que referencia uma propriedade indexada anexada, se sua fonte de dados tem uma propriedade assim.

Depurando um caminho de propriedade de associação

Como os caminhos de propriedade são interpretados por um mecanismo de associação e dependem de informações que podem estar presentes somente no tempo de execução, muitas vezes é preciso depurar um caminho de propriedade para a associação sem poder contar com o tempo de design convencional ou o suporte de tempo de compilação das ferramentas de desenvolvimento. 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. 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. Para saber mais sobre como usar esse recurso da ferramenta de desenvolvimento, veja a seção "Depuração" do tópico Visão geral da vinculação de dados.

Caminho de propriedade para direcionamento da animação

As animações dependem do direcionamento de uma propriedade de dependência onde valores de storyboard são aplicados quando a animação é reproduzida. Para identificar o objeto no qual a propriedade que deve ser animada existe, a animação direciona um ele por nome (x:Nome). Frequentemente, é necessário definir um caminho de propriedade que começa com o objeto identificado como Storyboard.TargetName e termina com o valor da propriedade de dependência específico na qual a animação deve ser aplicada. Esse caminho de propriedade é usado como valor de Storyboard.TargetProperty.

Para saber mais sobre como definir animações em XAML, veja Animações de storyboard.

Direcionamento simples

Se você está animando uma propriedade que existe no próprio objeto de destino e o tipo dessa propriedade pode ter uma animação aplicada diretamente a ela (em vez de a uma subpropriedade do valor de uma propriedade), você pode simplesmente nomear a propriedade que está sendo animada, sem qualquer outra qualificação. Por exemplo, se você está direcionando uma subclasse de Shape, como Rectangle, e aplicando uma Color animada à propriedade Fill, seu caminho de propriedade pode ser "Fill".

Direcionamento de propriedade indireto

Você pode animar uma propriedade que é uma subpropriedade do objeto de destino. 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. Sempre que você especifica um objeto no qual quer animar uma sub-propriedade, coloque o nome da propriedade entre parênteses e especifique a propriedade no formato typename.propertyname. Por exemplo, para especificar que você quer o valor do objeto da propriedade RenderTransform de um objeto de destino, especifique "(UIElement.RenderTransform)" como primeira etapa no caminho de propriedade. Esse caminho ainda não é completo, pois não há animações que possam se aplicar diretamente a um valor de Transform. Então, nesse exemplo, agora você completa o caminho de propriedade de forma que a propriedade final seja uma propriedade de uma subclasse de Transform que possa ser animada por um valor de Double: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"

Especificando um filho específico em uma coleção

Para especificar um item filho em uma propriedade de coleção, você pode usar um indexador numérico. Use colchetes "[]" ao redor do valor de índice inteiro. Você pode referenciar apenas listas ordenadas, não dicionários. 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.

Por exemplo, para especificar que você quer animar a primeira cor da parada de cor em um LinearGradientBrush aplicado à propriedade Background de um controle, este é o caminho de propriedade: "(Control.Background).(GradientBrush.GradientStops)[0].(GradientStop.Color)". Veja que o indexador não é a última etapa do caminho e que a última etapa deve referenciar especificamente a propriedade GradientStop.Color do item 0 da coleção para aplicar um valor a animado de Color a ela.

Animando uma propriedade anexada

Este não é um cenário comum, mas é possível animar uma propriedade anexada, desde que essa propriedade anexada tenha um valor de propriedade que corresponda a um tipo de animação. 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. 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)".

Observação  Nesse exemplo, o valor de Grid.Row é um tipo de propriedade Int32. Então, não é possível animá-la com uma animação Double. Em vez disso, você pode definir uma ObjectAnimationUsingKeyFrames que tem componentes DiscreteObjectKeyFrame, onde o ObjectKeyFrame.Value é definido como um inteiro, como "0" ou "1".
 

Regras das propriedades em um caminho de propriedade de direcionamento da animação

  • O ponto inicial presumido do caminho de propriedade é o objeto identificado por um Storyboard.TargetName.
  • Todos os objetos e todas as propriedades referenciados ao longo do caminho de propriedade devem ser públicos.
  • 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.
  • A propriedade final deve ter um tipo de propriedade que possa ser animada por uma das classes amplas de tipos de animação (animações de Color, animações de Double, animações de Point, ObjectAnimationUsingKeyFrames).

A classe PropertyPath

A classe PropertyPath é o tipo de propriedade subjacente de Binding.Path para o cenário de associação.

Quase sempre, você pode aplicar um PropertyPath em XAML sem usar nenhum código. Porém, às vezes, você pode querer definir um objeto PropertyPath usando código e atribuí-lo a uma propriedade em tempo de execução.

PropertyPath tem um construtor PropertyPath(String) e não tem um construtor padrão. A cadeia de caracteres que você passa para esse construtor é definida usando a sintaxe de caminho de propriedade, como explicado anteriormente. Essa também é a mesma cadeia de caracteres que você usaria para atribuir Path como um atributo XAML. A única outra API da classe PropertyPath é a propriedade Path, que é somente leitura. Você poderia usar essa propriedade como cadeia de caracteres de construção para outra instância de PropertyPath.

Tópicos relacionados

Visão geral de vinculação de dados
Animações com storyboard
Extensão de marcação de associação
PropertyPath
Binding
Binding constructor
DataContext

 

 

Mostrar:
© 2017 Microsoft