Declaration Reference

O propósito desse guia é te ensinar como escrever um arquivo de definição de alta qualidade. A estrutura desse guia exibe a documentação de uma API, juntamente com amostras de uso e explicações de como escrever a declaração correspondente.

Esses exemplos são ordenados por ordem crescente aproximada de complexidade.

Objetos com Propriedades

Documentação

A variável global minhaLib possui uma função criaCumprimento para criar saudações, e uma propriedade numeroDeCumprimentos indicando o numero de cumprimentos feitos ate ali.

Código

ts
let resultado = minhaLib.criaCumprimento("Olá, mundo");
console.log("O cumprimento computado é:" + resultado);
let count = minhaLib.numeroDeCumprimentos;

Declaração

Use declare namespace para descrever tipos ou valores acessados via notação por ponto.

ts
declare namespace minhaLib {
  function criaCumprimento(s: string): string;
  let numeroDeCumprimentos: number;
}

Funções Sobrecarregadas

Documentação

A função pegaFerramenta aceita um número e retorna uma Ferramenta, ou aceita uma string e retorna um array de Ferramentas.

Código

ts
let x: Ferramenta = pegaFerramenta(43);
let arr: Ferramenta[] = pegaFerramenta("todas");

Declaração

ts
declare function pegaFerramenta(n: number): Ferramenta;
declare function pegaFerramenta(s: string): Ferramenta[];

Tipos Reutilizáveis (Interfaces)

Documentação

Ao especificar uma saudação, você deve passar um objeto ConfiguracoesCumprimento. Esse objeto tem as seguintes propriedades:

1 - cumprimento: String obrigatória

2 - duracao: Comprimento de tempo opcional (em milissegundos)

3 - cor: String opcional, ex: ‘#ff00ff’

Código

ts
cumprimenta({
  cumprimento: "olá mundo",
  duracao: 4000
});

Declaração

Use uma interface para definir um tipo com propriedades.

ts
interface ConfiguracoesCumprimento {
  cumprimento: string;
  duracao?: number;
  cor?: string;
}
declare function cumprimenta(setting: ConfiguracoesSaudacao): void;

Tipos reutilizáveis (Tipo Aliases)

Documentação

Em qualquer lugar que um cumprimento é esperado, você pode prover uma string, uma função retornando uma string, ou uma instancia de Cumprimentador.

Código

ts
function pegaCumprimento() {
  return "oopa";
}
class MeuCumprimentador extends Cumprimentador {}
cumprimenta("olá");
cumprimenta(pegaCumprimento);
cumprimenta(new MeuCumprimentador());

Declaração

Você pode usar um alias para fazer uma abreviação para um tipo:

ts
type ComoUmCumprimentador = string | (() => string) | MeuCumprimentador;
declare function cumprimenta(g: ComoUmCumprimentador): void;

Organizando Tipos

Documentação

O objeto cumprimentador pode passar log para um arquivo ou mostrar um alerta. Você pode prover LogOptions para .log(...) e opções de alerta para .alert(...)

Código

ts
const g = new Cumprimentador("Olá");
g.log({ verbose: true });
g.alert({ modal: false, title: "Cumprimento Atual" });

Declaração

Use namespaces para organizar tipos.

ts
declare namespace CumprimentoLib {
  interface LogOptions {
    verbose?: boolean;
  }
  interface AlertOptions {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

Voce também pode criar namespaces aninhados em uma declaração:

ts
declare namespace CumprimentoLib.Options {
  // Faz referência via CumprimentoLib.Options.Log
  interface Log {
    verbose?: boolean;
  }
  interface Alert {
    modal: boolean;
    title?: string;
    color?: string;
  }
}

Classes

Documentação

Você pode criar um cumprimentador ao instanciar o objeto Cumprimentador, ou ao criar um cumprimentador customizado ao estendê-lo.

Código

ts
const MeuCumprimentador = new Cumprimentador("Olá, mundo");
MeuCumprimentador.cumprimento = "oopa";
MeuCumprimentador.mostraCumprimento();
class CumprimentadorEspecial extends Cumprimentador {
  constructor() {
    super("Cumprimentador muito especial");
  }
}

Declaração

Use declare class para descrever uma classe ou um objeto semelhante a classe. Classes também podem possuir propriedades e métodos assim como um construtor.

ts
declare class Cumprimentador {
  constructor(cumprimento: string);
  cumprimento: string;
  mostraCumprimento(): void;
}

Variáveis Globais

Documentação

A variável global foo contém o numero de ferramentas atual.

Código

ts
console.log("Metade do numero de ferramentas é " + foo / 2);

Declaração

Use declare var para declarar variáveis. Se a variável é apenas-leitura, você pode usar declare const. Você também pode usar declare let se a variável é de escopo-fechado.

ts
/** O numero de ferramentas atual */
declare var foo: number;

Global Functions

Documentação

Você pode chamar a função cumprimenta com uma string para mostrar um cumprimento para o usuário.

Código

ts
cumprimenta("olá, mundo");

Declaração

Use declare function para declarar funções.

ts
declare function cumprimenta(cumprimento: string): void;