overloads Sobrecargas de função
Última atualização: 2026-10-22
overloads Sobrecargas de função
Declarações de sobrecarga dão a uma função várias folhas de assinatura: quem chama recebe um tipo de retorno preciso para cada forma de argumento, enquanto a implementação é escrita uma única vez. O TS casa de cima para baixo e só reporta erro se nenhuma couber.
| Grupo | Funções e Classes |
|---|---|
| Tipo | Sintaxe |
| Modo strict | Não necessário |
ℹ️ Info O editor transpila TypeScript para JavaScript e o executa (sem verificação de tipos); veja a Saída de cada exemplo para o resultado da verificação.
📝 Sintaxe
function format(value: number): string; // número → valor monetário
function format(value: Date): string; // Date → string de data
function format(value: number | Date): string { // a assinatura de implementação fica invisível para quem chama
return value instanceof Date
? value.toISOString().slice(0, 10)
: `¥${value.toFixed(2)}`;
}⚙️ Parâmetros
| f(...): T; | Declarações sem corpo, escritas em sequência; casadas em ordem |
|---|---|
| f(...) { } | A única assinatura com corpo; seus parâmetros devem ser compatíveis com todas as sobrecargas, mas ela é invisível para quem chama |
Retorno：Determinado pela sobrecarga casada — cada sobrecarga pode declarar seu próprio tipo de retorno, e quem chama recebe o tipo preciso para a forma de seus argumentos.
▶ Exemplo
Edite o código abaixo e clique em Testar para ver o resultado transpilado:
Saída：
¥42.00
2026-01-15
(Saída de execução após a transpilação; as assinaturas de sobrecarga desaparecem — em execução só existe a função de implementação, sem custo de desvio)💡 Observações
ℹ️ Info Só a implementação sobrevive à compilação — assinaturas de sobrecarga são sintaxe de tempo de compilação, sem qualquer pegada em execução.
⚠️ Atenção A assinatura de implementação é invisível para quem chama: seus parâmetros devem cobrir todas as sobrecargas; caso contrário, chamadas válidas darão erro nela.
💡 Dica As sobrecargas casam de cima para baixo: coloque assinaturas específicas primeiro e as amplas por último; senão uma assinatura ampla rouba chamadas destinadas a uma específica.
🏷️ Funções e Classes Relacionadas
💡 Casos relacionados
Mais casos em breve.
📚 Tutoriais relacionados
❓ Perguntas frequentes
P Sobrecargas ou parâmetro união?
R Sobrecargas quando o tipo do argumento muda o tipo de retorno (uma folha precisa para cada); parâmetro união com estreitamento quando afeta apenas a lógica interna e o retorno é o mesmo.
P Por que recebo "no overload matches this call"?
R Verifique duas coisas: se os argumentos realmente se encaixam em alguma sobrecarga e se a ordem faz sentido (uma assinatura ampla no início bloqueia as específicas depois).
P Funções arrow podem ter sobrecargas?
R Não. Sobrecargas exigem declarações function; para variáveis, use a forma de tipo de objeto type Overloaded = { (x: string): A; (x: number): B }.
