IValueConverter.Convert(Object, TypeName, Object, String) Método

Definição

Namespace:

Windows.UI.Xaml.Data

Modifica os dados de origem antes de passá-los para o destino para exibição na interface do usuário.

public:
 Platform::Object ^ Convert(Platform::Object ^ value, TypeName targetType, Platform::Object ^ parameter, Platform::String ^ language);

IInspectable Convert(IInspectable const& value, TypeName const& targetType, IInspectable const& parameter, winrt::hstring const& language);

public object Convert(object value, System.Type targetType, object parameter, string language);

function convert(value, targetType, parameter, language)

Public Function Convert (value As Object, targetType As Type, parameter As Object, language As String) As Object

Parâmetros

value

Object

Platform::Object

IInspectable

Os dados de origem que estão sendo passados para o destino.

targetType

TypeName Type

O tipo da propriedade de destino, como uma referência de tipo (System.Type para Microsoft .NET, um struct auxiliar TypeName para C++/CX e C++/WinRT).

parameter

Object

Platform::Object

IInspectable

Um parâmetro opcional a ser usado na lógica do conversor.

language

String

Platform::String

winrt::hstring

O idioma da conversão.

Retornos

Object

Platform::Object

IInspectable

O valor a ser passado para a propriedade de dependência de destino.

Exemplos

O exemplo a seguir mostra como implementar o método Convert usando os parâmetros parameter e language .

//
// MainPage.xaml.h
// Declaration of the MainPage class.
// 

#pragma once

#include "MainPage.g.h"

namespace IValueConverterExample
{

    // Simple business object.
    [Windows::UI::Xaml::Data::Bindable]
    public ref class Recording sealed 
    {
    public: 
        Recording (Platform::String^ artistName, Platform::String^ cdName, Windows::Foundation::DateTime release)
        {
            Artist = artistName;
            Name = cdName;
            ReleaseDate = release;
        }
        property Platform::String^ Artist;
        property Platform::String^ Name;
        property Windows::Foundation::DateTime ReleaseDate;
    };

    public ref class DateFormatter  sealed : Windows::UI::Xaml::Data::IValueConverter 
    {
        // This converts the DateTime object to the Platform::String^ to display.
    public:
        virtual Platform::Object^ Convert(Platform::Object^ value, Windows::UI::Xaml::Interop::TypeName targetType, 
            Platform::Object^ parameter, Platform::String^ language)
        {
            Windows::Foundation::DateTime dt = safe_cast<Windows::Foundation::DateTime>(value); 
            Windows::Globalization::DateTimeFormatting::DateTimeFormatter^ dtf =
                Windows::Globalization::DateTimeFormatting::DateTimeFormatter::ShortDate;
            return dtf->Format(dt); 
        }

        // No need to implement converting back on a one-way binding 
        virtual Platform::Object^ ConvertBack(Platform::Object^ value, Windows::UI::Xaml::Interop::TypeName targetType, 
            Platform::Object^ parameter, Platform::String^ language)
        {
            throw ref new Platform::NotImplementedException();
        }
    };

    /// <summary>
    /// An empty page that can be used on its own or navigated to within a Frame.
    /// </summary>
    public ref class MainPage sealed
    {
    public:
        MainPage()
        {	
            m_myMusic = ref new Platform::Collections::Vector<Recording^>();

            // Add items to the collection.

            // You can use a Calendar object to create a Windows::Foundation::DateTime
            auto c = ref new Windows::Globalization::Calendar();
            c->Year = 2008;
            c->Month = 2;
            c->Day = 5;
            m_myMusic->Append(ref new Recording("Chris Sells", "Chris Sells Live",
                c->GetDateTime()));

            c->Year = 2007;
            c->Month = 4;
            c->Day = 3;
            m_myMusic->Append(ref new Recording("Luka Abrus",
                "The Road to Redmond", c->GetDateTime()));
            
            c->Year = 2007;
            c->Month = 2;
            c->Day = 3;
            m_myMusic->Append(ref new Recording("Jim Hance",
                "The Best of Jim Hance", dt));
            InitializeComponent();

            // Set the data context for the combo box.
            MusicCombo->DataContext = m_myMusic;	
        }


    protected:
        virtual void OnNavigatedTo(Windows::UI::Xaml::Navigation::NavigationEventArgs^ e) override;

    private:
        Windows::Foundation::Collections::IVector<Recording^>^ m_myMusic;
    };
}

using System;
using System.Collections.ObjectModel;
using System.Globalization;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Data;

namespace ConverterParameterEx
{
    public partial class Page : UserControl
    {

        public ObservableCollection<Recording> MyMusic =
            new ObservableCollection<Recording>();
        public Page()
        {
            InitializeComponent();

            // Add items to the collection.
            MyMusic.Add(new Recording("Chris Sells", "Chris Sells Live",
                new DateTime(2008, 2, 5)));
            MyMusic.Add(new Recording("Luka Abrus",
                "The Road to Redmond", new DateTime(2007, 4, 3)));
            MyMusic.Add(new Recording("Jim Hance",
                "The Best of Jim Hance", new DateTime(2007, 2, 6)));

            // Set the data context for the combo box.
            MusicCombo.DataContext = MyMusic;
        }
    }

    // Simple business object.
    public class Recording
    {
        public Recording() { }
        public Recording(string artistName, string cdName, DateTime release)
        {
            Artist = artistName;
            Name = cdName;
            ReleaseDate = release;
        }
        public string Artist { get; set; }
        public string Name { get; set; }
        public DateTime ReleaseDate { get; set; }
    }

    public class DateFormatter : IValueConverter
    {
        // This converts the DateTime object to the string to display.
        public object Convert(object value, Type targetType, 
            object parameter, string language)
        {
            // Retrieve the format string and use it to format the value.
            string formatString = parameter as string;
            if (!string.IsNullOrEmpty(formatString))
            {
                return string.Format(
                    new CultureInfo(language), formatString, value);
            }
            // If the format string is null or empty, simply call ToString()
            // on the value.
            return value.ToString();
        }

        // No need to implement converting back on a one-way binding 
        public object ConvertBack(object value, Type targetType, 
            object parameter, string language)
        {
            throw new NotImplementedException();
        }
    }
}

Imports System.Collections.ObjectModel
Imports System.Windows.Data
Imports System.Globalization

Partial Public Class Page
    Inherits UserControl

    Public MyMusic As New ObservableCollection(Of Recording)()
    Public Sub New()
        InitializeComponent()

        ' Add items to the collection.
        MyMusic.Add(New Recording("Sheryl Crow", "Detours", New DateTime(2008, 2, 5)))
        MyMusic.Add(New Recording("Brandi Carlisle", "The Story", New DateTime(2007, 4, 3)))
        MyMusic.Add(New Recording("Patty Griffin", "Children Running Through", New DateTime(2007, 2, 6)))

        ' Set the data context for the combo box.
        MusicCombo.DataContext = MyMusic
    End Sub
End Class

' Simple business object. 
Public Class Recording
    Public Sub New()
    End Sub
    Public Sub New(ByVal artistName As String, ByVal cdName As String, _
       ByVal release As DateTime)
        Artist = artistName
        Name = cdName
        ReleaseDate = release
    End Sub
    Private artistValue As String
    Private nameValue As String
    Private releaseDateValue As DateTime
    Public Property Artist() As String
        Get
            Return artistValue
        End Get
        Set(ByVal value As String)
            artistValue = value
        End Set
    End Property
    Public Property Name() As String
        Get
            Return nameValue
        End Get
        Set(ByVal value As String)
            nameValue = value
        End Set
    End Property
    Public Property ReleaseDate() As DateTime
        Get
            Return releaseDateValue
        End Get
        Set(ByVal value As DateTime)
            releaseDateValue = value
        End Set
    End Property
End Class

Public Class DateFormatter
    Implements IValueConverter

    ' This converts the DateTime object to the string to display. 
    Public Function Convert(ByVal value As Object, ByVal targetType As Type, _
        ByVal parameter As Object, ByVal language As System.String) As Object _
        Implements IValueConverter.Convert

        ' Retrieve the format string and use it to format the value. 
        Dim formatString As String = TryCast(parameter, String)
        If Not String.IsNullOrEmpty(formatString) Then

            Return String.Format(New CultureInfo(language), formatString, value)
        End If

        ' If the format string is null or empty, simply call ToString() 
        ' on the value. 
        Return value.ToString()
    End Function

    ' No need to implement converting back on a one-way binding.
    Public Function ConvertBack(ByVal value As Object, ByVal targetType As Type, _
        ByVal parameter As Object, _
        ByVal language As System.String) As Object _
        Implements IValueConverter.ConvertBack
        Throw New NotImplementedException()
    End Function
End Class

Comentários

O parâmetro targetType do método Convert usa técnicas diferentes para relatar as informações do sistema de tipo, dependendo se você está programando com o Microsoft .NET ou C++.

• Para o Microsoft .NET, esse parâmetro passa uma instância do tipo System.Type .
• Para C++/CX e C++/WinRT, esse parâmetro passa um valor de estrutura TypeName . TypeName::Kind contém o nome de cadeia de caracteres simples do tipo, semelhante ao microsoft . Type.NameDO NET. Quando o conversor é invocado pelo mecanismo de associação, o valor targetType é passado pesquisando o tipo de propriedade da propriedade de dependência de destino. Você pode usar esse valor em sua implementação Converter por um dos dois motivos:
• Seu conversor tem a expectativa de que ele sempre retornará objetos de um tipo específico e você deseja verificar se a associação para a qual o conversor é chamado está usando o conversor corretamente. Caso contrário, você pode retornar um valor de fallback ou lançar uma exceção (mas confira "Exceções de conversores" abaixo).
• O conversor pode retornar mais de um tipo e você deseja que o uso informe ao conversor qual tipo ele deve retornar. Por exemplo, você pode implementar uma conversão objeto para objeto e uma conversão objeto para cadeia de caracteres dentro do mesmo código conversor.

A linguagem vem do valor ConverterLanguage de uma associação específica, não de valores do sistema, portanto, você deve esperar que ela possa ser uma cadeia de caracteres vazia.

O parâmetro vem do valor ConverterParameter de uma associação específica e é nulo por padrão. Se o conversor usar parâmetros para modificar o que ele retorna, isso geralmente exigirá alguma convenção para validar o que é passado pela associação e manipulado pelo conversor. Uma convenção comum é passar cadeias de caracteres que nomeiem modos para o conversor que resultam em valores retornados diferentes. Por exemplo, você pode ter modos "Simples" e "Detalhados" que retornam cadeias de caracteres de comprimento diferentes que são apropriadas para exibição em diferentes tipos de controle de interface do usuário e layouts.

Exceções de conversores

O mecanismo de associação de dados não captura exceções geradas por um conversor fornecido pelo usuário. Qualquer exceção gerada pelo método Convert ou quaisquer exceções não capturadas geradas por métodos que o método Convert chama são tratadas como erros de tempo de execução. Se você estiver usando o conversor em situações em que a associação pode usar fallbacks ou mostrar resultados razoáveis mesmo se ocorrer uma falha de conversão, considere fazer com que o conversor retorne DependencyProperty.UnsetValue e não gere exceções. DependencyProperty.UnsetValue é um valor sentinela que tem um significado especial no sistema de propriedades de dependência e as associações passadas a esse valor usarão FallbackValue.

Outra alternativa para gerar exceções é retornar o valor original inalterado e permitir que a instância de associação manipule o que ela pode fazer com esse valor. Na maioria dos casos, as associações de interface do usuário que falharem não serão casos de erro. Eles simplesmente não usarão o valor de origem e usarão DependencyProperty.UnsetValue para não mostrar nada ou usar fallbacks.

try/catch com base em fazer algo de valor é um padrão de implementação comum para o método Convert, mas você não deve relançar, pelos motivos mencionados acima.

Para obter um exemplo que mostra como implementar o método Convert usando o parâmetro e os parâmetros de linguagem , consulte a interface IValueConverter .

Confira também

• ConvertBack(Object, TypeName, Object, String)
• Exemplo de associação de dados XAML
• Vinculação de dados em detalhes