Visualização de calendário

Uma vista de calendário permite que um utilizador veja e interaja com um calendário que 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.

Será este o controlo correto?

Use um modo de exibição de calendário para permitir que um usuário escolha uma única data ou um intervalo de datas de um calendário sempre visível.

Se precisar permitir que um usuário selecione várias datas ao mesmo tempo, use um modo de exibição de calendário. Se precisar permitir que um utilizador escolha apenas uma única data e não precisar que um calendário esteja sempre visível, considere usar um seletor de data de calendário ou um controle de seletor de data .

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

Examples

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, começa com a vista do mês aberta. Você pode especificar uma exibição de inicialização definindo a propriedade DisplayMode .

Os utilizadores clicam no cabeçalho na vista de mês para abrir a vista de ano e clicam no cabeçalho na vista de ano para abrir a vista de década. Os utilizadores escolhem um ano na vista de década para regressar à vista de ano e escolhem um mês na vista de ano para regressar à vista de mês. As duas setas ao lado do cabeçalho navegam para frente ou para trás por mês, por ano ou por década.

Criar uma vista de calendário

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

Este exemplo mostra como criar um modo de exibição de calendário simples.

<CalendarView/>

A vista de calendário resultante tem o seguinte aspeto:

Seleção de datas

Por padrão, a propriedade SelectionMode é definida como Single. Isso permite que um usuário escolha uma única data no calendário. Defina SelectionMode como Nenhum para desativar a seleção de data.

Defina SelectionMode como Multiple para permitir que um usuário selecione várias datas. Você pode selecionar várias datas programaticamente adicionando objetos DateTime/DateTimeOffset à coleção SelectedDates , conforme mostrado aqui:

calendarView1.SelectedDates.Add(DateTimeOffset.Now);
calendarView1.SelectedDates.Add(new DateTime(1977, 1, 5));

Um usuário pode desmarcar uma data selecionada clicando ou tocando nela na grade do calendário.

Você pode manipular o evento SelectedDatesChanged a ser notificado quando a coleção SelectedDates for alterada.

Personalizando a aparência do modo de exibição de calendário

A vista de calendário é composta por elementos XAML definidos no ControlTemplate e por elementos visuais renderizados diretamente pelo controlo.

• Os elementos XAML definidos no modelo de controle incluem a borda que inclui o controle, o cabeçalho, os botões anterior e seguinte e os elementos DayOfWeek. Você pode estilizar e remodelar esses elementos como qualquer controle XAML.
• A grade de calendário é composta de objetos CalendarViewDayItem . Não é possível definir o estilo ou remodelar esses elementos, mas várias propriedades são fornecidas para permitir que você personalize sua aparência.

Este diagrama mostra os elementos que compõem a vista de mês do calendário. Para obter mais informações, consulte os Comentários na classe CalendarViewDayItem .

Esta tabela lista as propriedades que você pode alterar para modificar a aparência dos elementos do calendário.

Por padrão, a visualização de mês mostra 6 semanas de cada vez. Você pode alterar o número de semanas mostrado definindo a propriedade NumberOfWeeksInView . O número mínimo de semanas para mostrar é 2; o máximo é 8.

Por padrão, as visualizações de ano e década são exibidas numa grade 4x4. Para alterar o número de linhas ou colunas, chame SetYearDecadeDisplayDimensions com o número desejado de linhas e colunas. Isso mudará a grade para as visualizações do ano e da década.

Aqui, as exibições do ano e da década estão configuradas para serem exibidas em uma grade 3 por 4.

calendarView1.SetYearDecadeDisplayDimensions(3, 4);

Por padrão, a data mínima mostrada no modo de exibição de calendário é 100 anos antes da data atual e a data máxima mostrada é 100 anos após a data atual. Você pode alterar as datas mínima e máxima que o calendário mostra definindo as propriedades MinDate e MaxDate .

calendarView1.MinDate = new DateTime(2000, 1, 1);
calendarView1.MaxDate = new DateTime(2099, 12, 31);

Atualização de itens do dia do calendário

Cada dia no calendário é representado por um objeto CalendarViewDayItem. Para acessar um item de dia individual e usar suas propriedades e métodos, manipule o evento CalendarViewDayItemChanging e use a propriedade Item dos args de evento para acessar o CalendarViewDayItem.

Você pode tornar um dia não selecionável no modo de exibição de calendário definindo sua propriedade CalendarViewDayItem.IsBlackout como true.

Você pode mostrar informações contextuais sobre a densidade de eventos em um dia chamando o método CalendarViewDayItem.SetDensityColors . Você pode mostrar de 0 a 10 barras de densidade para cada dia e definir a cor de cada barra.

Aqui estão alguns itens do dia em um calendário. Os dias 1 e 2 estão apagados. Os dias 2, 3 e 4 têm várias barras de densidade definidas.

Renderização em fases

Um modo de exibição de calendário pode conter um grande número de objetos CalendarViewDayItem. Para manter a interface do usuário responsiva e permitir uma navegação suave pelo calendário, o modo de exibição de calendário oferece suporte à renderização em fases. Isso permite dividir o processamento de um item de dia em fases. Se um dia for movido para fora da exibição antes que todas as fases sejam concluídas, não será usado mais tempo tentando processar e renderizar esse item.

Este exemplo mostra a renderização em fases de um modo de exibição de calendário para agendamento de compromissos.

• Na fase 0, o item de dia padrão é renderizado.
• Na fase 1, você bloqueia datas que não podem ser reservadas. Isso inclui datas passadas, domingos e datas que já estão totalmente reservadas.
• Na fase 2, você verifica cada consulta marcada para o dia. Você mostra uma barra de densidade verde para cada compromisso confirmado e uma barra de densidade azul para cada compromisso provisório.

A classe Bookings neste exemplo é de um aplicativo de reserva de compromissos fictício e não é mostrada.

<CalendarView CalendarViewDayItemChanging="CalendarView_CalendarViewDayItemChanging"/>

private void CalendarView_CalendarViewDayItemChanging(CalendarView sender,
                                   CalendarViewDayItemChangingEventArgs args)
{
    // Render basic day items.
    if (args.Phase == 0)
    {
        // Register callback for next phase.
        args.RegisterUpdateCallback(CalendarView_CalendarViewDayItemChanging);
    }
    // Set blackout dates.
    else if (args.Phase == 1)
    {
        // Blackout dates in the past, Sundays, and dates that are fully booked.
        if (args.Item.Date < DateTimeOffset.Now ||
            args.Item.Date.DayOfWeek == DayOfWeek.Sunday ||
            Bookings.HasOpenings(args.Item.Date) == false)
        {
            args.Item.IsBlackout = true;
        }
        // Register callback for next phase.
        args.RegisterUpdateCallback(CalendarView_CalendarViewDayItemChanging);
    }
    // Set density bars.
    else if (args.Phase == 2)
    {
        // Avoid unnecessary processing.
        // You don't need to set bars on past dates or Sundays.
        if (args.Item.Date > DateTimeOffset.Now &&
            args.Item.Date.DayOfWeek != DayOfWeek.Sunday)
        {
            // Get bookings for the date being rendered.
            var currentBookings = Bookings.GetBookings(args.Item.Date);

            List<Color> densityColors = new List<Color>();
            // Set a density bar color for each of the days bookings.
            // It's assumed that there can't be more than 10 bookings in a day. Otherwise,
            // further processing is needed to fit within the max of 10 density bars.
            foreach (booking in currentBookings)
            {
                if (booking.IsConfirmed == true)
                {
                    densityColors.Add(Colors.Green);
                }
                else
                {
                    densityColors.Add(Colors.Blue);
                }
            }
            args.Item.SetDensityColors(densityColors);
        }
    }
}

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

Artigos relacionados

• Controlos de data e hora
• Seletor de data do calendário
• Seletor de data
• Seletor de tempo