TypeScript no Navegador: Tipagem Estrita do DOM, Eventos, Formulários e HTML5 Canvas
TypeScript no Navegador: Tipagem Estrita do DOM, Eventos, Formulários e HTML5 Canvas
HTMLInputElement, HTMLFormElement), captura precisa de eventos e renderização gráfica em HTML5 Canvas 2D sem erros em tempo de execução.
📑 Índice do Conteúdo
1. A Biblioteca DOM Nativa e a Hierarquia de Herança da Web API
O TypeScript possui suporte de primeira classe às APIs do navegador. Por padrão, a configuração lib: ["DOM", "DOM.Iterable", "ES2022"] no tsconfig.json inclui automaticamente mais de 20.000 declarações de tipo oficiais da W3C e WHATWG (arquivo lib.dom.d.ts).
Para manipular o DOM com maestria, é essencial entender a cadeia de herança orientada a objetos dos nós do navegador:
| Tipo na Hierarquia | Nível de Abstração | Propriedades e Métodos Disponíveis |
|---|---|---|
EventTarget |
Raiz Universal | addEventListener(), removeEventListener(), dispatchEvent() |
Node |
Nós da Árvore | parentNode, childNodes, appendChild(), textContent |
Element |
Tags Genéricas (HTML / SVG / XML) | classList, attributes, getAttribute(), innerHTML |
HTMLElement |
Elementos HTML Específicos | style, dataset, hidden, offsetHeight, click() |
HTMLInputElement (Subtipos) |
Tags Especializadas | value, checked, disabled, type, focus() |
2. Seleção de Elementos e a Armadilha do Valor null
Quando você busca um elemento na página através de document.getElementById() ou document.querySelector(), o compilador do TypeScript alerta imediatamente que o elemento pode não existir no DOM no momento da execução, retornando um tipo nullable (HTMLElement | null):
// 1. getElementById retorna "HTMLElement | null"
const botaoSalvar = document.getElementById("btn-salvar");
// Erro do compilador com strictNullChecks ativo:
// @ts-expect-error - TS18047: 'botaoSalvar' is possibly 'null'.
botaoSalvar.addEventListener("click", () => {});
// 2. Abordagem Sênior Segura (Guard Clause):
if (!botaoSalvar) {
console.error("Botão #btn-salvar não foi encontrado no DOM!");
} else {
// Aqui dentro, o TypeScript afunilou botaoSalvar para estritamente HTMLElement:
botaoSalvar.style.backgroundColor = "#10B981";
}
3. Asserção com “as” vs Verificação em Tempo de Execução com instanceof
Muitos desenvolvedores caem na tentação de forçar o tipo usando asserção cega: const campo = document.querySelector("#email") as HTMLInputElement;. Se o seletor estiver errado ou o HTML mudar para uma <textarea>, o código compilará sem erros, mas explodirá em runtime!
A melhor prática corporativa é utilizar o operador nativo instanceof, que serve simultaneamente como verificação de segurança em runtime e Type Guard para o compilador:
const elementoBusca = document.getElementById("campo-pesquisa");
// O operador instanceof afunila de HTMLElement | null para HTMLInputElement:
if (elementoBusca instanceof HTMLInputElement) {
// Autocomplete total das propriedades de input!
console.log("Termo digitado:", elementoBusca.value);
elementoBusca.placeholder = "Digite o termo desejado...";
} else {
console.warn("O elemento #campo-pesquisa não é um input HTML válido!");
}
4. Tipagem Estrita de Eventos e Listeners
Quando você utiliza addEventListener passando o nome exato do evento como string literal (ex: "click", "input", "keydown"), o TypeScript infere automaticamente o tipo do parâmetro de evento recebido no callback:
const formulario = document.querySelector<HTMLFormElement>("#form-cadastro");
if (formulario) {
// "e" é inferido automaticamente como SubmitEvent!
formulario.addEventListener("submit", (e: SubmitEvent) => {
e.preventDefault(); // Impede o recarregamento padrão da página
// FormData fortemente tipado
const dadosForm = new FormData(formulario);
const email = dadosForm.get("email") as string;
console.log("Enviando cadastro para:", email);
});
}
// Eventos de teclado com KeyboardEvent:
window.addEventListener("keydown", (e: KeyboardEvent) => {
if (e.key === "Escape") {
console.log("Tecla ESC pressionada! Fechando modal...");
}
});
e.target representa o elemento específico mais interno que recebeu o clique (tipo EventTarget | null). Já e.currentTarget representa o elemento ao qual o ouvinte foi diretamente anexado (fortemente tipado pelo TypeScript com o tipo do container).
5. HTML5 Canvas: Gráficos 2D Fortemente Tipados
O elemento <canvas> é o padrão da web moderna para jogos, renderização de gráficos em tempo real e visualização de dados. No TypeScript, a API do Canvas é 100% tipada através de HTMLCanvasElement e CanvasRenderingContext2D:
const canvas = document.querySelector<HTMLCanvasElement>("#painel-grafico");
if (canvas) {
// getContext("2d") retorna CanvasRenderingContext2D | null
const ctx = canvas.getContext("2d");
if (ctx) {
// Redimensionamento estrito
canvas.width = 600;
canvas.height = 300;
// Fundo do gráfico (Midnight Blue ZoneWare)
ctx.fillStyle = "#0F172A";
ctx.fillRect(0, 0, canvas.width, canvas.height);
// Barra de progresso com gradiente Emerald Green
const gradiente = ctx.createLinearGradient(50, 0, 350, 0);
gradiente.addColorStop(0, "#10B981");
gradiente.addColorStop(1, "#34D399");
ctx.fillStyle = gradiente;
ctx.roundRect(50, 100, 300, 40, 8); // Bordas arredondadas nativas
ctx.fill();
// Tipografia estrita no Canvas
ctx.font = "bold 16px Outfit, sans-serif";
ctx.fillStyle = "#FFFFFF";
ctx.fillText("Progresso da Web Academy: 82%", 50, 85);
}
}
6. Exemplo Enterprise: Widget de Métricas Interativo com DOM & Canvas
Vamos construir um componente interativo corporativo completo em TypeScript: um painel de métricas financeiras que escuta eventos de formulário, sanitiza entradas numéricas e renderiza um gráfico dinâmico em Canvas 2D:
interface MetricaItem {
mes: string;
valor: number;
}
class DashboardCanvasWidget {
private canvas: HTMLCanvasElement;
private ctx: CanvasRenderingContext2D;
private dados: MetricaItem[] = [
{ mes: "Jan", valor: 120 },
{ mes: "Fev", valor: 190 },
{ mes: "Mar", valor: 280 },
{ mes: "Abr", valor: 350 }
];
constructor(canvasId: string) {
const elemento = document.getElementById(canvasId);
if (!(elemento instanceof HTMLCanvasElement)) {
throw new Error(`Elemento #${canvasId} não é um HTMLCanvasElement válido!`);
}
const contexto = elemento.getContext("2d");
if (!contexto) {
throw new Error("Não foi possível inicializar o contexto 2D do Canvas.");
}
this.canvas = elemento;
this.ctx = contexto;
this.renderizar();
}
public adicionarMetrica(mes: string, valor: number): void {
this.dados.push({ mes, valor });
this.renderizar();
}
public renderizar(): void {
const { ctx, canvas, dados } = this;
ctx.clearRect(0, 0, canvas.width, canvas.height);
// Fundo
ctx.fillStyle = "#1E293B";
ctx.fillRect(0, 0, canvas.width, canvas.height);
const larguraBarra = 40;
const espacamento = 30;
const offsetInicial = 50;
dados.forEach((item, index) => {
const x = offsetInicial + index * (larguraBarra + espacamento);
const alturaBarra = (item.valor / 400) * (canvas.height - 80);
const y = canvas.height - alturaBarra - 40;
// Barra
ctx.fillStyle = "#10B981";
ctx.fillRect(x, y, larguraBarra, alturaBarra);
// Rótulo do Mês
ctx.font = "14px Inter, sans-serif";
ctx.fillStyle = "#94A3B8";
ctx.textAlign = "center";
ctx.fillText(item.mes, x + larguraBarra / 2, canvas.height - 15);
// Valor no topo da barra
ctx.fillStyle = "#FFFFFF";
ctx.fillText(`${item.valor}`, x + larguraBarra / 2, y - 8);
});
}
}
// Inicialização segura após o carregamento do DOM:
window.addEventListener("DOMContentLoaded", () => {
const painel = new DashboardCanvasWidget("grafico-vendas");
const form = document.querySelector<HTMLFormElement>("#form-metrica");
const inputMes = document.querySelector<HTMLInputElement>("#input-mes");
const inputValor = document.querySelector<HTMLInputElement>("#input-valor");
if (form && inputMes && inputValor) {
form.addEventListener("submit", (e: SubmitEvent) => {
e.preventDefault();
const valorNumerico = parseFloat(inputValor.value);
if (inputMes.value && !isNaN(valorNumerico)) {
painel.adicionarMetrica(inputMes.value, valorNumerico);
inputMes.value = "";
inputValor.value = "";
}
});
}
});
7. Armadilhas Comuns e Boas Práticas Sênior
- Evite Asserções Cegas com
!eas: Utilizardocument.getElementById("x")! as HTMLInputElementmascara potenciais erros de execução se o elemento não for renderizado ou se o script carregar antes do HTML. Prefira sempreinstanceofou guard clauses. - QuerySelector com Generics: O método
document.querySelector<HTMLButtonElement>(".btn")é mais legível e idiomático do que fazer cast posterior comas HTMLButtonElement. - Cuidado ao Usar innerHTML: Atribuir
elemento.innerHTML = dadosNaoSanitizadospode introduzir vulnerabilidades críticas de XSS (Cross-Site Scripting). Prefira manipular texto comtextContentou criar elementos de forma declarativa comcreateElement().
Resumo da Lição 41
- A biblioteca DOM do TypeScript modela toda a especificação oficial de Web APIs do navegador.
- A hierarquia do DOM segue:
EventTarget→Node→Element→HTMLElement→ subtipos específicos. - Seletores de elementos retornam tipos que incluem
null, exigindo checagem defensiva de nulidade. - O operador
instanceofrealiza validação segura em runtime combinada com afunilamento de tipos (narrowing) em tempo de compilação. - Eventos (
MouseEvent,KeyboardEvent,SubmitEvent) e contextos gráficos de Canvas 2D são rigorosamente tipados.
📝 Exercício Prático Desafiador da Lição 41
1. Crie uma função configurarContadorCliques(botaoId: string, displayId: string): void que capture um botão e um elemento de texto por ID utilizando instanceof e afunilamento defensivo.
2. Ao clicar no botão, incremente um contador numérico interno e atualize o texto na tela, disparando uma mudança de cor no estilo caso o valor ultrapasse 10.
3. Adicione um listener de teclado para que a tecla “R” (reset) zere o contador para zero.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE