Compartilhar via

Sintaxe XAML do PropertyPath

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

Onde o PropertyPath é usado

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

Principalmente, o WPF usa PropertyPath para descrever caminhos do modelo de objeto para navegar nas 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, têm um nome de propriedade qualificado que se assemelha superficialmente a um PropertyPath. Mas isso não é um verdadeiro PropertyPath; em vez disso, é um uso qualificado do formato de string owner.property habilitado pelo processador XAML do WPF em conjunto com o conversor de tipos para DependencyProperty.

Caminho de Propriedade para Objetos na Vinculação de Dados

A associação de dados é um recurso do WPF que permite vincular o valor alvo 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 reconhecido pelo provedor de dados aplicável. Os caminhos de propriedade são particularmente usados para o ObjectDataProvider, que é usado para obter fontes de associação de objetos CLR (Common Language Runtime) e suas propriedades.

Observe que a associação de dados ao XML não usa PropertyPath, porque não se usa 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 Associar a dados XML usando consultas XMLDataProvider e XPath.

Uma chave para entender os caminhos de propriedade na associação de dados é que você pode direcionar a associação a um valor de propriedade individual ou, em vez disso, você pode associar a propriedades de destino que levam listas ou coleções. Se você estiver associando coleções, por exemplo, associando uma ListBox que será expandida dependendo de quantos itens de dados estão na coleção, o caminho da propriedade deverá referenciar o objeto de coleção, não itens de coleção individuais. O mecanismo de vinculação de dados corresponderá automaticamente a coleção usada como fonte de dados ao tipo do destino de vinculação, resultando em ações como preencher um ListBox com uma matriz de itens.

Propriedade única no objeto imediato como contexto de dados

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

propertyName deve se resolver para ser o nome de uma propriedade que esteja no DataContext atual para um uso Path. Se a associação atualizar a origem, 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]" ... />

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 que seja diretamente associável à propriedade em que ela é aplicada. Por exemplo, uma tabela de hash que contém chaves e valores de texto pode ser usada dessa forma para vincular ao texto para um TextBox. Ou, se a chave apontar para uma coleção ou subíndice, você poderá usar essa sintaxe para associar a uma propriedade de coleção de destino. Caso contrário, você precisará referenciar 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 ser o nome de uma propriedade que é a atual DataContext. As propriedades propertyName e propertyName2 do caminho podem ser quaisquer propriedades que existam em uma relação, onde propertyName2 é uma propriedade que existe no tipo que constitui o valor de propertyName.

Propriedade individual, anexada ou não Type-Qualified

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

Os parênteses indicam que essa propriedade em um PropertyPath deve ser construída usando uma qualificação parcial. Ele pode usar um namespace XML para localizar o tipo com um mapeamento apropriado. Os ownerType procura tipos aos quais um processador XAML tem acesso, por meio das XmlnsDefinitionAttribute declarações 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 necessário apenas para tipos personalizados ou tipos fora desse namespace. propertyName deve resolver ser o nome de uma propriedade existente no ownerType. Essa 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, pois em casos que não envolvem estilo ou modelo, a propriedade existe em uma instância, não em um tipo.

  • A propriedade é uma propriedade anexada.

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

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

Passagem de fonte (vinculação a coleções hierárquicas)

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

A /nesta sintaxe é usada para navegar dentro de um objeto de fonte de dados hierárquica e há suporte para várias etapas na hierarquia com caracteres/sucessivos. A navegação da fonte considera a posição atual do ponteiro de registro, que é determinada pela sincronização dos dados com a interface do usuário da visualização. Para obter detalhes sobre a vinculação com objetos de fonte de dados hierárquica e o conceito do ponteiro de registro atual na vinculação de dados, consulte Usar 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 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 uma exibição de coleção nomeada, prefixe o nome da exibição da coleção com o caractere hash (#).

Ponteiro de Registro Atual

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

Vários indexadores

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

ou

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

Se um determinado objeto der suporte a vários indexadores, esses indexadores poderão 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 do índice, se necessário. Para obter detalhes sobre como digitar os indexadores, consulte Binding.Path.

Combinando sintaxes

Cada uma das sintaxes mostradas acima pode ser intercalada. Por exemplo, o seguinte é um exemplo que cria um caminho de propriedade para a cor em coordenadas x, y específicas de uma propriedade ColorGrid que contém uma grade de pixels em forma de matriz de objetos SolidColorBrush.

<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 de caminho de propriedade requer uma sequência de escape para analisar corretamente. A necessidade de escape deve ser rara, pois muitos desses caracteres têm problemas de nomenclatura e interação semelhantes em idiomas que normalmente seriam usados para definir o objeto de negócios.

  • Dentro dos indexadores ([ ]), o caractere circunflexo (^) escapa o próximo caractere.

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

  • Você deve escapar os caracteres que são especiais para o comportamento do analisador XAML do WPF (usando a barra invertida \) para processar uma extensão de marcação.

    • Barra invertida (\) é o próprio caractere de escape.

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

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

    • A chave de fechamento direita (}) é o fim de uma extensão de marcação.

Observação

Tecnicamente, esses escapes também funcionam para um caminho de propriedade de storyboard, mas, geralmente, você está percorrendo modelos de objetos para objetos WPF existentes, tornando o escape desnecessário.

PropertyPath para destinos de animação

A propriedade de destino de uma animação deve ser uma propriedade de dependência que utiliza um Freezable ou um tipo primitivo. No entanto, a propriedade direcionada em um tipo e a propriedade animada final podem existir em diferentes objetos. 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 da propriedade.

Considerações gerais sobre Object-Property 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 Freezable ou um tipo primitivo. A propriedade que inicia o caminho deve resolver 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 classe FrameworkElement ou derivada de FrameworkContentElement.

Propriedade única no objeto de destino

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

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

Direcionamento de propriedade indireta

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

propertyName deve ser uma propriedade que seja um Freezable tipo de 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 devido a estilos e modelos aplicados. Para direcionar uma animação, você precisa de um TargetName objeto de destino e esse nome é estabelecido por x:Name ou Name. Embora 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 compartilharem namescopes com marcação de aplicativo, os nomes não poderão 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 talvez você queira animar vieram de um estilo ou modelo, você precisará começar com uma instância de elemento nomeada 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 você deseja animar.

Por exemplo, a propriedade Background de um Panel é um Brush integrado (na verdade, um SolidColorBrush) que se originou de um modelo de tema. Para animar completamente Brush , seria necessário haver um BrushAnimation (provavelmente um para cada Brush tipo) e não há esse tipo. Para animar um Brush, em vez disso, anime as propriedades de um tipo específico Brush . Você precisa ir do SolidColorBrush para o 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 essa propriedade em um PropertyPath deve ser construída usando uma qualificação parcial. Ele pode usar um namespace XML para localizar o tipo. Os ownerType procura tipos aos quais um processador XAML tem acesso, por meio das XmlnsDefinitionAttribute declarações 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 necessário apenas para tipos personalizados ou tipos fora desse namespace. propertyName deve resolver 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 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 está em uma posição intermediária entre a propriedade que inicia a cadeia no destino nomeado e a propriedade animada eventual. Na sintaxe fornecida, isto é propertyName2. Por exemplo, um uso de indexador poderá 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 no 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 usos de associação e usos de animação mais simples e outro para os usos complexos de animação. 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 etapa única, em que o objeto é um DependencyProperty. Use a PropertyPath(String, Object[]) assinatura 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.

Consulte também

  • Last updated on