Seletor de hora

O seletor de tempo oferece uma maneira padronizada de permitir que os usuários escolham um valor de tempo usando a entrada por toque, mouse ou teclado.

Será este o controlo correto?

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

Para obter mais informações sobre como escolher o controle correto, consulte o artigo Controles de data e hora.

Examples

O ponto de entrada mostra a hora escolhida e, quando o utilizador seleciona o ponto de entrada, uma superfície de seleção expande-se verticalmente a partir do centro para que o utilizador possa 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.

Criar um seletor de tempo

A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no GitHub.

Este exemplo mostra como criar um seletor de tempo simples com um cabeçalho.

<TimePicker x:Name="arrivalTimePicker" Header="Arrival time"/>

TimePicker arrivalTimePicker = new TimePicker();
arrivalTimePicker.Header = "Arrival time";

O seletor de tempo resultante tem esta aparência:

Formatando o seletor de tempo

Por padrão, o seletor de hora mostra um relógio de 12 horas com um seletor AM/PM. Você pode definir a propriedade ClockIdentifier como "24HourClock" para mostrar um relógio de 24 horas.

<TimePicker Header="24HourClock" SelectedTime="18:21" ClockIdentifier="24HourClock"/>

Você pode definir a propriedade MinuteIncrement para indicar os incrementos de tempo mostrados no seletor de minutos. Por exemplo, 15 especifica que o controle de TimePicker minutos exibe apenas as opções 00, 15, 30, 45.

<TimePicker MinuteIncrement="15"/>

Valores de tempo

O controlo do seletor de tempo possui as APIs Time/TimeChanged e SelectedTime/SelectedTimeChanged. A diferença entre eles é que Time não é anulável, enquanto SelectedTime é anulável.

O valor de SelectedTime é usado para preencher o seletor de tempo e é null por padrão. Se SelectedTime é null, a propriedade Time é definida como um TimeSpan de 0; caso contrário, o valor Time é sincronizado com o valor SelectedTime. Quando SelectedTime é null, o seletor é 'não definido' e mostra os nomes dos campos em vez de um horário.

Inicializar um valor de tempo

No código, você pode inicializar as propriedades de tempo para um valor do tipo TimeSpan:

TimePicker timePicker = new TimePicker
{
    SelectedTime = new TimeSpan(14, 15, 00) // Seconds are ignored.
};

Você pode definir o valor de tempo como um atributo em XAML. Isso provavelmente será mais fácil se você já estiver declarando o objeto TimePicker em XAML e não estiver usando associações para o valor de tempo. Use uma string na forma Hh:Mm onde Hh é horas e pode ser entre 0 e 23 e Mm é minutos e pode ser entre 0 e 59.

<TimePicker SelectedTime="14:15"/>

Usando os valores de tempo

Para usar o valor de tempo em seu aplicativo, normalmente você usa uma associação de dados para a propriedade SelectedTime ou Time , usa as propriedades de tempo diretamente em seu código ou manipula o evento SelectedTimeChanged ou TimeChanged .

Para ver um exemplo de utilização de um DatePicker e um TimePicker juntos para atualizar um único valor DateTime, consulte Controles de calendário, data e hora - Usar um seletor de data e um seletor de hora juntos.

Aqui, a propriedade SelectedTime é usada para comparar a hora selecionada com a hora atual.

Observe que, como a propriedade SelectedTime é anulável, você precisa enviá-la explicitamente para DateTime, assim: DateTime myTime = (DateTime)(DateTime.Today + checkTimePicker.SelectedTime);. A propriedade Time, no entanto, poderia ser usada sem um elenco, assim: DateTime myTime = DateTime.Today + checkTimePicker.Time;.

<StackPanel>
    <TimePicker x:Name="checkTimePicker"/>
    <Button Content="Check time" Click="{x:Bind CheckTime}"/>
    <TextBlock x:Name="resultText"/>
</StackPanel>

private void CheckTime()
{
    // Using the Time property.
    // DateTime myTime = DateTime.Today + checkTimePicker.Time;
    // Using the SelectedTime property (nullable requires cast to DateTime).
    DateTime myTime = (DateTime)(DateTime.Today + checkTimePicker.SelectedTime);
    if (DateTime.Now >= myTime)
    {
        resultText.Text = "Your selected time has already past.";
    }
    else
    {
        string hrs = (myTime - DateTime.Now).Hours.ToString();
        string mins = (myTime - DateTime.Now).Minutes.ToString();
        resultText.Text = string.Format("Your selected time is {0} hours, {1} minutes from now.", hrs, mins);
    }
}

Tópicos relacionados

• Controlos de data e hora
• Seletor de data do calendário
• Visualização de calendário
• Seletor de data