Padrões de UI Angular
Princípios Fundamentais
- Nunca mostre UI desatualizada - Estados de carregamento apenas quando realmente estiver carregando
- Sempre exiba erros - Os usuários devem saber quando algo falha
- Atualizações otimistas - Faça a UI parecer instantânea
- Divulgação progressiva - Use
@deferpara mostrar o conteúdo conforme disponível - Degradação graciosa - Dados parciais são melhores do que nenhum dado
Padrões de Estado de Carregamento
A Regra de Ouro
Mostre o indicador de carregamento SOMENTE quando não houver dados para exibir.
@Component({
template: `
@if (error()) {
<app-error-state [error]="error()" (retry)="load()" />
} @else if (loading() && !items().length) {
<app-skeleton-list />
} @else if (!items().length) {
<app-empty-state message="Nenhum item encontrado" />
} @else {
<app-item-list [items]="items()" />
}
`,
})
export class ItemListComponent {
private store = inject(ItemStore);
items = this.store.items;
loading = this.store.loading;
error = this.store.error;
}
Árvore de Decisão de Estado de Carregamento
Tem um erro?
→ Sim: Mostre o estado de erro com opção de repetir
→ Não: Continue
Está carregando E não temos dados?
→ Sim: Mostre o indicador de carregamento (spinner/esqueleto)
→ Não: Continue
Temos dados?
→ Sim, com itens: Mostre os dados
→ Sim, mas vazio: Mostre o estado vazio
→ Não: Mostre carregamento (fallback)
Esqueleto vs Spinner
| Use Esqueleto Quando | Use Spinner Quando |
|---|---|
| Forma de conteúdo conhecida | Forma de conteúdo desconhecida |
| Layouts de lista/cartão | Ações de modal |
| Carregamento inicial de página | Envios de botão |
| Placeholders de conteúdo | Operações inline |
Padrões de Fluxo de Controle
@if/@else para Renderização Condicional
@if (user(); as user) {
<span>Bem-vindo, {{ user.name }}</span>
} @else if (loading()) {
<app-spinner size="small" />
} @else {
<a routerLink="/login">Entrar</a>
}
@for com Track
@for (item of items(); track item.id) {
<app-item-card [item]="item" (delete)="remove(item.id)" />
} @empty {
<app-empty-state
icon="inbox"
message="Nenhum item ainda"
actionLabel="Criar Item"
(action)="create()"
/>
}
@defer para Carregamento Progressivo
<!-- Conteúdo crítico carrega imediatamente -->
<app-header />
<app-hero-section />
<!-- Conteúdo não crítico adiado -->
@defer (on viewport) {
<app-comments [postId]="postId()" />
} @placeholder {
<div class="h-32 bg-gray-100 animate-pulse"></div>
} @loading (minimum 200ms) {
<app-spinner />
} @error {
<app-error-state message="Falha ao carregar comentários" />
}
Padrões de Tratamento de Erros
Hierarquia de Tratamento de Erros
1. Erro inline (nível de campo) → Erros de validação de formulário
2. Notificação toast → Erros recuperáveis, usuário pode tentar novamente
3. Banner de erro → Erros de nível de página, dados ainda parcialmente utilizáveis
4. Tela de erro completa → Irrecuperável, precisa de ação do usuário
Sempre Mostre Erros
CRÍTICO: Nunca engula erros silenciosamente.
// CORRETO - Erro sempre exibido ao usuário
@Component({...})
export class CreateItemComponent {
private store = inject(ItemStore);
private toast = inject(ToastService);
async create(data: CreateItemDto) {
try {
await this.store.create(data);
this.toast.success('Item criado com sucesso');
this.router.navigate(['/items']);
} catch (error) {
console.error('createItem falhou:', error);
this.toast.error('Falha ao criar item. Por favor, tente novamente.');
}
}
}
// ERRADO - Erro capturado silenciosamente
async create(data: CreateItemDto) {
try {
await this.store.create(data);
} catch (error) {
console.error(error); // O usuário não vê nada!
}
}
Padrão de Componente de Estado de Erro
@Component({
selector: "app-error-state",
standalone: true,
imports: [NgOptimizedImage],
template: `
<div class="error-state">
<img ngSrc="/assets/error-icon.svg" width="64" height="64" alt="" />
<h3>{{ title() }}</h3>
<p>{{ message() }}</p>
@if (retry.observed) {
<button (click)="retry.emit()" class="btn-primary">Tentar Novamente</button>
}
</div>
`,
})
export class ErrorStateComponent {
title = input("Algo deu errado");
message = input("Ocorreu um erro inesperado");
retry = output<void>();
}
Padrões de Estado de Botão
Estado de Carregamento do Botão
<button
(click)="handleSubmit()"
[disabled]="isSubmitting() || !form.valid"
class="btn-primary"
>
@if (isSubmitting()) {
<app-spinner size="small" class="mr-2" />
Salvando... } @else { Salvar Alterações }
</button>
Desabilitar Durante Operações
CRÍTICO: Sempre desabilite gatilhos durante operações assíncronas.
// CORRETO - Botão desabilitado enquanto carrega
@Component({
template: `
<button
[disabled]="saving()"
(click)="save()"
>
@if (saving()) {
<app-spinner size="sm" /> Salvando...
} @else {
Salvar
}
</button>
`
})
export class SaveButtonComponent {
saving = signal(false);
async save() {
this.saving.set(true);
try {
await this.service.save();
} finally {
this.saving.set(false);
}
}
}
// ERRADO - Usuário pode clicar várias vezes
<button (click)="save()">
{{ saving() ? 'Salvando...' : 'Salvar' }}
</button>
Estados Vazios
Requisitos para Estado Vazio
Toda lista/coleção DEVE ter um estado vazio:
@for (item of items(); track item.id) {
<app-item-card [item]="item" />
} @empty {
<app-empty-state
icon="folder-open"
title="Nenhum item ainda"
description="Crie seu primeiro item para começar"
actionLabel="Criar Item"
(action)="openCreateDialog()"
/>
}
Estados Vazios Contextuais
@Component({
selector: "app-empty-state",
template: `
<div class="empty-state">
<span class="icon" [class]="icon()"></span>
<h3>{{ title() }}</h3>
<p>{{ description() }}</p>
@if (actionLabel()) {
<button (click)="action.emit()" class="btn-primary">
{{ actionLabel() }}
</button>
}
</div>
`,
})
export class EmptyStateComponent {
icon = input("inbox");
title = input.required<string>();
description = input("");
actionLabel = input<string | null>(null);
action = output<void>();
}
Padrões de Formulário
Formulário com Carregamento e Validação
@Component({
template: `
<form [formGroup]="form" (ngSubmit)="onSubmit()">
<div class="form-field">
<label for="name">Nome</label>
<input
id="name"
formControlName="name"
[class.error]="isFieldInvalid('name')"
/>
@if (isFieldInvalid("name")) {
<span class="error-text">
{{ getFieldError("name") }}
</span>
}
</div>
<div class="form-field">
<label for="email">Email</label>
<input id="email" type="email" formControlName="email" />
@if (isFieldInvalid("email")) {
<span class="error-text">
{{ getFieldError("email") }}
</span>
}
</div>
<button type="submit" [disabled]="form.invalid || submitting()">
@if (submitting()) {
<app-spinner size="sm" /> Enviando...
} @else {
Enviar
}
</button>
</form>
`,
})
export class UserFormComponent {
private fb = inject(FormBuilder);
submitting = signal(false);
form = this.fb.group({
name: ["", [Validators.required, Validators.minLength(2)]],
email: ["", [Validators.required, Validators.email]],
});
isFieldInvalid(field: string): boolean {
const control = this.form.get(field);
return control ? control.invalid && control.touched : false;
}
getFieldError(field: string): string {
const control = this.form.get(field);
if (control?.hasError("required")) return "Este campo é obrigatório";
if (control?.hasError("email")) return "Formato de email inválido";
if (control?.hasError("minlength")) return "Muito curto";
return "";
}
async onSubmit() {
if (this.form.invalid) return;
this.submitting.set(true);
try {
await this.service.submit(this.form.value);
this.toast.success("Enviado com sucesso");
} catch {
this.toast.error("Falha ao enviar");
} finally {
this.submitting.set(false);
}
}
}
Padrões de Diálogo/Modal
Diálogo de Confirmação
// dialog.service.ts
@Injectable({ providedIn: 'root' })
export class DialogService {
private dialog = inject(Dialog); // CDK Dialog ou custom
async confirm(options: {
title: string;
message: string;
confirmText?: string;
cancelText?: string;
}): Promise<boolean> {
const dialogRef = this.dialog.open(ConfirmDialogComponent, {
data: options,
});
return await firstValueFrom(dialogRef.closed) ?? false;
}
}
// Uso
async deleteItem(item: Item) {
const confirmed = await this.dialog.confirm({
title: 'Excluir Item',
message: `Tem certeza que deseja excluir "${item.name}"?`,
confirmText: 'Excluir',
});
if (confirmed) {
await this.store.delete(item.id);
}
}
Anti-Padrões
Estados de Carregamento
// ERRADO - Spinner quando os dados existem (causa flash ao recarregar)
@if (loading()) {
<app-spinner />
}
// CORRETO - Mostrar carregamento apenas sem dados
@if (loading() && !items().length) {
<app-spinner />
}
Tratamento de Erros
// ERRADO - Erro engolido
try {
await this.service.save();
} catch (e) {
console.log(e); // O usuário não faz ideia!
}
// CORRETO - Erro exibido
try {
await this.service.save();
} catch (e) {
console.error("Falha ao salvar:", e);
this.toast.error("Falha ao salvar. Por favor, tente novamente.");
}
Estados de Botão
<!-- ERRADO - Botão não desabilitado durante envio -->
<button (click)="submit()">Enviar</button>
<!-- CORRETO - Desabilitado e mostra carregamento -->
<button (click)="submit()" [disabled]="loading()">
@if (loading()) {
<app-spinner size="sm" />
} Enviar
</button>
Lista de Verificação de Estado de UI
Antes de completar qualquer componente de UI:
Estados de UI
- Estado de erro tratado e exibido ao usuário
- Estado de carregamento exibido apenas quando não há dados
- Estado vazio fornecido para coleções (bloco
@empty) - Botões desabilitados durante operações assíncronas
- Botões mostram indicador de carregamento quando apropriado
Dados e Mutações
- Todas as operações assíncronas têm tratamento de erro
- Todas as ações do usuário têm feedback (toast/visual)
- Atualizações otimistas revertem em caso de falha
Acessibilidade
- Estados de carregamento anunciados para leitores de tela
- Mensagens de erro vinculadas aos campos do formulário
- Gerenciamento de foco após mudanças de estado
Integração com Outras Skills
- angular-state-management: Use Signal stores para estado
- angular: Aplique padrões modernos (Signals, @defer)
- testing-patterns: Teste todos os estados de UI