Sintaxe de um PropertyPath XAML
O objeto PropertyPath suporta uma sintaxe inline XAML complexa para definir várias propriedades que recebam o tipo PropertyPath como seu valor. Este tópico documenta a sintaxe de um PropertyPath conforme aplicado a vinculação e animação.
Este tópico contém as seguintes seções.
- Onde PropertyPath é usado
- PropertyPath para objetos em associação de dados
- PropertyPath de alvos de animação
- PropertyPath em código
- Tópicos relacionados
Onde PropertyPath é usado
PropertyPath é um objeto comum usado em vários recursos Windows Presentation Foundation (WPF). Apesar do uso de um PropertyPath comum para transmitir informações de caminho de propriedade, os usos para cada tipo de recurso onde PropertyPath é usado como um tipo variam. Portanto, é mais prático documentar as sintaxes por recurso.
Basicamente, WPF usa PropertyPath para descrever caminhos objeto-modelo para percorrer as propriedades de um objeto fonte de dados e para descrever o caminho de destinos para animações com targets.
Algumas propriedades de estilo e modelo como Setter.Property recebem um nome de propriedade qualificado (de acordo com requisitos específicos) e que superficialmente lembra uma PropertyPath . Mas isso não é um verdadeiro PropertyPath; em vez disso, é um qualificado proprietário.propriedade seqüência de caracteres de formato uso ativado pelo XAML processador em combinação com o conversor de tipo para DependencyProperty.
PropertyPath para objetos em associação de dados
Associação de dados é um recurso WPF onde você pode associar dados ao valor de destino de qualquer propriedade de dependência . No entanto, a origem de tal 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. Caminhos de propriedade são usados principalmente para o ObjectDataProvider, que é usado para obter fontes de vinculação de objetos common language runtime (CLR) e suas propriedades.
Observe que associação de dados com XML não usa PropertyPath, pois não usa Path no Binding. Em vez disso, se usa XPath e especifica-se sintaxe XPath válida no XML Document Object Model (DOM) dos dados. XPath também é pode ser especificado como uma sequência de caracteres, mas isto não está documentado aqui; consulte Como: Bind to XML Data Using an XMLDataProvider and XPath Queries.
A chave para entender caminhos de propriedade em associação de dados é que você pode direcionar a vinculação a um valor de propriedade individual, ou à propriedades de destino que recebam listas ou coleções. Se você estiver associando coleções, então seu caminho de propriedade deve fazer referência a uma coleção, não a itens individuais de uma coleção. O mecanismo de associação de dados fará o casamento das coleções de fonte e destino automaticamente, resultando em comportamentos como popular um ListBox com um vetor de itens.
Propriedade única no próprio objeto como contexto de dados
<Binding Path="propertyName" .../>
propertyName deve ser resolvido para o nome de uma propriedade que esteja no DataContext atual para o uso em um Path. Se a vinculação atualiza a fonte, essa propriedade deve ser de leitura/gravação e o objeto de origem deve ser mutável.
Indexador único no próprio objeto 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 um vetor. Além disso, o valor da chave deve ser um tipo que seja diretamente associável à propriedade a que ele será aplicado. Por exemplo, um tabela de hash que contenha sequência de caracteres como chaves e valores pode ser usada dessa maneira para associar um texto a uma TextBox. Ou, se a chave aponta para uma coleção ou subindex, você pode usar essa sintaxe para fazer a associação a uma propriedade da coleção de destino. Otherwise, you need to reference a specific property, through a syntax such as <Binding Path="[key].propertyName" .../>.
Você pode especificar o tipo do índice, se necessário. Para obter detalhes sobre esse aspecto de caminho de propriedade indexado, consulte Binding.Path.
Propriedades múltiplas (definição indireta de propriedade de destino)
<Binding Path="propertyName.propertyName2" .../>
propertyName deve ser resolvido para o nome de uma propriedade que seja o atual DataContext. As propriedades de caminho propertyName e propertyName2 podem ser quaisquer propriedades que existam em um relacionamento, onde propertyName2 é uma propriedade que existe no tipo que é o valor de propertyName.
Propriedade única, fora do escopo de nomes de carga do XAML, Reflexão em tempo de execução
<object property="ownerType.propertyName" .../>
Essa sintaxe é exclusivamente para caminho de fonte para uma vinculação de dados para um CLR propriedade, e só pode ser um caminho de etapa única em Propriedades. propertyName deve resolver o nome de uma propriedade existente no ownerType. ownerType deve ser do tipo de pode ser encontrado com base no time de execução de reflexão. sistema autônomo tal, não é legal para qualificar ownerType com um prefixo de namespace de XML, sistema autônomo um prefixo de tal não tem nenhum significado para reflexão, somente a time de compilar XAML. Consulte a próxima seção.
Propriedade única, anexada ou aguardando contexto através de estilo/modelo
<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 de XML para localizar o tipo. O ownerType procura tipos aos quais um processador XAML tenha acesso, por meio de declarações XmlnsDefinitionAttribute em cada conjunto de módulos (assembly). A maioria dos aplicativos possui o namespace de XML padrão mapeado para o https://schemas.microsoft.com/winfx/2006/xaml/presentation espaço para nome, para que um prefixo normalmente só é necessário para tipos personalizados ou tipos de outra forma fora desse namespace. propertyName deve resolver o nome de uma propriedade existente no ownerType. Essa sintaxe é geralmente usada em um dos seguintes casos:
O caminho é especificado em XAML que é um estilo ou modelo que não tem um tipo de destino especificado. Um uso qualificado geralmente é inválido para outros casos que não este, pois em casos sem-estilo, não de modelo, a propriedade existe em uma instância, não em um tipo.
A propriedade é uma propriedade anexada.
Você estiver fazendo associação a um propriedade estática. Nesse caso, ownerType realmente é um tipo.
Para ser usado como alvo em um storyboard, a propriedade especificada como propertyName deve ser uma DependencyProperty.
Percorrendo Fonte (associação a hierarquias de coleções)
<object Path="propertyName/propertyNameX" .../>
A / nesta sintaxe é usada para navegar dentro de um objeto fonte de dados hierárquica; e vários níveis na hierarquia com sucessivas / são suportadas. O percorrimento da fonte leva em conta a posição do ponteiro para o registro atual, que é determinada pela sincronização dos dados com a interface do usuário de seu modo de exibição. Para obter detalhes sobre associação com objetos fonte de dados hierárquica e o conceito de ponteiro para o registro atual em associação de dados, consulte Como: Use the Master-Detail Pattern with Hierarchical Data ou Revisão de Associação de Dados.
.gif "Observação") Observação: |
|---|
Superficially, essa sintaxe semelhante XPath. Uma expressão XPath verdadeira para associação a uma fonte de dados XML não é usada como um valor Path e, em vez disso, deve ser usada para a propriedade mutuamente exclusiva XPath. |
Múltiplos Indexadores
<object Path="[index1,index2...]" .../>
or
<object Path="propertyName[index,index2...]" .../>
Se um determinado objeto aceita vários indexadores, esses indexadores podem ser especificados em ordem, de modo semelhante a uma sintaxe de referência a vetores. O objeto em questão pode ser o contexto atual ou o valor de uma propriedade que contém um objeto com múltiplos índices.
Por padrão, os valores do indexador são tipados usando as características do objeto base. Você pode especificar o tipo do índice, se necessário. Para obter detalhes sobre tipagem de indexadores, consulte Binding.Path.
Misturando Sintaxes
Cada uma das sintaxes mostradas acima pode ser intercalada. Por exemplo, o exemplo a seguir cria uma propriedade de caminho para a cor em um determinado x, y de uma propriedade ColorGrid que contém um vetor de grades de pixels de objetos SolidColorBrush:
<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" .../>
PropertyPath de alvos de animação
A propriedade alvo de uma animação deve ser uma propriedade de dependência que aceita um Freezable ou um tipo primitivo. No entanto, a propriedade alvo em um tipo e a propriedade animada eventualmente podem existir em diferentes objetos. Para animações, um caminho de propriedade é usado para definir a conexão entre a propriedade do objeto alvo da animação nomeada e a propriedade alvo da animação pretendida, através do percorrimento das relações objeto-propriedade nos valores da propriedade.
Considerações gerais sobre objeto-propriedade para animações
Para obter mais informações sobre conceitos de animação em geral, consulte Visão geral sobre Storyboards e Revisão de Animação.
O tipo do valor ou a propriedade sendo animada deve ser um tipo Freezable ou uma primitiva. A propriedade que inicia o caminho deve ser resolvida para o nome de uma propriedade de dependência que exista no tipo TargetName especificado.
Para oferecer suporte a clonagem na animação de um Freezable que já está congelado, o objeto especificado por TargetName deve ser uma classe derivada de FrameworkElement ou FrameworkContentElement.
Propriedade única no objeto alvo
<animation Storyboard.TargetProperty="propertyName" .../>
propertyName deve ser resolvido para o nome de uma propriedade de dependência que exista no tipo TargetName especificado.
Definição indireta de propriedade alvo
<animation Storyboard.TargetProperty="propertyName.propertyName2" .../>
propertyName deve ser uma propriedade que é um tipo Freezable ou primitivo, que exista no tipo TargetName especificado.
propertyName2 deve ser o nome de uma propriedade de dependência que exista no objeto que é o valor de propertyName. Em outras palavras, propertyName2 deve existir como um propriedade de dependência no tipo que é o PropertyType da propertyName.
Definição indireta de alvos de animações é necessária devido a estilos e modelos aplicados. Para poder definir o alvo de uma animação, você precisa de um TargetName em um objeto alvo, e esse nome é estabelecido por x:Name ou Name. Embora elementos modelo e estilo também possam ter nomes, esses nomes só são válidos dentro do escopo de nomes do estilo ou modelo. (Se os modelos e estilos compartilhassem escopos de nomes com a linguagem de marcação de aplicativos, os nomes não poderiam ser exclusivos. Os estilos e modelos são literalmente compartilhados entre instâncias e iriam perpetuar nomes duplicados.) Assim, se as propriedades individuais de um elemento que você talvez queira animar vieram de um estilo ou modelo, você precisará iniciar uma instância nomeada do elemento que não seja de um modelo de estilo, em seguida, definir o alvo na árvore de visuais do estilo ou modelo para chegar à propriedade que você 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 completamente um Brush, precisaria haver uma BrushAnimation (provavelmente uma para cada tipo Brush) e não há tal tipo. Para animar um Brush, em vez disso, se deve animar as propriedades de um determinado tipo Brush. Você precisará obter do SolidColorBrush sua Color para aplicar nela uma ColorAnimation. O caminho de propriedade para esse 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 de XML para localizar o tipo. O ownerType procura tipos aos quais um processador XAML tenha acesso, por meio de declarações XmlnsDefinitionAttribute em cada conjunto de módulos (assembly). A maioria dos aplicativos possui o namespace de XML padrão mapeado para o https://schemas.microsoft.com/winfx/2006/xaml/presentation espaço para nome, para que um prefixo normalmente só é necessário para tipos personalizados ou tipos de outra forma fora desse namespace. propertyName deve resolver o nome de uma propriedade existente no ownerType. A propriedade especificada como propertyName deve ser uma DependencyProperty. (Todas as propriedades anexadas WPF são implementadas como propriedades de dependência, portanto, esse problema é uma preocupação apenas para propriedades anexadas personalizadas.)
Indexadores
<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" .../>
A maioria das propriedades de dependência ou tipos Freezable não oferecem 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 alvo nomeado e a propriedade eventualmente animada. Na sintaxe fornecida, esta é propertyName2. Por exemplo, o uso de um indexador pode ser necessário se a propriedade intermediária é uma coleção como TransformGroup, em um caminho de propriedade como RenderTransform.Children[1].Angle.
PropertyPath em código
O uso em código de um PropertyPath, incluindo como criar um PropertyPath, está documentado no tópico de referência para PropertyPath.
Em geral, PropertyPath foi desenvolvido para usar dois construtores diferentes, um para os usos de associação (binding) e animações mais simples e um outro para os usos de animação complexas. Use a assinatura PropertyPath(Object) para usos de associação, nos quais o objeto é uma sequência de caracteres. Use a assinatura PropertyPath(Object) para trajetórias de animação de uma etapa, onde o objeto é uma DependencyProperty. Use a assinatura PropertyPath(String, array<Object[]) para animações complexas. Esse último construtor usa uma sequência de tokens como primeiro parâmetro e um vetor de objetos que preenchem posições na sequência de tokens para definir uma relação propriedade de caminho.
Consulte também
Conceitos
Revisão de Associação de Dados