Partilhar via

Sintaxe de Property-path

  • Artigo

Você pode usar a classe PropertyPath e a sintaxe de cadeia de caracteres para instanciar um valor PropertyPath em XAML ou em código. Os valores PropertyPath são usados pela associação de dados. Uma sintaxe semelhante é usada para direcionar animações com storyboard. Para ambos os 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 em XAML. Você pode usar a mesma sintaxe de cadeia de caracteres para construir um PropertyPath que define um Binding no código ou para definir um destino de animação no código usando SetTargetProperty. Há duas áreas de recursos distintas no Tempo de Execução do Windows que usam um caminho de propriedade: associação de dados e direcionamento de animação. O direcionamento de animação não cria valores de sintaxe de caminho de propriedade 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 travessia de propriedade de objeto são muito semelhantes. A associação de dados e a animação direcionada avaliam um caminho de propriedade de maneira ligeiramente diferente, portanto, descrevemos 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 associaçã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 Microsoft .NET ou C++). Ou o objeto de origem do valor de 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 dos relacionamentos objeto-propriedade no grafo de objeto do objeto de negócios.

Você pode associar a um valor de propriedade individual ou a uma propriedade de destino que contém listas ou coleções. Se a origem for uma coleção ou se o caminho especificar uma propriedade de coleção, o mecanismo de associação de dados corresponderá aos itens de coleção da origem ao destino da associação, resultando em um comportamento como preencher uma ListBox com uma lista de itens de uma coleção de fonte de dados sem a necessidade de antecipar os itens específicos nessa coleção.

Percorrendo um grafo de objeto

O elemento da sintaxe que denota a passagem de uma relação objeto-propriedade em um grafo de objeto é o caractere de ponto (.). Cada ponto em uma cadeia de caracteres de caminho de propriedade indica uma divisão entre um objeto (lado esquerdo do ponto) e uma propriedade desse objeto (lado direito do ponto). A cadeia de caracteres é avaliada da esquerda para a direita, o que permite percorrer várias relações de propriedade de objeto. Vejamos um exemplo:

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

Veja como esse caminho é avaliado:

  1. O objeto de contexto de dados (ou uma Fonte especificada pela mesma Associação) é pesquisado por uma propriedade chamada "Cliente".
  2. O objeto que é o valor da propriedade "Customer" é pesquisado por uma propriedade chamada "Address".
  3. O objeto que é o valor da propriedade "Address" é pesquisado por uma propriedade chamada "StreetAddress1".

Em cada uma dessas etapas, o valor é tratado como um objeto. O tipo do resultado é verificado somente quando a associação é aplicada a uma propriedade específica. Este exemplo falharia se "Address" fosse apenas um valor de cadeia de caracteres que não expusesse qual parte da cadeia de caracteres era o endereço. Normalmente, a ligação está apontando para os valores de propriedade aninhados específicos de um objeto de negócios que tem uma estrutura de informações conhecida e deliberada.

Regras para as propriedades em um caminho de propriedade de associação de dados

  • Todas as propriedades referenciadas por um caminho de propriedade devem ser públicas no objeto de negócios de origem.
  • A propriedade end (a propriedade que é a última propriedade nomeada no caminho) deve ser pública e deve ser mutável – você não pode associar a valores estáticos.
  • A propriedade end deverá ser leitura/gravação se esse caminho for usado como as informações de caminho para uma associação bidirecional.

Indexadores

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

Por exemplo, considere um objeto de negócios em que há uma lista de "Equipes" (lista ordenada), cada uma com um dicionário de "Jogadores" em que cada jogador é digitado pelo sobrenome. Um exemplo de caminho de propriedade para um jogador específico na segunda equipe é: "Equipes[1]. Jogadores [Smith]". (Você usa 1 para indicar o segundo item em "Equipes" porque a lista é indexada a zero.)

Observação O suporte à indexação para fontes de dados C++ é limitado; consulte Associação de dados em detalhes.

Propriedades anexadas

Os caminhos de propriedade podem incluir referências a propriedades anexadas. Como o nome de identificação de uma propriedade anexada já inclui um ponto, você deve colocar qualquer nome de propriedade anexada entre parênteses para que o ponto não seja tratado como uma etapa de propriedade de objeto. Por exemplo, a cadeia de caracteres para especificar que você deseja usar Canvas.ZIndex como um caminho de associação é "(Canvas.ZIndex)". Para obter mais informações sobre propriedades anexadas, consulte Visão geral das propriedades anexadas.

Combinando a sintaxe do caminho da propriedade

Você pode combinar vários elementos da sintaxe do caminho de propriedade em uma única cadeia de caracteres. Por exemplo, você pode definir um caminho de propriedade que faça referência a uma propriedade anexada indexada, se sua fonte de dados tiver essa propriedade.

Depurando um caminho de propriedade de associação

Como um caminho de propriedade é interpretado por um mecanismo de associação e depende de informações que podem estar presentes apenas em tempo de execução, muitas vezes você deve depurar um caminho de propriedade para associação sem poder contar com o suporte convencional em tempo de design ou tempo de compilação nas ferramentas de desenvolvimento. Em muitos casos, o resultado em tempo de execução da falha ao resolver um caminho de propriedade é um valor em branco sem erro, pois esse é o comportamento de fallback por design da resolução de associação. Felizmente, o Microsoft Visual Studio fornece um modo de saída de depuração que pode isolar qual parte de um caminho de propriedade que está especificando uma fonte de associação não foi resolvida. Para obter mais informações sobre como usar esse recurso de ferramenta de desenvolvimento, consulte a seção "Depuração" de Associação de dados em detalhes.

Caminho da propriedade para direcionamento de animação

As animações dependem do direcionamento de uma propriedade de dependência em que os valores do storyboard são aplicados quando a animação é executada. Para identificar o objeto em que existe a propriedade a ser animada, a animação tem como destino um elemento pelo nome (atributo x:Name). Geralmente, é necessário definir um caminho de propriedade que comece com o objeto identificado como Storyboard.TargetName e termine com o valor da propriedade de dependência específica em que a animação deve ser aplicada. Esse caminho de propriedade é usado como o valor para Storyboard.TargetProperty.

Para obter mais informações sobre como definir animações em XAML, consulte Animações com storyboard.

Segmentação simples

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

Segmentação indireta de propriedades

Você pode animar uma propriedade que é uma subpropriedade do objeto de destino. Em outras palavras, se houver uma propriedade do objeto de destino que seja um objeto em si, e esse objeto tiver propriedades, você deverá definir um caminho de propriedade que explique como percorrer essa relação objeto-propriedade. Sempre que você estiver especificando um objeto no qual deseja animar uma subpropriedade, coloque o nome da propriedade entre parênteses e especifique a propriedade em typename.formato propertyname . Por exemplo, para especificar que você deseja o valor do objeto da propriedade RenderTransform de um objeto de destino, especifique "(UIElement.RenderTransform)" como a primeira etapa no caminho da propriedade. Esse ainda não é um caminho completo, pois não há animações que possam ser aplicadas diretamente a um valor de Transformação . Portanto, para este exemplo, agora você conclui o caminho da propriedade para que a propriedade end seja uma propriedade de uma subclasse Transform que pode ser animada por um valor 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 caracteres entre colchetes "[]" ao redor do valor do índice inteiro. Você pode fazer referência apenas a listas ordenadas, não a dicionários. Como uma coleção não é um valor que pode ser animado, um uso do indexador nunca pode ser a propriedade end em um caminho de propriedade.

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

Animando uma propriedade anexada

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 de identificação de uma propriedade anexada já inclui um ponto, você deve colocar qualquer nome de propriedade anexada entre parênteses para que o ponto não seja tratado como uma etapa de propriedade de objeto. Por exemplo, a cadeia de caracteres para especificar que você deseja animar a propriedade anexada Grid.Row em um objeto, use o caminho da propriedade "(Grid.Row)".

Observação Para este exemplo, o valor de Grid.Row é um tipo de propriedade Int32. então você não pode animá-lo com uma animação dupla . Em vez disso, você definiria um ObjectAnimationUsingKeyFrames que tenha componentes DiscreteObjectKeyFrame, em que o ObjectKeyFrame.Value é definido como um número inteiro como "0" ou "1".

Regras para as propriedades em uma animação direcionando o caminho da propriedade

  • O ponto de partida presumido do caminho da propriedade é o objeto identificado por um Storyboard.TargetName.
  • Todos os objetos e propriedades referenciados ao longo do caminho da propriedade devem ser públicos.
  • A propriedade end (a propriedade que é a última propriedade nomeada no caminho) deve ser pública, ser de leitura/gravação e ser uma propriedade de dependência.
  • A propriedade end deve ter um tipo de propriedade que possa ser animado por uma das classes amplas de tipos de animação (animações coloridas, animações duplas, animações de ponto, ObjectAnimationUsingKeyFrames).

A classe PropertyPath

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

Na maioria das vezes, você pode aplicar um PropertyPath em XAML sem usar nenhum código. Mas, em alguns casos, talvez você queira 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 é uma cadeia de caracteres definida usando a sintaxe do caminho da propriedade, conforme explicamos 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ê pode usar essa propriedade como a cadeia de caracteres de construção para outra instância de PropertyPath .