# Blocos de código — destaque, cópia, escape
## Qual biblioteca
| | Peso (comprimido, com 1 gramática) | Escolha quando |
|---|---|---|
| **highlight.js** ✅ padrão | ~15,6 KiB | É o default desta skill. Uma tag `
```
```js
document.querySelectorAll('code[data-from]').forEach((c) => {
c.textContent = document.getElementById(c.dataset.from).textContent.trim();
});
// rode ANTES de hljs.highlightAll()
```
A única sequência que ainda quebra é `` **todo** caractere conta. Isto sai com uma linha em branco no topo e indentação
falsa em cada linha:
```html
const x = 1;
```
O certo é colar tudo, sem indentar pelo HTML — feio no fonte, correto na tela:
```html
const x = 1;
```
Para blocos de várias linhas, comece o conteúdo logo depois do `>` e termine logo antes do ``.
(HTML descarta *uma* quebra de linha imediatamente após `
`, mas não depois de `` — não
conte com isso.)
## Botão de copiar
Está no runtime do `template.html`. O que cada pedaço evita:
```js
if (navigator.clipboard && window.isSecureContext) { … }
```
**Testar `navigator.clipboard` antes de usar é obrigatório.** Fora de contexto seguro o objeto é
`undefined`, e `navigator.clipboard.writeText(t)` estoura `TypeError` — exceção síncrona, que
`.catch()` de promise não pega.
Vale a pena saber exatamente onde isso acontece, porque quase todo tutorial erra:
| Origem | Contexto seguro? |
|---|---|
| `https://…` | sim |
| `http://localhost`, `http://127.0.0.1`, `http://*.localhost` | **sim** — são tratadas como confiáveis mesmo sem TLS |
| `file:///home/voce/doc.html` | **sim** no Chromium (`isSecureContext === true`, verificado) |
| `http://192.168.0.10/doc.html` | **não** — é aqui que a API some |
Ou seja: o modo de falha real é o documento servido por HTTP simples num IP de rede — mandar o
arquivo para o time por um `python -m http.server` na sua máquina. Mesmo onde a API existe, a
escrita ainda pode ser recusada em runtime — daí o segundo nível:
```js
navigator.clipboard.writeText(text).then(ok, () => legacyCopy(text));
```
A promise rejeita quando o documento não está em foco (`DOMException: Document is not focused`) ou
a permissão é negada. O `legacyCopy` com `document.execCommand('copy')` é obsoleto, mas continua
implementado em todos os navegadores e é o único caminho que funciona nos dois casos.
```js
ta.style.cssText = 'position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;';
ta.select();
ta.setSelectionRange(0, ta.value.length); // iOS ignora select() sozinho
```
`position: fixed` (não `absolute`) impede que a página role até o textarea invisível.
`execCommand` só funciona **dentro do handler de um gesto do usuário** — chamar de um `setTimeout`
não copia nada.
E o mais silencioso de todos: **capture o texto antes de destacar.**
```js
const sources = new WeakMap();
document.querySelectorAll('pre > code').forEach((c) => sources.set(c, c.textContent.replace(/\n$/, '')));
hljs.highlightAll(); // só depois
```
Depois do highlight, `textContent` ainda devolve o texto certo — mas com plugin de número de linha
o DOM ganha os números e a pessoa cola `1 const x = 1;`. Capturar antes é a única versão que nunca
mente.
### Plugins prontos
`highlightjs-copy` faz isso pelo highlight.js, com i18n e aviso a leitor de tela — **mas copia só
pela Clipboard API**. Conferido no fonte da 1.0.6: uma referência a `navigator.clipboard`, e zero a
`execCommand`, `isSecureContext` ou `catch`. Fora de contexto seguro ele estoura `TypeError`, e uma
recusa em runtime vira rejeição não tratada: o botão não dá sinal nenhum e o usuário acha que copiou.
Prefira o botão do template, ou aceite que este falha em silêncio.
```html
```
No Prism, o botão exige **toolbar + copy-to-clipboard, nessa ordem** — o plugin de cópia se registra
na toolbar e não faz nada se ela ainda não existir. São três tags, não uma:
```html
```
Ele não tem objeto de configuração: os rótulos vêm de `data-*`, e o plugin sobe a árvore procurando
— então **uma declaração no `` traduz a página inteira**:
```html
```
Nos dois casos o botão sai com o CSS deles, não com o do Bootstrap. Se importa que o botão pareça
parte do documento, fique com o do template.
## Receitas
**Nome do arquivo em cima do bloco** — dá contexto sem uma frase inteira:
```html
src/server/auth.tsTypeScript
…
```
**Bloco longo com rolagem** — em vez de 200 linhas empurrando a aba:
```html
…
```
**Diff** — o highlight.js entende `language-diff` e colore `+`/`-` sozinho:
```html
- const a = 1;
+ const a = 2;
```
**Terminal** — comando e saída juntos, sem inventar cor de linguagem:
```html
$ npm run build
built in 1.2s
```
(É o único caso em que HTML dentro de `` é intencional. `nohighlight` impede o highlight.js de
reescrever o bloco e apagar o ``.)
**Destacar uma linha sem plugin** — `` funciona e o highlight.js não a remove se você marcar
depois; mais simples é um comentário `// ← aqui` na própria linha. Precisando muito disso, é o caso
de trocar para Prism com `line-highlight`.
**Código inserido depois do load** (você gerou HTML por JS): `hljs.highlightAll()` só varre o que
existia. Para um bloco novo:
```js
hljs.highlightElement(novoCode);
```
Depois de destacar, o highlight.js grava `data-highlighted="yes"` no elemento. Da versão 11.9.0 em
diante ele usa essa marca para **sair na hora** se você chamar `highlightElement` de novo no mesmo
bloco — sem duplicar ``, só um aviso no console. Ainda assim, filtre por
`:not([data-highlighted])` ao varrer: o aviso polui e some o sinal dos erros que importam.