Controles de calendário, data e hora

Os controles de data e hora oferecem maneiras padrão e localizadas de permitir que um usuário exiba e defina valores de data e hora em seu aplicativo. Este artigo fornece diretrizes de design e ajuda você a escolher o controle certo.

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub

Qual controle de data ou hora você deve usar?

Há quatro controles de data e hora para escolher; o controle que você usa depende do seu cenário. Use essas informações para escolher o controle correto a ser usado em seu aplicativo.

Controle	Example	Description
Exibição de calendário		Use para escolher uma única data ou um intervalo de datas de um calendário sempre visível.
Seletor de data do calendário		Use para escolher uma única data de um calendário contextual.
Seletor de data		Use para escolher uma única data conhecida quando as informações contextuais não forem importantes.
Seletor de hora		Use para escolher um único valor de hora.

Exibição de calendário

CalendarView permite que um usuário exiba e interaja com um calendário que ele pode navegar por mês, ano ou década. Um usuário pode selecionar uma única data ou um intervalo de datas. Ele não tem uma superfície de seletor e o calendário está sempre visível.

A exibição do calendário é composta por três modos de exibição separados: a exibição de mês, o modo de exibição de ano e a exibição de década. Por padrão, ele começa com a exibição de mês aberta, mas você pode especificar qualquer exibição como o modo de exibição de inicialização.

• Se você precisar permitir que um usuário selecione várias datas, você deve usar um CalendarView.
• Se você precisar permitir que um usuário escolha apenas uma única data e não precise que um calendário fique sempre visível, considere usar um controle CalendarDatePicker ou DatePicker .

Seletor de data do calendário

CalendarDatePicker é um controle suspenso otimizado para escolher uma única data de uma exibição de calendário em que informações contextuais como o dia da semana ou a plenitude do calendário são importantes. Você pode modificar o calendário para fornecer contexto adicional ou limitar as datas disponíveis.

O ponto de entrada exibirá o texto do espaço reservado se uma data não tiver sido definida; caso contrário, ele exibirá a data escolhida. Quando o usuário seleciona o ponto de entrada, uma exibição de calendário se expande para que o usuário faça uma seleção de data. A exibição de calendário sobrepõe outra interface do usuário; ele não empurra outra interface do usuário para fora do caminho.

• Use um seletor de data do calendário para coisas como escolher um compromisso ou uma data de partida.

Seletor de data

O controle DatePicker fornece uma maneira padronizada de escolher uma data específica.

O ponto de entrada exibe a data escolhida e, quando o usuário seleciona o ponto de entrada, uma superfície de seletor se expande verticalmente do meio para que o usuário faça uma seleção. O seletor de data sobrepõe outra interface do usuário; ele não empurra outra interface do usuário para fora do caminho.

• Use um seletor de data para permitir que um usuário escolha uma data conhecida, como uma data de nascimento, em que o contexto do calendário não é importante.

Seletor de hora

O TimePicker é usado para selecionar um único valor de hora para itens como compromissos ou hora de partida. É uma exibição estática definida pelo usuário ou no código, mas não é atualizada para exibir a hora atual.

O ponto de entrada exibe a hora escolhida e, quando o usuário seleciona o ponto de entrada, uma superfície do seletor se expande verticalmente do meio para que o usuário faça uma seleção. O seletor de tempo sobrepõe outra interface do usuário; ele não empurra outra interface do usuário para fora do caminho.

• Use um seletor de tempo para permitir que um usuário escolha um único valor de hora.

Criar um controle de data ou hora

Consulte estes artigos para obter informações e exemplos específicos para cada controle de data e hora.

• Exibição de calendário
• Seletor de data do calendário
• Seletor de data
• Seletor de Hora

Usar um seletor de data e seletor de hora juntos

Este exemplo mostra como usar um DatePicker e TimePicker juntos para permitir que um usuário selecione sua data e hora de chegada. Você manipula o e SelectedDateChanged os SelectedTimeChanged eventos para atualizar uma única instância datetime chamada arrivalDateTime. O usuário também pode limpar os seletores de data e hora depois de definidos.

<StackPanel>
    <DatePicker x:Name="arrivalDatePicker" Header="Arrival date"
                DayFormat="{}{day.integer} ({dayofweek.abbreviated})"
                SelectedDateChanged="ArrivalDatePicker_SelectedDateChanged"/>
    <StackPanel Orientation="Horizontal">
        <TimePicker x:Name="arrivalTimePicker" Header="Arrival time"
                MinuteIncrement="15"
                SelectedTimeChanged="ArrivalTimePicker_SelectedTimeChanged"/>
        <Button Content="Clear" Click="ClearDateButton_Click"
                VerticalAlignment="Bottom" Height="30" Width="54"/>
    </StackPanel>
    <TextBlock x:Name="arrivalText" Margin="0,12"/>
</StackPanel>

public sealed partial class MainPage : Page
{
    DateTime arrivalDateTime;

    public MainPage()
    {
        this.InitializeComponent();

        // Set minimum to the current year and maximum to five years from now.
        arrivalDatePicker.MinYear = DateTimeOffset.Now;
        arrivalDatePicker.MaxYear = DateTimeOffset.Now.AddYears(5);
    }

    private void ArrivalTimePicker_SelectedTimeChanged(TimePicker sender, TimePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalTimePicker.SelectedTime != null)
        {
            arrivalDateTime = new DateTime(arrivalDateTime.Year, arrivalDateTime.Month, arrivalDateTime.Day,
                                           args.NewTime.Value.Hours, args.NewTime.Value.Minutes, args.NewTime.Value.Seconds);
        }
        arrivalText.Text = arrivalDateTime.ToString();
    }

    private void ArrivalDatePicker_SelectedDateChanged(DatePicker sender, DatePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalDatePicker.SelectedDate != null)
        {
            if (VerifyDateIsFuture((DateTimeOffset)arrivalDatePicker.SelectedDate) == true)
            {
                arrivalDateTime = new DateTime(args.NewDate.Value.Year, args.NewDate.Value.Month, args.NewDate.Value.Day,
                                               arrivalDateTime.Hour, arrivalDateTime.Minute, arrivalDateTime.Second);
                arrivalText.Text = arrivalDateTime.ToString();
            }
            else
            {
                arrivalDatePicker.SelectedDate = null;
                arrivalText.Text = "Arrival date must be later than today.";
            }
        }
    }

    private bool VerifyDateIsFuture(DateTimeOffset date)
    {
        if (date > DateTimeOffset.Now)
        {
            return true;
        }
        return false;
    }

    private void ClearDateButton_Click(object sender, RoutedEventArgs e)
    {
        arrivalDateTime = new DateTime();
        arrivalDatePicker.SelectedDate = null;
        arrivalTimePicker.SelectedTime = null;
        arrivalText.Text = string.Empty;
    }
}

Globalization

Os controles de data XAML dão suporte a cada um dos sistemas de calendário compatíveis com o Windows. Esses calendários são especificados na classe Windows.Globalization.CalendarIdentifiers . Cada controle usa o calendário correto para o idioma padrão do aplicativo ou você pode definir a propriedade CalendarIdentifier para usar um sistema de calendário específico.

O controle do seletor de hora dá suporte a cada um dos sistemas de relógio especificados na classe Windows.Globalization.ClockIdentifiers . Você pode definir a propriedade ClockIdentifier para usar um relógio de 12 horas ou um relógio de 24 horas. O tipo da propriedade é String, mas você deve usar valores que correspondam às propriedades de cadeia de caracteres estáticas da classe ClockIdentifiers. Estes são: TwelveHour (a cadeia de caracteres "12HourClock")e TwentyFourHour (a cadeia de caracteres "24HourClock"). "12HourClock" é o valor padrão.

Valores datetime e calendário

Os objetos de data usados nos controles de data e hora XAML têm uma representação diferente dependendo da linguagem de programação.

• C# e Visual Basic usam a estrutura System.DateTimeOffset que faz parte do .NET.
• O C++/CX usa a estrutura Windows::Foundation::D ateTime .

Um conceito relacionado é a classe Calendar, que influencia como as datas são interpretadas no contexto. Todos os aplicativos do Windows Runtime podem usar a classe Windows.Globalization.Calendar . Os aplicativos C# e Visual Basic, como alternativa, podem usar a classe System.Globalization.Calendar , que tem funcionalidades muito semelhantes. (Os aplicativos do Windows Runtime podem usar a classe base .NET Calendar, mas não as implementações específicas; por exemplo, GregorianCalendar.)

O .NET também dá suporte a um tipo chamado DateTime, que é implicitamente conversível para um DateTimeOffset. Portanto, você pode ver um tipo "DateTime" sendo usado no código .NET usado para definir valores que são realmente DateTimeOffset. Para obter mais informações sobre a diferença entre DateTime e DateTimeOffset, consulte Comentários na classe DateTimeOffset .

Obter o código de exemplo

• Exemplo de Galeria do WinUI
• Exemplo de calendário
• Exemplo de formatação de data e hora

Tópicos relacionados

Para desenvolvedores (XAML)

• Classe CalendarView
• Classe CalendarDatePicker
• Classe DatePicker
• Classe TimePicker