Seletor de data

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

Será este o controlo correto?

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.

Se o contexto de um calendário for importante, considere usar um seletor de data ou uma vista de calendário .

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

Examples

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

Criar um seletor de data

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 data simples com um cabeçalho.

<DatePicker x:Name="exampleDatePicker" Header="Pick a date"/>

DatePicker exampleDatePicker = new DatePicker();
exampleDatePicker.Header = "Pick a date";

O seletor de data resultante tem esta aparência:

Formatar o seletor de data

Por padrão, o seletor de data mostra o dia, o mês e o ano. Se o seu cenário para o seletor de data não exigir todos os campos, você poderá ocultar os que não precisa. Para ocultar um campo, defina o campo correspondentepropriedade Visible como false: DayVisible, MonthVisibleou YearVisible.

Aqui, apenas o ano é necessário, por isso os campos de dia e mês são ocultos.

<DatePicker x:Name="yearDatePicker" Header="In what year was Microsoft founded?" 
            MonthVisible="False" DayVisible="False"/>

O conteúdo da cadeia de caracteres de cada ComboBox no DatePicker é criado por um DateTimeFormatter. Você informa ao DateTimeFormatter como formatar o valor de data fornecendo uma cadeia de caracteres que seja um modelo de formato ou um padrão de formato . Para obter mais informações, consulte as propriedades DayFormat, MonthFormate YearFormat.

Aqui, um padrão de formato é usado para mostrar o mês como um inteiro e uma abreviação. Você pode adicionar cadeias de caracteres literais ao padrão de formato, como os parênteses em torno da abreviatura do mês: ({month.abbreviated}).

<DatePicker MonthFormat="{}{month.integer(2)} ({month.abbreviated})" DayVisible="False"/>

Valores de data

O controle seletor de data tem Date/DateChanged e SelectedDate/SelectedDateChanged APIs. A diferença entre eles é que Date não é anulável, enquanto SelectedDate é anulável.

O valor de SelectedDate é usado para preencher o seletor de data e é null por padrão. Se SelectedDate for igual a null, a propriedade Date será definida para 31/12/1600; caso contrário, o valor Date será sincronizado com o valor SelectedDate. Quando SelectedDate é null, o seletor é 'desdefinido' e mostra os nomes dos campos em vez de uma data.

Você pode definir as propriedades MinYear e MaxYear para restringir os valores de data no seletor. Por padrão, MinYear é definido como 100 anos antes da data atual e MaxYear é definido como 100 anos após a data atual.

Se você definir apenas MinYear ou MaxYear, precisará garantir que um intervalo de datas válido seja criado pela data definida e pelo valor padrão da outra data; caso contrário, nenhuma data estará disponível para selecionar no seletor. Por exemplo, definir apenas yearDatePicker.MaxYear = new DateTimeOffset(new DateTime(900, 1, 1)); cria um intervalo de datas inválido com o valor padrão de MinYear.

Inicializando um valor de data

As propriedades date não podem ser definidas como uma cadeia de atributos XAML, porque o parser XAML Windows Runtime não tem uma lógica de conversão para converter cadeias em datas como objetos DateTime / DateTimeOffset. Aqui estão algumas maneiras sugeridas de que esses objetos podem ser definidos em código e definidos para uma data diferente da data atual.

• DateTime: Instanciar Windows.Globalization.Calendar (inicializado para a data atual). Defina o Anoou chame AdicionarAnospara ajustar a data. Em seguida, chame Calendar.GetDateTime e use o DateTime retornado para definir a propriedade date.
• DateTimeOffset: Chame o construtor. Para o System.DateTime interno , use a assinatura do método construtor. Ou então, construa um padrão DateTimeOffset (ele é inicializado com a data atual) e chame AddYears.

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 da data como um atributo XAML que referencia uma extensão de marcação {Binding} , que pode aceder a data como dados.

Este exemplo demonstra a definição das propriedades SelectedDate, MinYeare MaxYear em diferentes controles DatePicker.

<DatePicker x:Name="yearDatePicker" MonthVisible="False" DayVisible="False"/>
<DatePicker x:Name="arrivalDatePicker" Header="Arrival date"/>

public MainPage()
{
    this.InitializeComponent();

    // Set minimum year to 1900 and maximum year to 1999.
    yearDatePicker.SelectedDate = new DateTimeOffset(new DateTime(1950, 1, 1));
    yearDatePicker.MinYear = new DateTimeOffset(new DateTime(1900, 1, 1));
    // Using a different DateTimeOffset constructor.
    yearDatePicker.MaxYear = new DateTimeOffset(1999, 12, 31, 0, 0, 0, new TimeSpan());

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

Usando os valores de data

Para usar o valor de data na sua aplicação, normalmente utiliza uma associação de dados para a propriedade SelectedDate ou manipula o evento SelectedDateChanged.

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, você usa um DatePicker para permitir que um usuário selecione sua data de chegada. Você manipula o evento SelectedDateChanged para atualizar uma instância de DateTime chamada arrivalDateTime.

<StackPanel>
    <DatePicker x:Name="arrivalDatePicker" Header="Arrival date"
                DayFormat="{}{day.integer} ({dayofweek.abbreviated})"
                SelectedDateChanged="arrivalDatePicker_SelectedDateChanged"/>
    <Button Content="Clear" Click="ClearDateButton_Click"/>
    <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 arrivalDatePicker_SelectedDateChanged(DatePicker sender, DatePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalDatePicker.SelectedDate != null)
        {
            arrivalDateTime = new DateTime(args.NewDate.Value.Year, args.NewDate.Value.Month, args.NewDate.Value.Day);
        }
        arrivalText.Text = arrivalDateTime.ToString();
    }

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

Artigos relacionados

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