Ferramentas de desenvolvedor · Codificador e decodificador URL
O que o construtor URL codifica para você: os conjuntos de codificação percentual do navegador
· Como funciona
codificação de URL javascript o que é isso APIs da web
O URL API codifica silenciosamente alguns caracteres por cento e deixa outros em paz, dependendo de qual parte do URL eles pousam. Esta postagem explica os conjuntos de codificação WHATWG e como prever a saída.
O espaço que se tornou %20 e o | isso permaneceu — um caso concreto onde new URL() codificou parcialmente um caminho
Quando o novo URL("https://example.com/hello mundo") é executado, o espaço se torna %20 silenciosamente. Mas new URL("https://example.com/hello|world") deixa o canal intocado. Essa diferença não é aleatória. O padrão WHATWG URL define conjuntos de caracteres separados para codificar para cada componente URL: caminho, consulta, fragmento e informações do usuário, cada um com suas próprias regras. Compreender esses conjuntos significa prever o que o construtor fará.
O espaço precisa de codificação percentual porque não é seguro em HTTP e prejudica a legibilidade. O pipe é diferente: não é um caractere reservado que divide a estrutura, então o navegador o deixa como está. A linha entre segurança e legibilidade é traçada por WHATWG, não por suposições. O teste de "olá mundo" mostra a codificação; testar "hello|world" revela os limites de cada parte URL.
Um URL, vários conjuntos de codificação — caminho, consulta, fragmento e informações do usuário, cada um com sua própria lista de caracteres para escapar
Um URL contém várias regiões, cada uma com suas próprias regras de codificação. O caminho segue um conjunto, consulta outro, fragmenta um terceiro, userinfo um quarto. Um espaço torna-se %20 no caminho e na consulta. Um sinal de igual permanece na consulta, onde separa chaves e valores, mas encodeURIComponent o transforma em% 3D. O construtor URL conhece seu contexto e aplica as regras corretas para cada parte.
Os conjuntos de codificação são precisos e pequenos. Path tem sua própria lista de personagens; consulta tem uma lista semelhante, mas diferente. Isso reflete quais personagens têm significado estrutural. Uma barra divide segmentos de caminho, então encodeURIComponent codifica-o como %2F. No fragmento, uma barra pode existir sem quebrar nada. Compreender as regras WHATWG significa prever a saída sem executar o código.
Por que a codificação percentual é unidirecional: o que permanece codificado permanece assim
O construtor URL executa normalização unidirecional. Passe "%20" para o novo URL e ele produzirá %20 inalterado. O construtor o reconhece como já codificado e o deixa como está. É por isso que a codificação dupla é importante: codifique uma vez, passe pelo construtor e a codificação permanece. O construtor não decodifica, reinterpreta e recodifica; ele lê adiante.
Esta propriedade unidirecional afeta aplicativos que confiam em URL.href como canônico. Se você concatenar a entrada do usuário com o seu caminho, a entrada será normalizada, mas não decodificada. Um valor como "meu+arquivo" permanece como está ou se torna "meu%2Barquivo" em alguns contextos. O código posterior usando decodeURIComponent pode ser lido como espaço se for proveniente de dados de formulário. O construtor normaliza uma vez; depois disso, seu valor é fixo.
Exemplo resolvido: passando a mesma string confusa por new URL() e lendo href, pathname e searchParams — três visualizações diferentes
Pegue "hello world&foo=bar|test#anchor" e coloque-o no novo URL com componentes diferentes. O espaço se torna %20 em todos os lugares. O e comercial no caminho permanece (sem significado estrutural), mas na consulta também permanece (separa parâmetros, portanto a normalização perderia o limite entre "q =" e "foo = bar"). O pipe e o hash se comportam de maneira diferente por local.
Ler href, pathname e searchParams mostra três visualizações diferentes. pathname mostra o caminho codificado sem esquema, host ou consulta. searchParams fornece parâmetros decodificados, então "hello+world" dos dados do formulário se torna um espaço. A propriedade search preserva a string literal. href mostra o URL normalizado completo. Estes coexistem em um objeto; qual usar depende da sua próxima etapa.
URLSearchParams e a regra de codificação de formulário — por que produz + para espaços enquanto o nome do caminho produz %20
URLSearchParams aplica codificação de formulário: o espaço torna-se mais, não %20. new URLSearchParams({q: "hello world"}) produz "q=hello+world", não "q=hello%20world". Esta é a regra histórica do aplicativo/x-www-form-urlencoded. Mas se você passar essa string como consulta bruta para o novo URL, o sinal de mais permanecerá mais; apenas URLSearchParams o decodifica como espaço. O construtor é fiel ao que vê.
Essa diferença de sinal de mais causa bugs comuns. Um URL da barra de endereço usa %20 para espaços. Os dados do formulário usam plus. Se você decodificar com decodeURIComponent (que lê mais literalmente) em vez de URLSearchParams.get, os espaços se tornarão caracteres de mais. O codificador e decodificador URL mostra ambos: cole "hello+world" e compare os modos de componente e formulário para ver onde o espaço aparece.
Comparando com encodeURI — onde os dois concordam e onde divergem
O construtor URL e encodeURIComponent são ferramentas diferentes. encodeURIComponent codifica quase tudo, exceto letras, dígitos e - _ não reservados. ! ~ * ' ( ). Não assume nenhum contexto. O construtor URL analisa um URL real e aplica regras WHATWG por componente. encodeURIComponent transforma "hello/world" em "hello%2Fworld"; new URL vê barras como separadores de caminho. Mesma entrada, saída diferente.
Use encodeURIComponent ao construir um URL concatenando peças. Use URLSearchParams ou o construtor URL para URLs completos ou parciais. Não use encodeURIComponent em um URL inteiro; você destruirá o esquema. Compare o resultado com a intenção. O navegador impõe opiniões de estrutura URL e o novo URL as implementa. O codificador e decodificador URL mostra ambas as visualizações lado a lado.
O que isso não cobre — análise de host, IDNA e esquemas especiais versus não especiais
O padrão WHATWG URL é a fonte da verdade, embora sua leitura exija paciência. Os conjuntos de codificação são definidos em fragmentos de algoritmos, não em listas simples. Na prática, compreender o princípio é mais importante do que memorizar conjuntos. O caminho permite mais caracteres (as barras são estruturais); a consulta possui regras próprias; o fragmento tem menos restrições (tratado no lado do cliente, nunca enviado aos servidores). Cada componente possui suas próprias regras; saber disso lhe diz onde procurar.
Normalização e validação são limites diferentes. O construtor normaliza: limpa a codificação percentual, aplica regras de componentes, fornece forma canônica. Não valida: caracteres inválidos são lançados, mas hosts vazios são aceitos. O construtor é rigoroso quanto ao formato, mas tolerante quanto à interpretação. Para conformidade exata com as especificações, leia a seção de bytes codificados por porcentagem de WHATWG. Para construção diária, use URLSearchParams, URL API e exemplos reais.
Conclusão: o analisador tem opiniões - como o codificador e decodificador URL mostra a codificação percentual simples de um valor ou endereço para que você possa compará-lo com o que o navegador produziu
Os recursos WHATWG não suportados aqui incluem análise de host com conversão IDNA (nomes de domínio internacionais para ASCII) e tratamento de esquema especial versus não especial. Arquivo: URLs usam autoridade de barra dupla; dados: URLs não. O construtor impõe essas regras. A conversão de nomes de host e a determinação de status especial pertencem à leitura de especificações, não à codificação percentual. Isso é importante ao construir URLs em diferentes esquemas.
Teste sua construção URL comparando a interpretação do navegador com as expectativas. Construa com o novo URL, leia as propriedades importantes: href para formulário completo, nome de caminho para caminho, pesquisa para consulta bruta, searchParams para decodificado. Se a saída o surpreender, cole no codificador e decodificador URL e siga a transformação passo a passo. A ferramenta mostra a saída normalizada junto com a codificação bruta, revelando a diferença. Compreender os conjuntos WHATWG significa compreender as escolhas do navegador e como trabalhar com eles.