Partilhar via

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 visualize e defina valores de data e hora em seu aplicativo. Este artigo fornece diretrizes de design e ajuda você a escolher o controle certo.

Abra o aplicativo WinUI 3 Gallery e veja os controles de data e hora em ação

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

Que controlo de data ou hora deve utilizar?

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 certo para usar em seu aplicativo.

Controlo Example Description
Visualização de calendário Exemplo de vista 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 Captura de ecrã de um seletor de datas do calendário. Use para escolher uma única data de um calendário contextual.
Seletor de data Exemplo de seletor de data Use para escolher uma única data conhecida quando as informações contextuais não forem importantes.
Seletor de hora Exemplo de seletor de tempo Use para escolher um único valor de tempo.

Visualização de calendário

CalendarView permite que um usuário visualize 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. Não tem uma interface de seleção e o calendário está sempre visível.

A vista de calendário é composta por 3 vistas separadas: a vista de mês, a vista de ano e a vista de década. Por padrão, ele começa com o modo de exibição de mês aberto, mas você pode especificar qualquer modo de exibição como o modo de exibição de inicialização.

Captura de ecrã de três vistas de Calendário a mostrar uma vista de Mês, uma vista de Ano e uma vista de Década.

  • Se você precisar permitir que um usuário selecione várias datas, deverá usar um CalendarView.
  • Se você precisar permitir que um usuário escolha apenas uma única data e não precisar que um calendário esteja 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 onde 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 exibe texto de exemplo se uma data não tiver sido definida; caso contrário, exibe a data escolhida. Quando o usuário seleciona o ponto de entrada, uma exibição de calendário é expandida para que o usuário faça uma seleção de data. O modo de 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.

Captura de ecrã de um Seletor de Data do Calendário a mostrar uma caixa de texto vazia, selecionar uma data e, em seguida, uma caixa de texto preenchida com um calendário por baixo.

  • Use um seletor de data do calendário para coisas como escolher um compromisso ou 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 do seletor se expande verticalmente do meio para o usuário fazer 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.

Exemplo do seletor de data expandindo

  • 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 tempo para coisas como compromissos ou um horário de partida. É uma exibição estática definida pelo usuário ou em 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 o usuário fazer 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.

Exemplo de expansão do seletor de tempo

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

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.

Use um seletor de data e um 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 os SelectedDateChanged eventos e SelectedTimeChanged para atualizar uma única instância de DateTime chamada arrivalDateTime. O usuário também pode limpar os seletores de data e hora depois que eles foram definidos.

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

Globalization

Os controles de data XAML oferecem suporte a cada um dos sistemas de calendário suportados pelo 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 seu aplicativo ou você pode definir a propriedade CalendarIdentifier para usar um sistema de calendário específico.

O controle de seletor de tempo suporta 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 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. São eles: TwelveHour (a string "12HourClock") e TwentyFourHour (a string "24HourClock"). "12HourClock" é o valor padrão.

Valores de DateTime e Calendário

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

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

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

Observação

As propriedades que usam objetos date não podem ser definidas como uma cadeia de caracteres de atributo XAML, porque o analisador XAML do Tempo de Execução do Windows não tem uma lógica de conversão para converter cadeias de caracteres em datas como objetos DateTime/DateTimeOffset. Normalmente, você define esses valores no código. Outra técnica possível é definir uma data que está 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)

  • Last updated on