Ferramentas de desenvolvedor · Codificador e decodificador Base64
Por que btoa() ativa emoji e como codificar UTF-8 em Base64 em JavaScript
· Como funciona
base64 Unicode codificação
btoa() só aceita caracteres até U+00FF, portanto texto acentuado, CJK e lançamento de emoji. Esta postagem mostra o que a função realmente espera e como o TextEncoder fornece uma string Base64 UTF-8 correta.
Por que o btoa pode usar Unicode - e codificar incorretamente um sotaque silenciosamente
Chamar btoa("😀") gera InvalidCharacterError porque o emoji não cabe em uma única unidade de código de tamanho de byte. Um erro mais sutil é btoa("é"): o é pré-composto é U+00E9, abaixo de 256, então btoa aceita, mas codifica Latin-1 byte E9, não UTF-8 bytes C3 A9. O mesmo acento visível escrito como e mais uma marca de combinação pode ocorrer porque a marca está fora do intervalo aceito. A abreviação da pasta de trabalho “um sotaque lança” precisa desta qualificação: uma string pode falhar ruidosamente ou produzir silenciosamente os bytes errados.
O que btoa() realmente codifica: uma string binária de unidades de código 0–255 — por que a função foi projetada em torno de Latin-1 bytes em vez de texto Unicode
btoa consome uma “string binária”: cada unidade de código de caractere JavaScript deve estar no intervalo 0–255 e representa um byte. Ele não entende codificação, linguagem ou normalização de texto Unicode. Um emoji astral é representado por duas unidades de código substituto UTF-16, ambas muito maiores que 255, portanto, enviar a string bruta JavaScript diretamente não funciona. Trate a saída como uma codificação de bytes, não de caracteres abstratos.
UTF-8 primeiro, Base64 depois - por que o texto deve se tornar bytes antes de qualquer alfabeto Base64 ser aplicado
TextEncoder transforma uma string JavaScript em sua sequência de bytes UTF-8 primeiro. Em seguida, transforme cada byte em um caractere de string binária e passe essa string binária para btoa ou use outro API que aceite bytes diretamente. Para decodificação, atob retorna a string binária; recupere seus valores de bytes e forneça-os a TextDecoder("utf-8"). ToolAcre usa um decodificador estrito que recusa UTF-8 malformado em vez de inserir caracteres de substituição silenciosamente.
Exemplo resolvido: codificação de 'café 😀' com TextEncoder e btoa — a sequência de bytes, a string binária intermediária e a saída final
Para o texto literal café 😀, os bytes UTF-8 são 63 61 66 C3 A9 20 F0 9F 98 80 em hexadecimal: ASCII c-a-f, dois bytes para é, um espaço e quatro bytes para o emoji. Base64 desses dez bytes é Y2Fmw6kg8J+YgA==. O preenchimento e o alfabeto descrevem apenas os bytes; eles não rotulam o idioma. Compare uma falha direta de btoa("café 😀") com o modo UTF-8 de ToolAcre, decodifique seu resultado e verifique se o mesmo sotaque visível e emoji sobrevivem.
O velho truque unescape(encodeURIComponent()) e por que é um hack — o que ele faz nos bastidores e por que é desencorajado
Uma solução alternativa histórica é btoa(unescape(encodeURIComponent(text))). encodeURIComponent codifica percentualmente UTF-8 e unescape reempacota trigêmeos percentuais como unidades de código único, mas unescape está obsoleto, difícil de ler e estranho em torno de substitutos solitários malformados. Faz com que uma conversão pareça um processamento de URL mesmo quando não existe URL. TextEncoder indica claramente o limite pretendido: o texto se torna bytes uma vez e o Base64 opera somente depois disso.
Decodificação do outro lado – emparelhando atob com TextDecoder para que a viagem de ida e volta seja sem perdas
Depois de atob, não chame decodeURIComponent em bytes binários arbitrários e espere que eles se tornem texto. Converta códigos de caracteres em Uint8Array e passe-os pelo TextDecoder. No exemplo do café 😀, o resultado é a sequência UTF-8 original de dez bytes e, em seguida, a string original. Se o Base64 for decodificado em bytes de imagem ou arquivo compactado, ele pode não representar texto UTF-8 válido; ToolAcre relata que, em vez de fingir que dados binários são prosa legível.
O que isso não cobre – codificação de arquivos e blobs binários, variantes base64url e streaming de grandes entradas
Esta explicação diz respeito ao texto codificado como UTF-8. Arquivo e Blob Base64, Base64url para segmentos JWT e codificação incremental de dados de vários gigabytes têm diferentes interfaces ou necessidades de memória. Base64 também não criptografa um token: qualquer pessoa que o possua pode decodificar os bytes. O decodificador pode aceitar preenchimentos ausentes e espaços em branco comuns, mas a interoperabilidade ainda depende de saber se a carga útil é texto ou dados binários arbitrários.
Conclusão: codifique bytes, não strings, e verifique o percurso de ida e volta - como o codificador e decodificador Base64 executa a etapa UTF-8 para você, para que acentos, CJK e emoji sobrevivam
Codifique bytes, não strings JavaScript brutas e verifique o percurso de ida e volta. O codificador e decodificador Base64 executa as etapas TextEncoder e TextDecoder para você enquanto mantém o texto colado no navegador. RFC 4648 especifica o alfabeto e o preenchimento; UTF-8 fornece o contrato separado de caractere para byte. A mistura dessas duas camadas é a raiz do InvalidCharacterError e da corrupção silenciosa do Latin-1.