diff --git a/docs/documentation/pt/declaration-files/Library Structures.md b/docs/documentation/pt/declaration-files/Library Structures.md new file mode 100644 index 00000000..fe50b376 --- /dev/null +++ b/docs/documentation/pt/declaration-files/Library Structures.md @@ -0,0 +1,326 @@ +--- +title: Estrutura de Bibliotecas +layout: docs +permalink: /pt/docs/handbook/declaration-files/library-structures.html +oneline: Como estruturar seus arquivos .d.ts +--- + +Amplamente falando, a forma como você _constrói_ seus arquivos de declaração depende de como a biblioteca é consumida. +Há muitas formas de distribuir uma biblioteca para consumo em JavaScript, e você precisará escrever seus arquivos de declaração correspondentes. +Esse guia cobre como identificar padrões comuns de bibliotecas e como escrever arquivos de declaração que correspondem a cada padrão. + +Cada principal tipo de construção de biblioteca tem um arquivo correspondente na seção dos [Templates](/docs/handbook/declaration-files/templates.html). +Você pode começar com esses templates para acelerar o processo. + +## Identificando Tipos de Bibliotecas + +Primeiro, vamos revisar quais tipos de bibliotecas os arquivos de declaração do Typescript podem representar. +Vamos mostrar brevemente como cada tipo de biblioteca é _usado_, como é _escrito_ e listar algumas bibliotecas de exemplo do mundo real. + +Identificar a estrutura da biblioteca é o primeiro passo para escrever seu arquivo de declaração. +Nós daremos dicas em como identificar estruturas baseado no _uso_ e no _código. +Dependendo da organização de documentação da biblioteca, uma pode ser mais fácil do que outra. +Recomendamos usar oq ue for mais confortável para você. + +### O que você deve procurar? + +Algumas perguntas para fazer a si mesmo enquanto olha para uma biblioteca que você está tentando tipar. + +1. Como você obtém a biblioteca? + + Por exemplo, você pode consegui-la _apenas_ pelo npm ou apenas por uma CDN? + +2. Como você importa ela? + + Ela adiciona um objecto global? Você usa o `require` ou os comandos `import`/`export`? + +### Exemplos menores para diferentes tipos de bibliotecas + +### Bibliotecas Modulares + +Quase todas as bibliotecas modernas do Node.js se encaixam na família modular. +Esse tipo de bibliotecas funcionam apenas num ambiente JavaScript com um carregador de módulos. +Por exemplo, `express` só funciona no Node.js e precisa ser carregado usando a função `require` do CommonJS. + +ECMAScript 2015 (também conhecido como ES2015, ECMAScript 6 e ES6), CommonJS e RequireJS tem formas similares de _importar_ um _módulo_. +Em JavaScript CommonJS (Node.js), por exemplo, você escreveria: + +```js +var fs = require("fs"); +``` + +Em Typescript ou ES6, a palavra chave `import` tem o mesmo propósito: + +```ts +import * as fs from "fs"; +``` + +Você vai tipicamente ver bibliotecas modulares incluírem linhas como essa em suas documentações: + +```js +var algumaBiblioteca = require("algumaBiblioteca"); +``` + +ou + +```js +define(..., ['algumaBiblioteca'], function(algumaBiblioteca) { + +}); +``` + +Assim como os módulos globais, você pode ver esses exemplos na documentção de um [módulo UMD](#umd), então tenha certeza de checar o código ou a documentação. + +#### Identificando Uma Biblioteca Modular Pelo Código + +Bibliotecas modulares vão tipicamente satisfazer pelo menos uma das condições seguintes: + +- Chamadas incondicionais do `require` ou `define` +- Declarações como `import * as a from 'b'` ou `export c;` +- Atribuições para `exports` ou `module.exports` + +Elas raramente terão: + +- Atribuições para propriedades do `window` ou `global` + +#### Templates Para Módulos + +Há quatro templates disponíveis para módulos, +[`module.d.ts`](/docs/handbook/declaration-files/templates/module-d-ts.html), [`module-class.d.ts`](/docs/handbook/declaration-files/templates/module-class-d-ts.html), [`module-function.d.ts`](/docs/handbook/declaration-files/templates/module-function-d-ts.html) e [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html). + +Você deveria ler primeiro [`module.d.ts`](/docs/handbook/declaration-files/templates/module-d-ts.html) para um entendimento da forma de que todos funcionam. + +Então use o template [`module-function.d.ts`](/docs/handbook/declaration-files/templates/module-function-d-ts.html) se seu módulo pode ser _chamado_ como uma função: + +```js +const x = require("foo"); +// Nota: chamando 'x' como uma função +const y = x(42); +``` + +Use o template [`module-class.d.ts`](/docs/handbook/declaration-files/templates/module-class-d-ts.html) se seu módulo pode ser _construído_ usando `new`: + +```js +const x = require("bar"); +// Nota: usando o operador 'new' na variável importada +const y = new x("oi"); +``` + +Se você tem um módulo que quando importado, faz mudanças em outros módulos use o template [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html): + +```js +const jest = require("jest"); +require("jest-matchers-files"); +``` + +### Bibliotecas Globais + +Uma biblioteca _global_ é a que pode ser acessada no escopo global (i.e. sem o uso de nenhuma forma do `import`). +Muitas bibliotecas simplesmente expõem uma ou mais variáveis globais para uso. +Por exemplo, se você estivesse usando [jQuery](https://jquery.com/), a variável `$` pode ser usada simplesmente se referindo a ela: + +```ts +$(() => { + console.log("oi!"); +}); +``` + +Você vai usualmente encontrar na documentação de uma biblioteca global, um guia de como usar a biblioteca em uma tag script do HTML: + +```html + +``` + +Hoje, a maioria das bibliotecas populares são escritas como bibliotecas UMD (veja abaixo). +A documentação de uma biblioteca UMD é difícil de distinguir de uma biblioteca normal. +Antes de escrever um arquivo de declaração global, tenha certeza de que a biblioteca não é UMD. + +#### Identificando Uma Biblioteca Global Pelo Código + +O código de uma biblioteca normal é usualmente extremamente simples. +Uma bilioteca global "Olá, mundo" pode parecer com isso: + +```js +function cirarCumprimento(s) { + return "Oi, " + s; +} +``` + +ou assim: + +```js +// Web +window.cirarCumprimento = function (s) { + return "Oi, " + s; +}; + +// Node +global.cirarCumprimento = function (s) { + return "Oi, " + s; +}; + +// Potencialmente qualquer ambiente de execução +globalThis.cirarCumprimento = function (s) { + return "Oi, " + s; +}; +``` + +Quando olhando para o código de uma biblioteca global, você usualmente verá: + +- Declaração de nível globalç com comandos `var` ou comandos `function` +- Uma ou mais atribuições para `window.algumNome` +- Presunções que primitivos da DOM tais como `document` ou `window` existem + +Você não verá: + +- Checagens por ou uso de carregadores de módulo tais como `require` ou `define` +- Importações no estilo do CommonJS/Node.js no formato `var fs = require("fs");` +- Chamadas para `define(...)` +- Documentação descrevendo como importar a biblioteca com `require` ou outro comando + +#### Exemplos de Bibliotecas Globais + +Por ser comunmente fácil tornar uma biblioteca global em uma biblioteca UMD, muito poucas bibliotecas populares ainda são escritas no estilo global. +Entretando, bibliotecas que são pequenas e requerem a DOM (ou tem _zero_ dependências) ainda podem ser globais. +] +#### Template de Bibliotecas Globais + +O arquivo de template [`global.d.ts`](/docs/handbook/declaration-files/templates/global-d-ts.html) define uma biblioteca exemplo `minhaBiblioteca`. +Tenha certeza de ler [a nota de rodapé "Prevenindo Conflitos de Nomes"](#prevenindo-conflitos-de-nomes). + +### _UMD_ + +Um módulo _UMD_ é um que pode ser usado _tanto como_ módulo (por alguma forma de importação), ou como global (quando executado em um ambiente sem um carregador de módulos). +Muitas bibliotecas populares, tais como [Moment.js](https://moment.js.com/), são escritas assim. +Por exemplo, no Node.js ou usando RequireJS, você escreveria: + +```ts +import moment = require("moment"); +console.log(moment.format()); +``` + +Enquanto que em um ambiente de navegador vanilla, você escreveria: + +```js +console.log(moment.format()); +``` + +#### Identificando uma Biblioteca UMD + +[Módulos UMD](https://github.com/umdjs/umd) procuram pela existência de um ambiente carregador de módulos. +É um padrão fácil de se encontrar que se parece com isso: + +```js +(function (root, factory) { + if (typeof define === "function" && define.amd) { + define(["libName"], factory); + } else if (typeof module === "object" && module.exports) { + module.exports = factory(require("libName")); + } else { + root.returnExports = factory(root.libName); + } +}(this, function (b) { +``` + +Se você ver testes como `typeof define`, `typeof window`, ou `typeof module` no código de uma biblioteca, especialmente no topo do arquivo, é quase sempre uma biblioteca UMD. + +Documentação de bibliotecas UMD vão frequentemente demonstrar um exemplo de "Usando em Node.js" usando o `require`, +e um exemplo de "Usando no navegador" usando uma tag `