RelativeSource MarkupExtension

Artigo
01/30/2025

Especifica propriedades de uma fonte de associação RelativeSource, para serem usadas em uma Extensão de marcação de associação ou ao configurar a propriedade RelativeSource de um elemento Binding estabelecido em XAML.

Uso do atributo XAML

<Binding RelativeSource="{RelativeSource modeEnumValue}" ... />

Uso de atributo XAML (aninhado em uma extensão de associação)

<object property="{Binding RelativeSource={RelativeSource modeEnumValue} ...}" ... />

Uso de Elementos de Objeto XAML

<Binding>
  <Binding.RelativeSource>
    <RelativeSource Mode="modeEnumValue"/>
  </Binding.RelativeSource>
</Binding>

-ou-

<Binding>
  <Binding.RelativeSource>
    <RelativeSource
      Mode="FindAncestor"
      AncestorType="{x:Type typeName}"
      AncestorLevel="intLevel"
    />
  </Binding.RelativeSource>
</Binding>

Valores XAML

Valor	Descrição
`modeEnumValue`	Um dos seguintes: - O token de sequência de texto `Self`; corresponde a um RelativeSource, como criado com a respectiva propriedade Mode definida como Self. - O token de cadeia de caracteres `TemplatedParent`; corresponde a um RelativeSource, criado com sua propriedade Mode definida como TemplatedParent. - O token de string `PreviousData`; corresponde a um RelativeSource, criado com sua propriedade Mode definida como PreviousData. - Consulte abaixo para obter informações sobre o modo `FindAncestor`.
`FindAncestor`	O token da cadeia de caracteres `FindAncestor`. O uso deste token ativa um modo no qual um `RelativeSource` especifica um tipo ancestral e, opcionalmente, um nível ancestral. Isso corresponde a RelativeSource, conforme criado com a propriedade Mode, definida como FindAncestor.
`typeName`	Necessário para o modo `FindAncestor`. O nome de um tipo que preenche a propriedade AncestorType.
`intLevel`	Opcional para o modo `FindAncestor`. Um nível de ancestral (avaliado de acordo com a direção do pai na árvore lógica).

Observações

Usos de associação {RelativeSource TemplatedParent} são técnicas-chave que atendem a um conceito maior de separação de uma interface do usuário do controle e uma lógica do controle. Isso habilita a associação a partir da definição de modelo a um pai modelo (instância do objeto de tempo de execução em que o modelo é aplicado). Nesse caso, a Extensão de Marcação TemplateBinding é, na verdade, uma abreviação da seguinte expressão de associação: {Binding RelativeSource={RelativeSource TemplatedParent}}. Os usos de TemplateBinding ou {RelativeSource TemplatedParent} são relevantes somente no XAML que define um modelo. Para obter mais informações, consulte Extensão de Marcação TemplateBinding.

O {RelativeSource FindAncestor} é usado principalmente em modelos de controle ou em composições de interface do usuário independentes previsíveis para casos em que um controle deve estar sempre em uma árvore visual de um determinado tipo de ancestral. Por exemplo, os itens de um controle de itens podem utilizar os usos FindAncestor para se associar às propriedades do ancestral pai do controle de itens. Ou, os elementos que fazem parte da composição de controle em um modelo podem usar associações FindAncestor para elementos pai na mesma estrutura da composição.

Na sintaxe do elemento de objeto para o modo FindAncestor mostrado nas seções de sintaxe XAML, a sintaxe do segundo elemento de objeto é usada especificamente para o modo FindAncestor. O modo FindAncestor requer um valor AncestorType. Você precisa definir AncestorType como um atributo usando uma referência Extensão de Marcação x:Type ao tipo de ancestral a ser buscado. O valor AncestorType é usado quando a solicitação de associação é processada em tempo de execução.

Para o modo FindAncestor, a propriedade opcional AncestorLevel pode ajudar a desambiguar a pesquisa ancestral nos casos em que possivelmente há mais de um ancestral desse tipo existente na estrutura de elementos.

Para obter mais informações sobre como usar o modo FindAncestor, consulte RelativeSource.

{RelativeSource Self} é útil para cenários em que uma propriedade de uma instância deve depender do valor de outra propriedade da mesma instância, e nenhuma relação de propriedade de dependência geral (como coerção) já existe entre essas duas propriedades. Embora seja raro que existam duas propriedades em um objeto tal que os valores sejam literalmente idênticos e possuam o mesmo tipo, você também pode aplicar um parâmetro Converter a um vínculo que tenha {RelativeSource Self}e usar o conversor para converter entre tipos de origem e de destino. Outro cenário para {RelativeSource Self} é como parte de um MultiDataTrigger.

Por exemplo, o XAML a seguir define um elemento Rectangle de modo que não importa qual valor seja inserido para Width, o Rectangle é sempre um quadrado: <Rectangle Width="200" Height="{Binding RelativeSource={RelativeSource Self}, Path=Width}" .../>

{RelativeSource PreviousData} é útil em modelos de dados ou em casos em que as associações estão usando uma coleção como fonte de dados. Você pode usar {RelativeSource PreviousData} para realçar relações entre itens de dados adjacentes na coleção. Uma técnica relacionada é estabelecer uma MultiBinding entre os itens atuais e anteriores na fonte de dados e usar um conversor nessa associação para determinar a diferença entre os dois itens e suas propriedades.

No exemplo a seguir, o primeiro TextBlock no modelo de itens exibe o número atual. A segunda ligação de TextBlock é uma MultiBinding que nominalmente possui dois constituintes Binding: o registro atual e uma ligação que utiliza deliberadamente o registro de dados anterior utilizando {RelativeSource PreviousData}. Em seguida, um conversor em MultiBinding calcula a diferença e retorna-a à associação.

<ListBox Name="fibolist">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
            <TextBlock Text="{Binding}"/>
            <TextBlock>, difference = </TextBlock>
                <TextBlock>
                    <TextBlock.Text>
                        <MultiBinding Converter="{StaticResource DiffConverter}">
                            <Binding/>
                            <Binding RelativeSource="{RelativeSource PreviousData}"/>
                        </MultiBinding>
                    </TextBlock.Text>
                </TextBlock>
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

Descrever a vinculação de dados como conceito não é abordado aqui, consulte Data Binding Overview.

Na implementação do processador XAML do WPF, a manipulação dessa extensão de marcação é definida pela classe RelativeSource.

RelativeSource é uma extensão da marcação. As extensões de marcação normalmente são implementadas quando há um requisito para escapar de valores de atributo que não sejam valores literais ou nomes de manipulador, e o requisito é mais global do que apenas colocar conversores de tipo em determinados tipos ou propriedades. Todas as extensões de marcação no XAML usam os caracteres { e } em sua sintaxe de atributo, que é a convenção pela qual um processador XAML reconhece que uma extensão de marcação deve processar o atributo. Para obter mais informações, consulte Extensões de marcação e XAML do WPF.

Compartilhar via