Partilhar via

Sintaxe XAML PropertyPath

  • Artigo

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

Onde PropertyPath é usado

PropertyPath é um objeto comum que é usado em vários recursos do Windows Presentation Foundation (WPF). Apesar de usar o PropertyPath comum para transmitir informações de caminho de propriedade, os usos para cada área funcional 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 objetos 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 usam um nome de propriedade qualificado que se assemelha superficialmente a um PropertyPath. Mas esta não é uma verdadeira PropertyPath; em vez disso, é um qualificado owner.property uso de formato de cadeia de caracteres que é habilitado pelo processador WPF XAML em combinação com o conversor de tipo para DependencyProperty.

PropertyPath para objetos na vinculaçã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 fonte dessa ligação de dados não precisa ser uma propriedade de dependência; Pode ser qualquer tipo de propriedade reconhecida pelo provedor de dados aplicável. Os caminhos de propriedade são particularmente usados 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 PropertyPath, porque não usa Path no Binding. Em vez disso, use XPath e especifique sintaxe XPath válida no DOM (Document Object Model) XML dos dados. XPath também é especificado como uma string, mas não está documentado aqui; está documentado em Vincular a dados XML usando um XMLDataProvider e consultas XPath.

Uma chave para entender os caminhos de propriedade na associação de dados é que você pode direcionar a associação para um valor de propriedade individual ou, em vez disso, pode vincular a propriedades de destino que usam listas ou coleções. Se você estiver vinculando coleções, por exemplo, vinculando um ListBox que será expandido 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 fará a correspondência entre a coleção usada como fonte de dados e o 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 DataContext atual para um uso Path. Se sua associação atualizar a fonte, essa propriedade deverá ser lida/gravada e o objeto de origem deverá ser mutável.

Indexador único no objeto imediato como contexto de dados

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

key deve ser o índice digitado 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 que seja diretamente vinculável à propriedade onde ela é aplicada. Por exemplo, uma tabela de hash que contém strings como chaves e valores pode ser usada desta forma para se ligar ao texto para um TextBox. Ou, se a chave apontar para uma coleção ou subíndice, você poderá usar essa sintaxe para vincular a uma propriedade de coleção de destino. Caso contrário, você precisará fazer referência a uma propriedade específica, por meio de uma sintaxe como <Binding Path="[key].propertyName" .../>.

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

Propriedades múltiplas (alvo indireto de propriedade)

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

propertyName deve ser definido como o nome de uma propriedade que é o DataContextatual. As propriedades de caminho propertyName e propertyName2 podem ser quaisquer propriedades que existam numa relação, onde propertyName2 é uma propriedade que existe no tipo que é o valor de propertyName.

Propriedade única, anexa ou de outra forma Type-Qualified

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

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

  • O caminho é especificado em XAML que está em um estilo ou modelo que não tem um Tipo de Destino especificado. Um uso qualificado geralmente 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 anexa.

  • Você está vinculando a uma propriedade estática.

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

Source Traversal (Ligação a hierarquias de coleções)

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

O "/" nesta sintaxe é usado para navegar através de um objeto de fonte de dados hierárquico, e são suportadas várias etapas na hierarquia com o uso sucessivo de caracteres "/". O percurso da fonte leva em consideração a posição atual do ponteiro do registo, determinada pela sincronização dos dados com a interface de utilizador da sua visualização. Para obter detalhes sobre a associação com objetos de fonte de dados hierárquicos e o conceito de ponteiro de registro atual na vinculação de dados, consulte O padrão Master-Detail com dados hierárquicos ou Visão geral da vinculação de dados.

Observação

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

Visualizações de Coleção

Para fazer referência a uma exibição de coleção nomeada, prefixe o nome da exibição de coleção com o caractere de hash (#).

Ponteiro de registro atual

Para fazer referência ao ponteiro do registo atual para uma vista de coleção ou cenário de vinculação de dados de detalhes mestre, inicie o caminho com uma barra (/). Qualquer caminho além da barra é percorrido a partir do ponteiro de registro atual.

Vários indexadores

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

ou

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

Se um determinado objeto suportar vários indexadores, esses indexadores podem ser especificados em ordem, 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 de índice múltiplo.

Por padrão, os valores do indexador são digitados usando as características do objeto subjacente. Você pode especificar o tipo de í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, segue um exemplo que cria um caminho de propriedade para a cor num x,y específico da propriedade ColorGrid, que contém uma matriz de objetos SolidColorBrush organizados em um grid de pixels.

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

Escapes para strings de caminho de propriedade

Para determinados objetos de negócios, você pode encontrar um caso em que a cadeia de caracteres do caminho da propriedade requer uma sequência de escape para analisar corretamente. A necessidade de escapar deve ser rara, porque muitos desses caracteres têm problemas semelhantes de interação de nomenclatura em linguagens que normalmente seriam usadas para definir o objeto comercial.

  • Dentro dos indexadores ([ ]), o caractere de acento circunflexo (^) escapa do caractere seguinte.

  • Você deve escapar (usando entidades XML) de determinados caracteres que são especiais para a definição da linguagem XML. Use & para escapar do personagem "&". Use > para escapar a etiqueta de encerramento ">".

  • Você deve fazer escape (usando a barra invertida \) dos caracteres especiais para o comportamento do analisador de XAML do WPF ao processar uma extensão de marcação.

    • Backslash (\) é o próprio personagem de fuga.

    • O sinal de igual (=) separa o nome de uma propriedade do respetivo valor.

    • A vírgula (,) separa as propriedades.

    • A cinta direita (}) é o final de uma extensão de marcação.

Observação

Tecnicamente, estas sequências de escape também funcionam para um caminho de propriedade de storyboard, mas você geralmente está a percorrer modelos de objeto para objetos WPF existentes, e as sequências de escape devem ser desnecessárias.

PropertyPath para destinos de animação

A propriedade de destino de uma animação deve ser uma propriedade de dependência que aceita um tipo Freezable ou um tipo primitivo. No entanto, a propriedade alvo num tipo e a eventual propriedade animada podem estar presentes em objetos diferentes. Para animações, um caminho de propriedade é usado para definir a conexão entre a propriedade do objeto de destino de animação nomeado e a propriedade de animação de destino pretendida, percorrendo relações objeto-propriedade nos valores de propriedade.

Considerações gerais Object-Property para animações

Para mais informações sobre conceitos de animação em geral, consulte a Visão Geral dos Guiões Gráficos e a Introdução à Animação .

O tipo de valor ou a propriedade que está a ser animada deve ser de tipo Freezable ou um valor primitivo. A propriedade que inicia o caminho deve corresponder ao nome de uma propriedade dependente que existe no tipo TargetName especificado.

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

Propriedade única no objeto de destino

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

propertyName deve ser o nome de uma propriedade de dependência existente no tipo TargetName especificado.

Alvo indireto de propriedades

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

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

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 do tipo que é o propertyNamePropertyType.

A segmentação indireta de animações é necessária devido aos 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ó são válidos dentro do namescope do estilo e do modelo. (Se modelos e estilos compartilhassem âmbitos de nomes com a marcação da aplicação, 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ê deseja animar forem provenientes de um estilo ou modelo, você precisa começar com uma instância de elemento nomeado que não provenha de um modelo de estilo e, em seguida, direcionar-se para a árvore visual do estilo ou modelo a fim de chegar à propriedade que deseja animar.

Por exemplo, a propriedade Background de um Panel é um Brush completo (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 tipo Brush) e não existe esse tipo. Para animar um Pincel, em vez disso, anime as propriedades de um determinado tipo de Brush. Você precisa ir do SolidColorBrush ao seu Color para aplicar um ColorAnimation lá. O caminho da propriedade para este exemplo seria Background.Color.

Propriedades anexadas

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

Os parênteses indicam que esta propriedade num/a PropertyPath deve ser construída usando uma qualificação parcial. Ele pode usar um namespace XML para localizar o tipo. O ownerType pesquisa os tipos aos quais um processador XAML tem acesso, por meio das declarações XmlnsDefinitionAttribute em cada assemblagem. A maioria dos aplicativos tem o namespace XML padrão mapeado para o namespace http://schemas.microsoft.com/winfx/2006/xaml/presentation, portanto, um prefixo geralmente só é necessário para tipos personalizados ou tipos fora desse namespace. 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 é apenas preocupante para propriedades anexadas personalizadas.)

Indexadores

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

A maioria das propriedades de dependência ou tipos de Freezable 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 eventual propriedade animada. Na sintaxe fornecida, isso é 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 para PropertyPath.

Em geral, PropertyPath é projetado para usar dois construtores diferentes, um para os usos de vinculação e usos de animação mais simples, e outro para os usos de animação complexa. Use a assinatura PropertyPath(Object) para usos de vinculação, onde o objeto é uma cadeia de caracteres. Utilize a assinatura PropertyPath(Object) para caminhos de animação de etapa única, onde o objeto é um DependencyProperty. Use a assinatura PropertyPath(String, Object[]) para animações complexas. Este ú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 de propriedade.

Ver também