APIs no navegador

Trabalhe numa cópia da pasta inicio/ desta etapa. Ela já abre ou executa com as instruções do README. Leia o código, mude uma coisa e anote sua previsão antes de recarregar. Compare com a referência na pasta da etapa. Se nada mudar, confira a extensão do arquivo, o arquivo salvo e o caminho aberto. Blocos adicionais do capítulo são experiências separadas; a pasta de referência contém o programa completo desta etapa.

A Biblioteca da Ribeira, acervo comunitário fictício no bairro da Ribeira, Recife, precisa de um rascunho da hora do conto. O texto não vai para a internet. Ele fica neste navegador, neste computador.

O exemplo está em exemplos/21-apis-no-navegador/. Abra index.html. O ciclo: ler, copiar, mudar uma coisa, prever, recarregar, conferir.

O que você vai aprender

• O que é uma API da Web no navegador.
• Guardar texto com localStorage em nota.js.
• Entender canvas como API de desenho, sem repetir o capítulo 20.
• Estudar sem conta paga e sem serviço externo obrigatório.

O que é uma API no navegador

API, aqui, é um conjunto de objetos e funções que o navegador já oferece. Você não baixa um pacote. document, localStorage e canvas são APIs da Web.

Elas falam com a página, o disco local do navegador ou o pincel. Não são um servidor distante.

localStorage na Ribeira

localStorage guarda texto no perfil deste navegador. Sobrevive ao recarregar. Não substitui um banco. Não é cadastro.

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bloco de rascunho</title>
  </head>
  <body>
    <h1>Rascunho da hora do conto</h1>
    <label for="nota">Texto</label><br>
    <textarea id="nota" rows="6" cols="40"></textarea><br>
    <button type="button" id="salvar">Salvar neste navegador</button>
    <p id="aviso" role="status"></p>
    <script src="nota.js"></script>
  </body>
</html>

const campo = document.getElementById("nota");
campo.value = localStorage.getItem("ribeira-nota") || "";
document.getElementById("salvar").addEventListener("click", function () {
  localStorage.setItem("ribeira-nota", campo.value);
  document.getElementById("aviso").textContent = "Guardado neste navegador.";
});

Escreva uma frase fictícia. Clique em salvar. Recarregue. Preveja: o texto volta. Confira.

A chave ribeira-nota é só um nome. Outro site, outra origem. Outro navegador, outra gaveta.

Canvas, só a ideia

canvas é a API de desenho usada no capítulo 20. getContext("2d") pinta círculos, retângulos, texto. Não guarda o rascunho da hora do conto. Cada API resolve um problema.

Não copie de novo o pátio de bolas. Basta saber: desenho vai no canvas; texto persistente vai no localStorage.

Outras APIs, sem conta

O navegador também oferece áudio, vídeo, geolocalização e notificações. Nenhuma é obrigatória nesta pasta. Nenhuma pede cartão.

API de terceiro (mapa, clima, rede social) vive noutro servidor. Quase sempre pede chave. A Ribeira deste volume não chama nenhuma.

O rascunho usa só o que já está no navegador. Sem chave. Sem publicação. Sem dado real de leitor.

Erro comum: achar que localStorage envia o texto para um servidor. Não envia. É este navegador, nesta máquina. Limpar os dados do site apaga o rascunho.

Outro erro: getElementById("nota") antes do textarea no HTML. O script roda, o campo ainda não existe, campo fica null.

Arquivo no disco é nota.js. A janela mostra o campo. Teste em 127.0.0.1 se quiser HTTP local. Nada disso é o site público da biblioteca.

A origem conta: file://, http://127.0.0.1:8765 e um site publicado são gavetas diferentes. O rascunho de uma não aparece na outra.

Atividades

1. O que localStorage.setItem guarda e o que ele não guarda?
2. Por que o campo tem label com for="nota" igual ao id do textarea?
3. Qual a diferença entre a API localStorage e uma API paga de mapa?

Respostas comentadas

1. Guarda um texto associado a uma chave neste origem/navegador. Não guarda arquivo no disco da pasta do volume e não envia a outro computador.
2. O leitor de tela e o clique no rótulo encontram o campo. Sem o par, o textarea fica solto.
3. localStorage já vem no navegador, sem conta. API de mapa costuma exigir chave, rede e, muitas vezes, pagamento. Aqui não é obrigatória.

O arquivo completo

Referência do exemplo 21-apis-no-navegador, reproduzida aqui para que você possa conferir sem sair da página.

index.html

<!DOCTYPE html>

<html lang="pt-BR">
<head>
<meta charset="utf-8"/>
<meta content="width=device-width, initial-scale=1" name="viewport"/>
<title>Bloco de rascunho</title>
<style>
/* Apoio de leitura, teclado e tela estreita. */
img{max-width:100%;height:auto} html {overflow-wrap:anywhere} main {min-width:0} input,textarea,select,canvas {max-width:100%;box-sizing:border-box} fieldset {min-width:0}
pre {max-width:100%;overflow:auto} :focus-visible {outline:3px solid #0f3d3e;outline-offset:3px}
.skip {position:absolute;top:-5rem;left:1rem;background:#0f3d3e;color:white;padding:.5rem;z-index:9}.skip:focus {top:.5rem}
table {max-width:100%} td,th {overflow-wrap:anywhere}
@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}}
</style></head>
<body><a class="skip" href="#conteudo">Pular para o conteúdo</a><main id="conteudo" tabindex="-1">
<h1>Rascunho da hora do conto</h1>
<label for="nota">Texto</label><br/>
<textarea cols="40" id="nota" rows="6"></textarea><br/>
<button id="salvar" type="button">Salvar neste navegador</button>
<p id="aviso" role="status"></p>

</main><script src="nota.js"></script></body>
</html>

nota.js

const campo = document.getElementById("nota");
campo.value = localStorage.getItem("ribeira-nota") || "";
document.getElementById("salvar").addEventListener("click", function () {
  localStorage.setItem("ribeira-nota", campo.value);
  document.getElementById("aviso").textContent = "Guardado neste navegador.";
});