Sintaxe PropertyPath XAML

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

Onde o PropertyPath é usado

PropertyPath é um objeto comum 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 feição em que 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 direcionadas.

Algumas propriedades de estilo e modelo, como Setter.Property usar um nome de propriedade qualificado que superficialmente se assemelha a um PropertyPath. 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 do WPF em combinação com o conversor de tipo para DependencyProperty.

PropertyPath para objetos em associação de dados

A associação de dados é um recurso do WPF pelo qual você pode associar 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 associação de objetos CLR (Common Language Runtime) e suas propriedades.

Observe que a vinculação de dados ao XML não usa PropertyPath, porque não usa Path no Binding. Em vez disso, você usa XPath e especifica a sintaxe XPath válida no DOM (Document Object Model) 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 associando coleções, por exemplo, associando um ListBox que se expandirá dependendo de quantos itens de dados estão na coleção, o caminho da propriedade deverá fazer referência ao objeto de coleção, não a itens de coleção individuais. O mecanismo de associação de dados corresponderá a coleção usada como fonte de dados ao tipo do destino de associação automaticamente, resultando em um comportamento como preencher uma ListBox matriz com itens.

Propriedade única no objeto imediato como contexto de dados

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

propertyName deve ser resolvido como o nome de uma propriedade que está no current 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 a um TextBoxfórum de texto . 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" ... />

propertyNamedeve ser resolvido como o nome de uma propriedade que é o domínio .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 DependencyProperty.

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.

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...]" ... />

ou

<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 determinado x,y de uma ColorGrid propriedade que contém uma matriz de objetos de grade de SolidColorBrush pixels:

<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.

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 primitivo ou primitivo Freezable . 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 Freezable tipo ou um primitivo. A propriedade que inicia o caminho deve ser resolvida como 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 ser resolvido 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 seja um tipo de Freezable valor ou um 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 TargetName em um objeto de 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 modelos e estilos compartilhassem namescopes com marcação de aplicativo, os nomes não poderiam ser exclusivos. Os estilos e modelos são literalmente compartilhados entre instâncias e perpetuariam nomes duplicados.) Portanto, se as propriedades individuais de um elemento que você deseja animar vieram de um estilo ou modelo, você precisará começar com uma instância de elemento nomeado que não seja de um modelo de estilo e, em seguida, direcionar para a árvore visual de estilo ou modelo para chegar à propriedade que deseja animar.

Por exemplo, a Background propriedade de a Panel é um completo Brush (na verdade, um SolidColorBrush) que veio de um modelo de tema. Para animar um Brush completamente, seria necessário haver um BrushAnimation (provavelmente um para cada Brush tipo) e não existe esse tipo. Para animar um Brush, você anima propriedades de um tipo específico Brush . Você precisa ir de SolidColorBrush para o seu Color para aplicar um ColorAnimation lá. 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 DependencyProperty. (Todas as propriedades anexadas do WPF são implementadas como propriedades de dependência, portanto, esse problema é preocupante apenas para propriedades anexadas personalizadas.)

Indexadores

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

A maioria das propriedades ou Freezable tipos de dependência não dá 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 do 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 para PropertyPath.

Em geral, PropertyPath foi projetado para usar dois construtores diferentes, um para os usos de associação e usos de animação mais simples e outro para os usos de animação complexos. Use a PropertyPath(Object) assinatura para usos de associaçã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.

Confira também

• PropertyPath
• Visão geral da vinculação de dados
• Visão geral de storyboards