Sintaxe PropertyPath XAML

Artigo
10/18/2023

O PropertyPath objeto oferece suporte a uma sintaxe XAML embutida complexa para definir várias propriedades que tomam o PropertyPath tipo como seu valor. Este tópico documenta a PropertyPath sintaxe aplicada às sintaxes de vinculação e animação.

Onde o PropertyPath é usado

PropertyPath é um objeto comum que é usado em vários recursos do Windows Presentation Foundation (WPF). Apesar de usar o comum PropertyPath para transmitir informações de caminho de propriedade, os usos para cada área de recurso onde PropertyPath é usado como um tipo variam. Portanto, é mais prático documentar as sintaxes por recurso.

Principalmente, o WPF usa PropertyPath para descrever caminhos de modelo de objeto para percorrer as propriedades de uma fonte de dados de objeto e para descrever o caminho de destino para animações de destino.

Algumas propriedades de estilo e modelo, como Setter.Property usar um nome de propriedade qualificado que se assemelha superficialmente a um PropertyPatharquivo . Mas isso não é verdade PropertyPath, em vez disso, é um uso qualificado do formato de cadeia de caracteres owner.property que é habilitado pelo processador XAML WPF em combinação com o conversor de tipo para DependencyProperty.

PropertyPath para objetos em associação de dados

A vinculação de dados é um recurso do WPF pelo qual você pode vincular ao valor de destino de qualquer propriedade de dependência. No entanto, a origem dessa associação de dados não precisa ser uma propriedade de dependência; pode ser qualquer tipo de propriedade que seja reconhecido pelo provedor de dados aplicável. Os caminhos de propriedade são usados particularmente para o ObjectDataProvider, que é usado para obter fontes de vinculação de objetos CLR (Common Language Runtime) e suas propriedades.

Observe que a vinculação de dados ao XML não usa o , porque ele não usa PropertyPath Path no Binding. Em vez disso, use XPath e especifique a sintaxe XPath válida no DOM (Modelo de Objeto de Documento) XML dos dados. XPath também é especificado como uma cadeia de caracteres, mas não está documentado aqui; consulte Vincular a dados XML usando um XMLDataProvider e consultas XPath.

A chave para entender os caminhos da propriedade na associação de dados é que você pode direcionar a associação a um valor da propriedade individual ou, em vez disso, pode associar a propriedades de destino que assumem listas ou coleções. Se você estiver vinculando coleções, por exemplo, vinculando um ListBox que se expandirá dependendo de quantos itens de dados estão na coleção, seu caminho de propriedade deverá fazer referência ao objeto de coleção, não a itens de coleção individuais. O mecanismo de vinculação de dados corresponderá a coleção usada como fonte de dados ao tipo de destino de vinculação automaticamente, resultando em um comportamento como preencher um ListBox com uma matriz de itens.

Propriedade única no objeto imediato como contexto de dados

<Binding Path="propertyName" ... />

propertyName deve resolver ser o nome de uma propriedade que está no atual DataContext para um Path uso. Se a associação atualizar a fonte, essa propriedade deverá ser de leitura/gravação e o objeto de origem deverá ser mutável.

Indexador único no objeto imediato como contexto de dados

<Binding Path="[key]" ... />

O key deve ser o índice tipado para um dicionário ou tabela de hash ou o índice inteiro de uma matriz. Além disso, o valor da chave deve ser um tipo diretamente associável à propriedade em que foi aplicado. Por exemplo, uma tabela de hash que contém chaves de cadeia de caracteres e valores de cadeia de caracteres pode ser usada dessa maneira para vincular ao Text de um TextBoxarquivo . Ou, se a chave apontar para uma coleção ou subíndice, será possível usar essa sintaxe para se associar a uma propriedade de coleção de destino. Caso contrário, será necessário fazer referência a uma propriedade específica, por meio de uma sintaxe como <Binding Path="[key].propertyName" .../>.

Você pode especificar o tipo do índice, se necessário. Para obter detalhes sobre esse aspecto de um caminho de propriedade indexado, consulte Binding.Path.

Propriedade múltipla (direcionamento indireto de propriedade)

<Binding Path="propertyName.propertyName2" ... />

propertyName deve resolver ser o nome de uma propriedade que é o atual DataContext. As propriedades de caminho propertyName e propertyName2 podem ser quaisquer propriedades que existam em uma relação, em que propertyName2 é uma propriedade que existe no tipo que é o valor de propertyName.

Propriedade única, anexada ou de tipo qualificado

<object property="(ownerType.propertyName)" ... />

Os parênteses indicam que essa propriedade em a PropertyPath deve ser construída usando uma qualificação parcial. Ela pode utilizar um namespace de XML para localizar o tipo com um mapeamento apropriado. Os ownerType tipos de pesquisa aos quais um processador XAML tem acesso, por meio das XmlnsDefinitionAttribute declarações em cada assembly. A maioria dos aplicativos tem o namespace de XML padrão mapeado para o namespace http://schemas.microsoft.com/winfx/2006/xaml/presentation; portanto, um prefixo geralmente é necessário apenas para tipos personalizados ou tipos fora desse namespace. O propertyName deve ser o nome de uma propriedade existente no ownerType. Em geral, essa sintaxe é usada para um dos casos a seguir:

O caminho é especificado em XAML que está em um estilo ou modelo que não tem um Tipo de Destino especificado. Um uso qualificado normalmente não é válido para casos diferentes deste, porque, em casos sem estilo e sem modelo, a propriedade existe em uma instância, não em um tipo.
A propriedade é uma propriedade anexada.
A associação é a uma propriedade estática.

Para uso como destino de storyboard, a propriedade especificada como propertyName deve ser um DependencyPropertyarquivo .

Passagem de fonte (associação a hierarquias de coleções)

<object Path="propertyName/propertyNameX" ... />

A / nessa sintaxe é usada para navegar dentro de um objeto de fonte de dados hierárquicos; há suporte para várias etapas para a hierarquia com caracteres / sucessivos. A passagem de fonte explica a posição atual do ponteiro de registro, que é determinada pela sincronização dos dados com a interface do usuário do modo de exibição. Para ver detalhes sobre a associação com objetos de fonte de dados hierárquicos e o conceito do ponteiro de registro atual na associação de dados, consulte Usar o padrão de detalhes mestre com os dados hierárquicos ou Visão geral da associação de dados.

Observação

Superficialmente, essa sintaxe se assemelha a XPath. Uma expressão XPath verdadeira para associação a uma fonte de dados XML não é usada como um Path valor e, em vez disso, deve ser usada para a propriedade mutuamente exclusiva XPath .

Exibições de coleção

Para fazer referência a um modo de exibição de coleção nomeado, o nome do modo de exibição da coleção deve ter o caractere (#) como prefixo.

Ponteiro de registro atual

Para fazer referência ao ponteiro de registro atual para um modo de exibição de coleção ou um cenário de associação de dados com detalhes mestre, inicie a cadeia de caracteres do caminho com uma barra invertida (/). Qualquer caminho após a barra invertida é atravessado por meio do ponteiro de registro atual.

Vários indexadores

<object Path="[index1,index2...]" ... />

<object Path="propertyName[index,index2...]" ... />

Se determinado objeto dá suporte a vários indexadores, eles podem ser especificados em ordem, de forma semelhante a uma sintaxe de referência de matriz. O objeto em questão pode ser o contexto atual ou o valor de uma propriedade que contém um objeto com vários índices.

Por padrão, os valores do indexador são tipados usando as características do objeto subjacente. Você pode especificar o tipo do índice, se necessário. Para obter detalhes sobre como digitar os indexadores, consulte Binding.Path.

Misturando sintaxes

Cada uma das sintaxes mostradas acima pode ser intercalada. Por exemplo, a seguir está um exemplo que cria um caminho de propriedade para a cor em um x,y específico de uma propriedade que contém uma ColorGrid matriz de grade de pixels de SolidColorBrush objetos:

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" ... />

Escapes para cadeias de caracteres de caminho da propriedade

Para determinados objetos de negócios, é possível encontrar um caso em que a cadeia de caracteres de caminho da propriedade requer uma sequência de escape para uma análise correta. A necessidade de escape deve ser rara, pois muitos desses caracteres têm problemas semelhantes de interação de nomenclatura em linguagens que costumam ser usadas para definir o objeto de negócios.

Dentro dos indexadores ([]), o caractere de acento circunflexo (^) pula o próximo caractere.
É necessário pular (usando entidades XML) alguns caracteres que são especiais para a definição da linguagem XML. Use & para pular o caractere "&". Use > para escapar da tag final ">".
É necessário pular (usando a barra invertida \) caracteres que são especiais para o comportamento de analisador de XAML do WPF, para o processamento de uma extensão de marcação.
- A barra invertida (\) é o caractere de escape.
- O sinal de igual (=) separa o nome da propriedade do valor da propriedade.
- A vírgula (,) separa as propriedades.
- A chave direita (}) é o final de uma extensão de marcação.

Observação

Tecnicamente, esses escapes também funcionam para um caminho da propriedade de storyboard; contudo, você normalmente atravessa modelos de objeto para objetos existentes do WPF e o escape deve ser desnecessário.

PropertyPath para destinos de animação

A propriedade de destino de uma animação deve ser uma propriedade de dependência que usa um tipo ou um Freezable tipo primitivo. No entanto, a propriedade direcionada em um tipo e a propriedade animada eventual podem existir em diferentes objetos. No caso de animações, um caminho da propriedade é usado para definir a conexão entre a propriedade do objeto de destino da animação nomeada e a propriedade de animação de destino pretendida, atravessando relações de propriedade do objeto nos valores da propriedade.

Considerações sobre a propriedade de objeto geral para animações

Para obter mais informações sobre conceitos de animação em geral, consulte Visão geral de storyboards e Visão geral da animação.

O tipo de valor ou a propriedade que está sendo animada deve ser um tipo ou um Freezable primitivo. A propriedade que inicia o caminho deve resolver para ser o nome de uma propriedade de dependência que existe no tipo especificado TargetName .

Para dar suporte à clonagem para animar um Freezable que já está congelado, o objeto especificado por TargetName deve ser uma FrameworkElement classe ou FrameworkContentElement derivada.

Propriedade única no objeto de destino

<animation Storyboard.TargetProperty="propertyName" ... />

propertyName deve resolver para ser o nome de uma propriedade de dependência que existe no tipo especificado TargetName .

Direcionamento indireto de propriedade

<animation Storyboard.TargetProperty="propertyName.propertyName2" ... />

propertyName deve ser uma propriedade que é um tipo de valor ou um Freezable primitivo, que existe no tipo especificado TargetName .

propertyName2 deve ser o nome de uma propriedade de dependência que existe no objeto que é o valor de propertyName. Em outras palavras, propertyName2 deve existir como uma propriedade de dependência no tipo que é o propertyNamePropertyType.

O direcionamento indireto de animações é necessário por causa dos estilos e modelos aplicados. Para direcionar uma animação, você precisa de um objeto de TargetName destino e esse nome é estabelecido por x:Name ou Name. Embora os elementos de modelo e estilo também possam ter nomes, esses nomes são válidos somente dentro do escopo de nome do estilo e do modelo. (Se os modelos e estilos compartilhassem namescopes com a marcação do aplicativo, os nomes não poderiam ser exclusivos. Os estilos e modelos são literalmente compartilhados entre instâncias e perpetuariam nomes duplicados.) Assim, se as propriedades individuais de um elemento que você pode querer animar vieram de um estilo ou modelo, você precisa começar com uma ocorrência de elemento nomeado que não é de um modelo de estilo e, em seguida, direcionar para a árvore visual de estilo ou modelo para chegar à propriedade que você deseja animar.

Por exemplo, a propriedade de a Background Panel é um completo Brush (na verdade um ) que veio de um SolidColorBrushmodelo de tema. Para animar um completamente, precisaria haver um BrushAnimation (provavelmente um Brush para cada Brush tipo) e não há esse tipo. Para animar um Pincel, você anima propriedades de um tipo específico Brush . Você precisa ir de SolidColorBrush lá para aplicar um ColorAnimation láColor. O caminho da propriedade para esse exemplo seria Background.Color.

Propriedades Anexadas

<animation Storyboard.TargetProperty="(ownerType.propertyName)" ... />

Os parênteses indicam que essa propriedade em a PropertyPath deve ser construída usando uma qualificação parcial. Ela pode usar um namespace de XML para encontrar o tipo. Os ownerType tipos de pesquisa aos quais um processador XAML tem acesso, por meio das XmlnsDefinitionAttribute declarações em cada assembly. A maioria dos aplicativos tem o namespace de XML padrão mapeado para o namespace http://schemas.microsoft.com/winfx/2006/xaml/presentation; portanto, um prefixo geralmente é necessário apenas para tipos personalizados ou tipos fora desse namespace. O propertyName deve ser o nome de uma propriedade existente no ownerType. A propriedade especificada como propertyName deve ser um DependencyPropertyarquivo . (Todas as propriedades anexadas do WPF são implementadas como propriedades de dependência, portanto, esse problema só preocupa as propriedades anexadas personalizadas.)

Indexadores

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" ... />

A maioria das propriedades ou Freezable tipos de dependência não oferece suporte a um indexador. Portanto, o único uso para um indexador em um caminho de animação é em uma posição intermediária entre a propriedade que inicia a cadeia no destino nomeado e a propriedade animada eventual. Na sintaxe fornecida, é propertyName2. Por exemplo, um uso de indexador pode ser necessário se a propriedade intermediária for uma coleção como TransformGroup, em um caminho de propriedade como RenderTransform.Children[1].Angle.

PropertyPath em código

O uso de código para PropertyPath, incluindo como construir um PropertyPath, está documentado no tópico de referência do PropertyPath.

Em geral, é projetado para usar dois construtores diferentes, um para os usos de vinculação e usos de animação mais simples, PropertyPath e um para os usos de animação complexa. Use a PropertyPath(Object) assinatura para usos de vinculação, em que o objeto é uma cadeia de caracteres. Use a PropertyPath(Object) assinatura para caminhos de animação de uma etapa, em que o objeto é um DependencyPropertyarquivo . Use a PropertyPath(String, Object[]) assinatura para animações complexas. Esse último construtor usa uma cadeia de caracteres de token para o primeiro parâmetro e uma matriz de objetos que preenchem posições na cadeia de caracteres de token para definir uma relação de caminho da propriedade.