From 0e07a6acde9bff6b6e37b5d390e9d5ef0c19bd36 Mon Sep 17 00:00:00 2001 From: guuszz Date: Wed, 3 Jun 2026 19:37:45 -0300 Subject: [PATCH] docs(pt): translate handbook-v2/Type Declarations Co-Authored-By: Claude Opus 4.8 (1M context) --- .../pt/handbook-v2/Type Declarations.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/documentation/pt/handbook-v2/Type Declarations.md diff --git a/docs/documentation/pt/handbook-v2/Type Declarations.md b/docs/documentation/pt/handbook-v2/Type Declarations.md new file mode 100644 index 00000000..2d6130a1 --- /dev/null +++ b/docs/documentation/pt/handbook-v2/Type Declarations.md @@ -0,0 +1,100 @@ +--- +title: Declarações de Tipo +layout: docs +permalink: /pt/docs/handbook/2/type-declarations.html +oneline: "Como o TypeScript fornece tipos para JavaScript não tipado." +--- + +Ao longo das seções que você leu até agora, estivemos demonstrando conceitos básicos do TypeScript usando as funções embutidas presentes em todos os runtimes de JavaScript. +No entanto, quase todo JavaScript hoje inclui muitas bibliotecas para realizar tarefas comuns. +Ter tipos para as partes da sua aplicação que _não são_ o seu código vai melhorar muito a sua experiência com TypeScript. +De onde vêm esses tipos? + +## Com o Que se Parecem as Declarações de Tipo? + +Digamos que você escreva um código como este: + +```ts twoslash +// @errors: 2339 +const k = Math.max(5, 6); +const j = Math.mix(7, 8); +``` + +Como o TypeScript sabia que `max` estava presente, mas `mix` não, mesmo que a implementação de `Math` não fizesse parte do seu código? + +A resposta é que existem _arquivos de declaração_ (declaration files) descrevendo esses objetos embutidos. +Um arquivo de declaração fornece uma forma de _declarar_ a existência de alguns tipos ou valores sem realmente fornecer implementações para esses valores. + +## Arquivos `.d.ts` + +O TypeScript tem dois tipos principais de arquivos. +Arquivos `.ts` são arquivos de _implementação_ que contêm tipos e código executável. +Esses são os arquivos que produzem saídas `.js`, e são onde você normalmente escreveria seu código. + +Arquivos `.d.ts` são arquivos de _declaração_ que contêm _apenas_ informação de tipo. +Esses arquivos não produzem saídas `.js`; eles são usados apenas para verificação de tipos. +Vamos aprender mais sobre como escrever nossos próprios arquivos de declaração mais tarde. + +## Definições de Tipo Embutidas + +O TypeScript inclui arquivos de declaração para todas as APIs embutidas padronizadas disponíveis nos runtimes de JavaScript. +Isso inclui coisas como métodos e propriedades de tipos embutidos como `string` ou `function`, nomes de nível superior como `Math` e `Object`, e seus tipos associados. +Por padrão, o TypeScript também inclui tipos para coisas disponíveis ao rodar dentro do navegador, como `window` e `document`; estes são coletivamente chamados de APIs do DOM. + +O TypeScript nomeia esses arquivos de declaração com o padrão `lib.[algo].d.ts`. +Se você navegar até um arquivo com esse nome, pode saber que está lidando com alguma parte embutida da plataforma, não com código do usuário. + +### Configuração `target` + +Os métodos, propriedades e funções disponíveis para você variam, na verdade, com base na _versão_ do JavaScript em que seu código está rodando. +Por exemplo, o método `startsWith` de strings está disponível apenas a partir da versão do JavaScript conhecida como _ECMAScript 6_. + +Estar ciente de qual versão do JavaScript seu código vai rodar no fim das contas é importante porque você não quer usar APIs que são de uma versão mais nova do que a plataforma na qual você faz deploy. +Esta é uma das funções da configuração de compilador [`target`](/tsconfig#target). + +O TypeScript ajuda com esse problema variando quais arquivos `lib` são incluídos por padrão com base na sua configuração [`target`](/tsconfig#target). +Por exemplo, se [`target`](/tsconfig#target) for `ES5`, você vai ver um erro ao tentar usar o método `startsWith`, porque esse método só está disponível no `ES6` ou posterior. + +### Configuração `lib` + +A configuração [`lib`](/tsconfig#lib) permite um controle mais granular sobre quais arquivos de declaração embutidos são considerados disponíveis no seu programa. +Veja a página de documentação sobre [`lib`](/tsconfig#lib) para mais informações. + +## Definições Externas + +Para APIs não embutidas, há uma variedade de formas de obter arquivos de declaração. +Como você faz isso depende exatamente de qual biblioteca você está obtendo tipos. + +### Tipos Empacotados + +Se uma biblioteca que você está usando é publicada como um pacote npm, ela pode já incluir arquivos de declaração de tipo como parte de sua distribuição. +Você pode ler a documentação do projeto para descobrir, ou simplesmente tentar importar o pacote e ver se o TypeScript consegue resolver os tipos automaticamente para você. + +Se você é autor de um pacote considerando empacotar definições de tipo com seu pacote, pode ler nosso guia sobre [empacotar definições de tipo](/docs/handbook/declaration-files/publishing.html#including-declarations-in-your-npm-package). + +### DefinitelyTyped / `@types` + +O [repositório DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/) é um repo centralizado que armazena arquivos de declaração para milhares de bibliotecas. +A grande maioria das bibliotecas comumente usadas tem arquivos de declaração disponíveis no DefinitelyTyped. + +Definições no DefinitelyTyped também são publicadas automaticamente no npm sob o escopo `@types`. +O nome do pacote de tipos é sempre o mesmo que o nome do próprio pacote subjacente. +Por exemplo, se você instalou o pacote npm `react`, pode instalar seus tipos correspondentes rodando + +```sh +npm install --save-dev @types/react +``` + +O TypeScript encontra automaticamente definições de tipo em `node_modules/@types`, então não há nenhum outro passo necessário para deixar esses tipos disponíveis no seu programa. + +### Suas Próprias Definições + +No caso incomum de uma biblioteca não empacotar seus próprios tipos e não ter uma definição no DefinitelyTyped, você pode escrever um arquivo de declaração você mesmo. +Veja o apêndice [Escrevendo Arquivos de Declaração](/docs/handbook/declaration-files/introduction.html) para um guia. + +Se você quiser silenciar avisos sobre um módulo específico sem escrever um arquivo de declaração, também pode declarar rapidamente o módulo como tipo `any` colocando uma declaração vazia para ele em um arquivo `.d.ts` no seu projeto. +Por exemplo, se você quisesse usar um módulo chamado `some-untyped-module` sem ter definições para ele, você escreveria: + +```ts twoslash +declare module "some-untyped-module"; +```