English 中文 العربية 日本語 Português

.d.ts Arquivos de declaração

Última atualização: 2026-10-22

.d.ts Arquivos de declaração

Arquivos de declaração (.d.ts) descrevem como uma biblioteca é sem conter nenhuma implementação, permitindo ao TypeScript verificar tipos de bibliotecas JS puras. Os tipos vêm de três fontes: incluídos na biblioteca (o melhor), pacotes comunitários @types (npm i -D @types/xxx) ou escritos à mão. O núcleo da escrita manual é a palavra-chave declare — ela afirma "este valor/função é implementado em outro lugar", e o compilador não emite código algum para ele.

GrupoConfiguração e Prática
TipoConfiguração
Modo strictNã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

// my-lib.d.ts — arquivo de declaração: apenas tipos, apagado após compilar
declare const APP_VERSION: string;
declare function log(msg: string): void;

interface Config {
  host: string;
  port: number;
  debug?: boolean;
}

// Instale tipos da comunidade: npm i -D @types/lodash

⚙️ Parâmetros

declare const / letDeclara um valor fornecido pelo ambiente hospedeiro (uma biblioteca, uma global de CDN, ...); o tipo vem da sua descrição
declare functionDeclara uma assinatura de função para uma implementação existente — apenas tipos, sem corpo
@types/*Pacotes de declarações mantidos pela comunidade (DefinitelyTyped); instale-os em devDependencies e eles entram em vigor automaticamente

Retorno：Nenhum — arquivos .d.ts não emitem JS após a compilação; eles apenas fornecem informações de tipo ao compilador.

▶ Exemplo

Edite o código abaixo e clique em Testar para ver o resultado transpilado:

Saída：

info app booted
[10:24:00] OK db connected

(Saída de execução após a transpilação; o formato de LogOptions vem do .d.ts — passar { timestamps: "yes" } produz error TS2322)
▶ Testar

💡 Observações

ℹ️ Info Prioridade de resolução de tipos: o .d.ts apontado pelo campo types do package.json da biblioteca vence, depois vêm os pacotes @types e, por fim, as declarações escritas à mão no projeto.
💡 Dica Ao escrever declarações à mão, execute a biblioteca uma vez e registre o formato real como uma interface — muito mais confiável do que adivinhar pela documentação; marque campos incertos como opcionais.
⚠️ Atenção Variáveis declaradas não têm JS de sustentação após a compilação — o valor em tempo de execução precisa vir do ambiente. Se nada atribui LOG_LEVEL, você obtém undefined em tempo de execução e o TypeScript não avisará.
tsconfig es-modules
Mais casos em breve.

📚 Tutoriais relacionados

Arquivos de declaração do TypeScript
Lição 21: Arquivos de declaração do TypeScript

❓ Perguntas frequentes

P Instalei @types/xxx e ainda não há tipos — e agora?
R Verifique o nome do pacote (@types/ mais o nome do pacote original) e o escopo include do seu tsconfig; se o DefinitelyTyped não tiver nada, escreva à mão: crie um .d.ts, descreva com declare as APIs que você usa e mantenha-o dentro do escopo de compilação (global ou por módulo).
P Qual é a diferença entre declare const e um const normal?
R Um const normal compila para uma variável JS real; declare const é uma promessa no nível de tipo dizendo ao compilador "esse nome existirá em tempo de execução" — nada é emitido. Por isso, instruções declare não podem ter inicializadores.
P Para que serve declare module "xxx"?
R Declaração de módulo ambiente: adiciona tipos para um pacote npm ou recurso não TS. Dois usos típicos — declare module "pkg" { ... } para pacotes de terceiros sem tipos, e declare module "*.css" para que importações de estilos parem de falhar com "cannot find module".
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%