Visão geral Angular Time Picker

    O componente seletor de tempo permite que os usuários insiram ou selecionem partes de tempo de um objeto `Data` de um menu suspenso ou diálogo com spinners, que é então espelhado no campo de entrada. No modo suspenso, que é o padrão, o campo de entrada é editável e os usuários também podem editar o tempo selecionado.

    O componente seletor de tempo tem diferentes modelos integrados para exibir um botão de relógio, bem como recursos como validação, formatação de tempo personalizada e muito mais.

    Angular Time Picker Example

    Em geral, os usuários podem inserir um horário preferencial por meio de entrada de texto ou escolhendo um valor de horário em um menu suspenso do Angular Time Picker. O exemplo básico Angular Time Picker abaixo mostra como os usuários podem inserir facilmente o valor com a ajuda do menu suspenso ou usando o teclado.

    Getting Started with Ignite UI for Angular Time Picker

    Para começar a usar o componente Ignite UI for Angular Time Picker, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

    ng add igniteui-angular

    Para obter uma introdução completa ao Ignite UI for Angular, leia o tópico de introdução.

    O próximo passo é importar o IgxTimePickerModule no seu arquivo app.module.ts.

    Note

    O IgxTimePicker também depende tanto do BrowserAnimationsModule quanto, opcionalmente, do HammerModule para interações de toque. Eles precisam ser adicionados ao AppModule também.

    // app.module.ts

...
import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IgxTimePickerModule } from 'igniteui-angular';
// import { IgxTimePickerModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., BrowserAnimationsModule, HammerModule, IgxTimePickerModule],
    ...
})
export class AppModule {}

    Como alternativa, a partir da 16.0.0 você pode importar o IgxTimePickerComponent como uma dependência autônoma ou usar o token IGX_TIME_PICKER_DIRECTIVES para importar o componente e todos os seus componentes e diretivas de suporte.

    // home.component.ts

import { FormsModule } from '@angular/forms';
import { IGX_TIME_PICKER_DIRECTIVES } from 'igniteui-angular';
// import { IGX_TABS_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-time-picker [(ngModel)]="time"></igx-time-picker>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_TIME_PICKER_DIRECTIVES, FormsModule]
    /* or imports: [IgxTimePickerComponent, FormsModule] */
})
export class HomeComponent {
    public time: Date;
}

    Agora que você importou o módulo Ignite UI for Angular Time Picker ou as diretivas, você pode começar a usar o componente igx-time-picker.

    Using the Angular Time Picker

    Default

    Para adicionar o seletor de tempo em um modelo, use o seguinte código:

    <!--meeting.component.html-->
<igx-time-picker></igx-time-picker>

    A saída deve ser a mesma da demonstração.

    Binding

    O Time Picker no Angular pode ser vinculado a um objeto Date ou a um valor de string somente de tempo no formato ISO 8601 definindo a propriedade value ou ngModel.

    Primeiro crie uma sequência de tempo no formato ISO 8601:

    public time = '09:15:30';

    Em seguida, use o ngModel para criar uma ligação de dados bidirecional:

    <igx-time-picker [(ngModel)]="time"></igx-time-picker>

    ou defina value de entrada no modelo:

    <igx-time-picker [value]="time"></igx-time-picker>

    Para usá-lo em um formulário reativo, você precisa definir um formControlName no seletor

    <form [formGroup]="form">
    <igx-time-picker formControlName="timePicker"></igx-time-picker>
</form>

    export class SampleFormComponent {
    // ...
    public form: FormGroup;
    constructor(private fb: FormBuilder) {
        this.form = this.fb.group({
            timePicker: ['', Validators.required]
        });
    }
}

    Projecting components

    O componente seletor de tempo permite projetar componentes filhos - o mesmo que no IgxInputGroupComponent: igxLabel, IgxHint, igxPrefix, igxSuffix, excluindo IgxInput. Informações mais detalhadas sobre isso podem ser encontradas no tópico Label & Input.

    Na configuração padrão, um ícone de alternância de menu suspenso/diálogo é exibido como um prefixo. Ele pode ser alterado ou redefinido usando o componente IgxPickerToggleComponent. Ele pode ser decorado com igxPrefix ou igxSuffix, que definirão sua posição - no início da entrada ou no final, respectivamente.

    No exemplo a seguir, adicionamos um rótulo e uma dica personalizados e alteramos a posição padrão do ícone de alternância para ser exibido como um sufixo:

    <igx-time-picker [(ngModel)]="date" mode="dialog" [inputFormat]="'hh:mm'">
    <label igxLabel>Home Time </label>
    <igx-picker-toggle igxSuffix>
        <igx-icon>home</igx-icon>
    </igx-picker-toggle>
    <igx-hint>{{date.toLocaleString()}}</igx-hint>
</igx-time-picker>

    public date: Date = new Date();

    E aqui está nosso modelo de Ignite UI for Angular Time Picker:

    Custom action buttons

    O IgxTimePickerComponent suporta personalização de botões de ação. Para conseguir isso, envolva os botões em ng-template marcados com o seletor de diretiva igxPickerActions.

    No exemplo abaixo, botões de ação personalizados são adicionados para ações 'CANCELAR', 'CONCLUÍDO' e 'AGORA'.

    <!-- sample.component.html -->

<igx-time-picker #picker format="hh:mm" mode="dropdown">
    <ng-template igxTimePickerActions>
        <div class="container action-buttons">
            <button igxButton="flat" (click)="picker.cancelButtonClick()">cancel</button>
            <button igxButton="flat" (click)="picker.okButtonClick()">done</button>
            <button igxButton="flat" (click)="selectNow(picker)">now</button>
        </div>
    </ng-template>
</igx-time-picker>

    // sample.component.ts
...
public selectNow(timePicker: IgxTimePickerComponent) {
    timePicker.value = new Date();
    timePicker.close();
}
...

    E aí está, um seletor de tempo remodelado com menu suspenso, ações personalizadas e suporte para vinculação bidirecional:

    Customizing the toggle and clear icons

    O IgxTimePickerComponent pode ser configurado com IgxPickerToggleComponent e IgxPickerClearComponent, que podem ser usados para alterar os ícones de alternância e limpeza sem precisar adicionar seus próprios manipuladores de clique.

     <igx-time-picker>
    <label igxLabel>Select time</label>
    <igx-picker-toggle igxPrefix>
        <igx-icon>snooze</igx-icon>
    </igx-picker-toggle>
    <igx-picker-clear igxSuffix>
        <igx-icon>delete</igx-icon>
    </igx-picker-clear>
</igx-time-picker>

    Keyboard Navigation

    • Os usuários podem navegar pelas porções de tempo do componente por meio das teclas de seta para cima e para baixo do teclado ou rolando no campo de entrada e no menu suspenso/diálogo. A navegação na entrada é possível independentemente do minValue ou maxValue, enquanto a navegação no menu suspenso/diálogo será restrita dentro do intervalo minValue e maxValue.
    • O menu suspenso do seletor de tempo pode ser aberto clicando no ícone de alternância, tecla Espaço ou pressionando as teclas Alt + Seta para baixo. No modo de diálogo, isso pode ser feito clicando na entrada.
    • Pressionar a tecla Enter ou clicar com o mouse fora do menu suspenso/caixa de diálogo aplica a seleção e fecha o menu suspenso/caixa de diálogo.
    • Pressionar a tecla Escape cancela a seleção e fecha o menu suspenso/caixa de diálogo.
    • Ao inserir um novo valor enquanto o menu suspenso estiver fechado, clique fora do seletor de tempo ou pressione Tab para mover o foco para que o valor seja aceito.

    Examples

    Dialog Mode

    O modo padrão do seletor de tempo é o modo suspenso editável. Para alterar o modo do seletor de tempo para o modo de diálogo somente leitura, defina a entrada do mode para dialog:

    // timePickerDropdown.component.ts

import { PickerInteractionMode } from 'igniteui-angular';
// import { PickerInteractionMode } from '@infragistics/igniteui-angular'; for licensed package
...
public mode = PickerInteractionMode.Dialog;

    <!--timePickerDropdown.component.html-->
<igx-time-picker [mode]="mode"></igx-time-picker>

    ou apenas altere o mode no seletor de tempo assim:

    <!--timePickerDropdown.component.html-->
<igx-time-picker mode="dialog"></igx-time-picker>

    No modo de diálogo, o cabeçalho do diálogo exibe o tempo selecionado no momento no input format do seletor. Você pode alterar a posição do cabeçalho definindo a propriedade headerOrientation.

    Quando minValue e maxValue são definidos, a caixa de diálogo exibe o tempo dentro desse intervalo somente. Veja o exemplo de valor Min max abaixo, para mais detalhes.

    Display and input format

    O componente seletor de tempo suporta diferentes formatos de exibição e entrada.

    O formato de exibição é o formato do valor quando em modo de edição e pode ser um dos formatos Angular DatePipe listados. Isso permite que ele suporte opções de formato predefinidas, como shortTime e longTime.

    O formato de entrada é o formato do valor quando não estiver no modo de edição e o formato, no qual as partes de tempo são exibidas no menu suspenso/diálogo. A propriedade inputFormat aceita uma string de formato construída usando caracteres suportados pelo DatePipe, por exemplo, hh:mm:ss, mas não suporta opções de formato predefinidas, como shortTime e longTime. Se a propriedade inputFormat não for definida, o padrão será hh:mm tt. Como alternativa, se a propriedade inputFormat não for definida, o formato de entrada será inferido do displayFormat caso possa ser analisado como contendo apenas partes numéricas de data e hora.

    <igx-time-picker
    [(ngModel)]="time"
    [inputFormat]="`hh:mm:ss`"
    [displayFormat]="`shortTime`">
</igx-time-picker>
    Note

    O IgxTimePicker agora suporta entrada IME. Quando a composição termina, o controle converte os números de caracteres largos para caracteres ASCII.

    Increment and decrement

    O seletor de tempo expõe métodos públicos increment e decrement, que aceitam dois parâmetros opcionais: o DatePart a ser modificado e o delta pelo qual ele será alterado. Se não for especificado, o DatePart assume o padrão Hours e o delta assume o padrão itemsDelta.

    Você pode encontrar um exemplo que ilustra o uso de ambos os métodos em Date Time Editor Directive.

    Forms and Validation

    O componente time picker suporta todas as diretivas do FormsModule NgModel e ReactiveFormsModule principais (FormControl, FormGroup, etc.). Isso também inclui as funções Forms Validators. Além disso, os valores min e max do componente também atuam como validadores de formulário.

    O exemplo de integração de formulários reativos demonstra como usar o igxTimePicker em formulários reativos.

    Valor mínimo máximo

    Você pode especificar minValue e maxValue para restringir a entrada do usuário, em cujo caso o menu suspenso/diálogo exibirá o tempo dentro desse intervalo somente. No modo suspenso, no entanto, ainda é possível que o usuário digite um tempo inválido. Você pode manipular o evento validationFailed para notificar o usuário se isso acontecer.

    Note

    Os valores mínimo/máximo devem ser um objeto Date ou uma string somente de tempo no formato ISO 8601:

    // app.module.ts

...
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IgxTimePickerModule, IgxToastModule } from 'igniteui-angular';
// import { IgxTimePickerModule, IgxToastModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., BrowserAnimationsModule, IgxTimePickerModule, IgxToastModule],
    ...
})
export class AppModule {}

// app.component.ts

public time = '10:00:00';
public min = '09:15:30';
public max = '18:15:30';

@ViewChild('toast', { static: true })
private toast;

public onValidationFailed() {
    this.toast.open();
}

    <igx-time-picker
	[(ngModel)]="time"
    [itemsDelta]="{hours:2, minutes:5}"
    [inputFormat]="'hh:mm:ss tt'"
    [headerOrientation]="true"
    [minValue]="min"
    [maxValue]="max"
	(onValidationFailed)="onValidationFailed()">
	<label igxLabel>Meeting Start</label>
</igx-time-picker>

<igx-toast #toast message="Value must be between 09:15:30 AM and 06:15:30 PM"></igx-toast>

    O menu suspenso exibe valores dentro do intervalo min/max (09:15:30 AM~06:15:30 PM) com base no delta dos itens. Um toast é adicionado para mostrar uma mensagem quando um horário inválido foi digitado.

    Note

    Os valores exibidos para cada porção de tempo no menu suspenso/diálogo são calculados com base no delta dos itens, sempre começando do zero. Se o minValue e maxValue não corresponderem ao delta dos itens, os valores exibidos começarão/terminarão do próximo/último valor possível que corresponda ao limite.

    E aí está:

    Usando o seletor de data e hora juntos

    Em alguns casos, quando o IgxDatePicker e o IgxTimePicker são usados juntos, pode ser necessário vinculá-los ao mesmo valor do objeto Date.

    Para conseguir isso em formulários baseados em modelos, use o ngModel para vincular ambos os componentes ao mesmo objeto Date.

    Em formulários reativos, podemos manipular o evento valueChange de cada componente e atualizar o valor do outro.

    Estilização

    Para começar a estilizar o seletor de tempo, precisamos importar o arquivo index, onde todas as funções do tema e mixins de componentes estão localizados:

    @use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

    Seguindo a abordagem mais simples, criamos um novo tema que estende o time-picker-theme e aceita parâmetros que estilizam o time picker.

    $my-time-picker-theme: time-picker-theme(
  $text-color: #e4c8a5,
  $hover-text-color: #ecaa53,
  $selected-text-color: #ecaa53,
  $header-background: #ecaa53,
  $header-hour-text-color: #011627,
  $header-time-period-color: #011627,
  $background-color: #011627
);
    Note

    Para estilizar quaisquer componentes adicionais que são usados como parte do conteúdo da janela do seletor de tempo (como o IgxButton), um tema adicional deve ser criado, específico para o respectivo componente e colocado somente no escopo da janela de diálogo (para que não afete o restante do aplicativo).

    Como a janela do seletor de tempo usa o IgxOverlayService, para que nosso tema personalizado alcance a janela do seletor de tempo que queremos estilizar, forneceremos uma saída específica onde a janela de diálogo será colocada no DOM quando estiver visível.

    Os itens em nosso seletor de tempo não são descendentes do nosso host de componente - eles estão sendo exibidos atualmente no outlet de sobreposição padrão, no final do corpo do document. A alteração disso é feita usando a propriedade outlet em overlaySettings. O outlet controla onde o contêiner de sobreposição deve ser renderizado.

    Aqui, podemos passar uma referência ao elemento onde gostaríamos que nosso contêiner estivesse:

    <igx-time-picker #picker [overlaySettings]="{ outlet: element }">
</igx-time-picker>

    export class TimepickerStylingComponent {
    constructor(public element: ElementRef) {
    }
}

    Agora, os itens do seletor de tempo são renderizados corretamente dentro do host do nosso componente, o que significa que nosso tema personalizado entrará em vigor:

    Note

    Para saber mais sobre as várias opções para fornecer temas aos elementos que são exibidos usando o IgxOverlayService, você pode dar uma olhada no tópico Estilo de sobreposição.

     @include css-vars($my-time-picker-theme);
    Warning

    Se o componente estiver usando um Emulated ViewEncapsulation, é necessário penetrate neste encapsulamento usando::ng-deep

    :host {
  ::ng-deep {
    @include css-vars($my-time-picker-theme);
  }
}

    Demo

    API References

    Theming Dependencies

    Additional Resources

    Nossa comunidade é ativa e sempre acolhedora para novas ideias.