Controles de calendário, data e hora

  • Artigo

Os controles de data e hora oferecem formas padrão e localizadas para 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 correto.

Abra o aplicativo Galeria do WinUI 3 e consulte DateAndTime em ação.

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 o código-fonte no GitHub

Qual controle de data ou hora você deve usar?

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

Control Exemplo Descrição
Exibição de calendário Exemplo de exibição de calendário Use-a para selecionar uma única data ou um intervalo de datas de um calendário sempre visível.
Seletor de data do calendário Captura de tela de um seletor de data do calendário. Use-o para selecionar uma única data de um calendário contextual.
Seletor de data Exemplo de seletor de data Use-o para selecionar uma única data conhecida quando informações contextuais não forem importantes.
Seletor de tempo Exemplo de seletor de hora Use-o para selecionar um valor de hora único.

Exibição de calendário

CalendarView permite que um usuário visualize e interaja com um calendário em 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 de calendário é composta de três visões separadas: a visão de mês, a visão de ano e a visão de década. Por padrão, ele é iniciado com a visão de mês aberta, mas você pode especificar qualquer visão como a visão de inicialização.

Captura de tela de três exibições de calendário mostrando uma Exibição de Mês, uma Exibição de Ano e uma Exibição de Década.

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

Seletor de data do calendário

CalendarDatePicker é um controle suspenso otimizado para selecionar uma única data em uma exibição de calendário, em que informações contextuais como o dia da semana ou o preenchimento 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 de 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 se sobrepõe à outra interface do usuário; ela não remove a outra interface do usuário.

Captura de tela de um seletor de data do calendário mostrando uma caixa de texto Selecionar uma data vazia e, em seguida, uma preenchida com um calendário embaixo dela.

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

Seletor de data

O controle DatePicker oferece uma maneira padronizada para escolher uma data específica.

O ponto de entrada mostra 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 se sobrepõe à outra interface do usuário; ele não remove a outra interface do usuário.

Exemplo da expansão do seletor de data

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

Seletor de tempo

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

O ponto de entrada mostra a hora 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 hora se sobrepõe a outra interface do usuário; ele não remove a outra interface do usuário.

Exemplo da expansão do seletor de hora

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

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.

Usar um seletor de data e de hora em conjunto

Este exemplo mostra como usar um DatePicker e um TimePicker em conjunto para permitir que um usuário selecione a data e hora de chegada. Você trata dos eventos SelectedDateChanged e SelectedTimeChanged para atualizar uma instância DateTime denominada arrivalDateTime. O usuário também pode limpar os seletores de data e hora depois que eles tiverem sido definidos.

Seletor de data, seletor de hora, botão e rótulo de texto. 

<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;
    }
}

Globalização

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

O controle seletor de hora dá suporte a todos os 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 de 24 horas. O tipo da propriedade é String, mas você deve usar valores que correspondam às propriedades de cadeia de caracteres estática da classe ClockIdentifiers. Eles são: TwelveHour (a cadeia de caracteres "12HourClock") e TwentyFourHour (a cadeia de caracteres "24HourClock"). O valor padrão é "12HourClock".

Valores DateTime e Calendar

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

Um conceito relacionado é a classe Calendar, que influencia como as datas são interpretadas em contexto. Todos os aplicativos do Windows Runtime podem usar a classe Windows.Globalization.Calendar. Aplicativos C# e Visual Basic também podem usar a classe System.Globalization.Calendar, que tem funcionalidade muito semelhante. (Os aplicativos Windows Runtime podem usar a classe base do calendário do .NET, 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 de "DateTime"usado em código .NET que é usado para definir valores que são realmente DateTimeOffset. Para obter mais informações sobre a diferença entre DateTime e DateTimeOffset, confira Comentários na classe DateTimeOffset.

Observação

As propriedades que usam objetos de data não podem ser definidas como uma cadeia de caracteres de atributo XAML, pois o analisador de XAML do Windows Runtime não tem uma lógica de conversão para converter cadeias de caracteres em datas como objetos DateTime/DateTimeOffset. Você normalmente define esses valores no código. Outra técnica possível é definir uma data disponível como um objeto de dados ou no contexto de dados e, em seguida, definir a propriedade como um atributo XAML que faz referência a uma expressão de extensão de marcação {Binding} que pode acessar a data como dados.

Obter o código de exemplo

Para desenvolvedores (XAML)