Extensão de marcação {Binding}

Observação

Um novo mecanismo de vinculação está disponível para o Windows 10, que é otimizado para desempenho e produtividade do desenvolvedor. Consulte a extensão de marcação {x:Bind}.

Observação

Para obter informações gerais sobre como usar a associação de dados em seu aplicativo com {Binding} (e para uma comparação completa entre {x:Bind} e {Binding}), consulte Vinculação de dados em profundidade.

A extensão de marcação {Binding} é usada para vincular propriedades de dados em controles a valores provenientes de uma fonte de dados, como código. Extensão de marcação {Binding} é convertida no tempo de carregamento XAML numa instância da classe Binding. Este objeto de ligação obtém um valor de uma propriedade de uma fonte de dados e transmite-o para a propriedade no controlo. O objeto de vinculação pode, opcionalmente, ser configurado para observar alterações no valor da propriedade da fonte de dados e atualizar-se com base nessas alterações. Ele também pode ser configurado opcionalmente para enviar as alterações no valor de controle de volta para a propriedade de origem. A propriedade que é o destino de uma associação de dados deve ser uma propriedade de dependência. Para saber mais, veja Visão geral das propriedades de dependência.

{Binding} tem a mesma precedência de propriedade de dependência que um valor local, e definir um valor local em código imperativo remove o efeito de qualquer {Binding} definido na marcação.

Uso de atributos XAML

<object property="{Binding}" .../>
-or-
<object property="{Binding propertyPath}" .../>
-or-
<object property="{Binding bindingProperties}" .../>
-or-
<object property="{Binding propertyPath, bindingProperties}" .../>

Term	Description
propertyPath	Uma cadeia de caracteres que especifica o caminho da propriedade para a vinculação. Mais informações estão na seção Caminho da propriedade abaixo.
bindingProperties	propNome=valor[, propNome=valor]* Uma ou mais propriedades de vinculação especificadas usando uma sintaxe de par nome/valor.
propNome	O nome da cadeia de caracteres da propriedade a ser definida no objeto Binding . Por exemplo, "Converter".
value	O valor a ser atribuído à propriedade. A sintaxe do argumento depende da propriedade de Properties da classe Binding que pode ser definida com a seção {Binding} abaixo.

Caminho da propriedade

Path descreve a propriedade a que está a vincular (a propriedade de origem). Path é um parâmetro posicional, o que significa que você pode usar o nome do parâmetro explicitamente ({Binding Path=EmployeeID}), ou pode especificá-lo como o primeiro parâmetro sem nome ({Binding EmployeeID}).

O tipo de Path é um caminho de propriedade, que é uma cadeia de caracteres que é avaliada como uma propriedade ou subpropriedade do seu tipo personalizado ou de um tipo de estrutura. O tipo pode ser, mas não precisa ser, um DependencyObject. Os passos em um caminho de propriedade são delimitados por pontos (.), e pode-se incluir múltiplos delimitadores para percorrer subpropriedades sucessivas. Use o delimitador de pontos independentemente da linguagem de programação usada para implementar o objeto ao qual está vinculado.

Por exemplo, para vincular a UI à propriedade FirstName de um objeto de funcionário, o caminho da propriedade pode ser "Employee.FirstName". Se você estiver vinculando um controle de itens a uma propriedade que contém dependentes de um funcionário, seu caminho de propriedade pode ser "Employee.Dependents", e o modelo de item do controle de itens se encarregará de exibir os itens em "Dependentes".

Se a fonte de dados for uma coleção, um caminho de propriedade poderá especificar itens na coleção por sua posição ou índice. Por exemplo, "Equipas[0].Players", onde o literal "[]" inclui o "0" que especifica o primeiro elemento de uma coleção.

Ao usar uma associação ElementName a um DependencyObject existente, você pode usar propriedades anexadas como parte do caminho da propriedade. Para desambiguar uma propriedade anexada para que o ponto intermediário no nome da propriedade anexada não seja considerado uma etapa em um caminho de propriedade, coloque parênteses em torno do nome da propriedade anexada qualificada pelo proprietário; por exemplo, (AutomationProperties.Name).

Um objeto intermediário de caminho de propriedade é armazenado como um objeto PropertyPath numa representação durante a execução, mas a maioria dos cenários não precisará interagir com um objeto PropertyPath no código. Normalmente, você pode especificar as informações de associação necessárias usando XAML.

Para obter mais informações sobre a sintaxe de cadeia de caracteres para um caminho de propriedade, caminhos de propriedade em áreas de recurso de animação e a construção de um objeto PropertyPath , consulte Sintaxe de caminho de propriedade.

Propriedades da classe Binding que podem ser definidas com {Binding}

{Binding} é ilustrado com a sintaxe de placeholder bindingProperties porque há várias propriedades de leitura e escrita de um Binding que podem ser definidas na extensão de marcação. As propriedades podem ser definidas em qualquer ordem com pares devalores= separados por vírgula. Algumas das propriedades exigem tipos que não têm uma conversão de tipo, portanto, elas exigem extensões de marcação próprias aninhadas dentro do {Binding}.

Propriedade	Description
Caminho	Consulte a seção Caminho da propriedade acima.
Conversor	Especifica um objeto conversor que é chamado pelo mecanismo de ligação. O conversor pode ser configurado nas marcações usando a extensão de marcação {StaticResource} para referenciar esse objeto de um dicionário de recursos.
ConversorLanguage	Especifica a cultura a ser usada pelo conversor. (Se você estiver definindo o Conversor.) A cultura é definida como um identificador baseado em padrões. Para obter mais informações, consulte ConverterLanguage
ConverterParameter	Especifica um parâmetro do conversor que pode ser usado na lógica do conversor. (Se estiver a definir o Conversor.) A maioria dos conversores utiliza lógica simples que obtém todas as informações necessárias a partir do valor passado para converter e não precisam de um valor de ConverterParameter. O parâmetro ConverterParameter é para implementações de conversor mais complexas que têm lógica condicional que desliga o que é passado em ConverterParameter. Você pode escrever um conversor que usa valores diferentes de cadeias de caracteres, mas isso é incomum, consulte Comentários em ConverterParameter para obter mais informações.
ElementName	Especifica uma fonte de dados fazendo referência a outro elemento na mesma construção XAML que tem uma propriedade Name ou um atributo x:Name. Isso geralmente é usado para compartilhar valores relacionados ou usar subpropriedades de um elemento da interface do usuário para fornecer um valor específico para outro elemento, por exemplo, em um modelo de controle XAML.
FallbackValue	Especifica um valor a ser exibido quando a origem ou o caminho não puderem ser resolvidos.
Modo	Especifica o modo de ligação, como um destes valores: "OneTime", "OneWay" ou "TwoWay". Estes correspondem aos nomes constantes da enumeração BindingMode . O padrão é "OneWay". Observe que isso difere do padrão para {x:Bind}, que é "OneTime".
FonteRelativa	Especifica uma fonte de dados descrevendo a posição da fonte de vinculação em relação à posição do destino de vinculação. Isso é usado com mais freqüência em associações dentro de modelos de controle XAML. Definindo a extensão de marcação {RelativeSource}.
Fonte	Especifica a fonte de dados do objeto. Dentro da extensão de marcação Binding, a propriedade Source requer uma referência de objeto, como uma referência de extensão de marcação {StaticResource}. Se essa propriedade não for especificada, o contexto de dados de atuação especificará a origem. É mais comum não especificar um valor Source em associações individuais e, em vez disso, confiar no DataContext compartilhado para várias associações. Para saber mais, veja DataContext ou Vinculação de dados em profundidade.
TargetNullValue	Especifica um valor a ser exibido quando o valor de origem é resolvido, mas é explicitamente nulo.
UpdateSourceTrigger	Especifica o momento das atualizações da fonte de dados da vinculação. Se não for especificado, o padrão será Padrão.

Observação

Se estiver a converter a marcação de {x:Bind} para {Binding}, esteja ciente das diferenças nos valores predefinidos para a propriedade Mode.

Converter, ConverterLanguage e ConverterLanguage estão relacionados ao cenário de conversão de um valor ou tipo da fonte de vinculação em um tipo ou valor compatível com a propriedade de destino de vinculação. Para obter mais informações e exemplos, consulte a seção "Conversões de dados" de Vinculação de dados em profundidade.

Observação

A partir do Windows 10, versão 1607, a estrutura XAML fornece um conversor Boolean to Visibility integrado. O conversor mapeia true para o valor de enumeração Visible e false para Collapsed para que você possa vincular uma propriedade Visibility a um Boolean sem criar um conversor. Para usar o conversor interno, a versão mínima do SDK de destino do seu aplicativo deve ser 14393 ou posterior. Você não pode usá-lo quando seu aplicativo tem como alvo versões anteriores do Windows 10. Para obter mais informações sobre versões de destino, consulte Código adaptável de versão.

Source, RelativeSource e ElementName especificam uma fonte de ligação, para que sejam mutuamente exclusivos.

Sugestão

Se precisar especificar uma única chave de colchete para um valor, como em Path ou ConverterParameter, preceda-a com uma barra invertida: \{. Como alternativa, coloque toda a cadeia de caracteres que contém as chaves que precisam ser escapadas em um conjunto de aspas secundário, por exemplo ConverterParameter='{Mix}'.

Examples

<!-- binding a UI element to a view model -->
<Page ... >
    <Page.DataContext>
        <local:BookstoreViewModel/>
    </Page.DataContext>

    <GridView ItemsSource="{Binding BookSkus}" SelectedItem="{Binding SelectedBookSku, Mode=TwoWay}" ... />
</Page>

<!-- binding a UI element to another UI element -->
<Page ... >
    <Page.Resources>
        <local:S2Formatter x:Key="GradeConverter"/>
    </Page.Resources>

    <Slider x:Name="sliderValueConverter" ... />
    <TextBox Text="{Binding Path=Value, ElementName=sliderValueConverter,
        Mode=OneWay,
        Converter={StaticResource GradeConverter}}"/>
</Page>

O segundo exemplo define quatro propriedades Binding diferentes: ElementName, Path, Mode e Converter. Path , neste caso, é mostrado explicitamente nomeado como uma propriedade Binding . O Path é avaliado como uma origem de dados que está ligada a outro objeto na mesma árvore de objetos em tempo de execução, um Slider chamado sliderValueConverter.

Observe como o valor da propriedade Converter usa outra extensão de marcação, a extensão de marcação {StaticResource}, resultando em dois usos de extensões de marcação aninhadas aqui. A parte interna é avaliada primeiro, de modo que, uma vez obtido o recurso, há um IValueConverter útil (uma classe personalizada que é instanciada pelo elemento local:S2Formatter nos recursos) que a associação pode utilizar.

Suporte de ferramentas

O Microsoft IntelliSense no Microsoft Visual Studio exibe as propriedades do contexto de dados durante a criação de {Binding} no editor de marcação XAML. Assim que se digitar "{Binding", as propriedades de contexto de dados apropriadas para Path serão exibidas no menu dropdown. IntelliSense também ajuda com as outras propriedades de Binding. Para que isso funcione, você deve ter o contexto de dados ou o contexto de dados em tempo de design definido na página de marcação. Go To Definition (F12) também funciona com {Binding}. Como alternativa, você pode usar a caixa de diálogo de vinculação de dados.