Come decodificare un URL in JavaScript (guida completa)

decodeURIComponent() — Decodificare un componente di URI

decodeURIComponent() è la funzione principale per decodificare le stringhe codificate come URL in JavaScript. Decodifica tutte le sequenze percent-encoded, riconvertendole nei caratteri originali. Usa questa funzione quando devi decodificare i valori dei parametri di query, i segmenti del percorso o qualsiasi singolo componente di un URI.

// Decodifica di base
console.log(decodeURIComponent('hello%20world'));
// "hello world"

console.log(decodeURIComponent('price%3D10%26qty%3D2'));
// "price=10&qty=2"

// Decodifica di caratteri Unicode
console.log(decodeURIComponent('caf%C3%A9'));
// "cafe" (con accento)

console.log(decodeURIComponent('%E4%B8%AD%E6%96%87'));
// Caratteri cinesi

// Decodifica del valore di un parametro di query da un URL
const url = 'https://example.com/search?q=C%2B%2B%20%26%20Java';
const params = url.split('?')[1];
const value = params.split('=')[1];
console.log(decodeURIComponent(value));
// "C++ & Java"

decodeURIComponent() decodifica tutte le sequenze percent-encoded, comprese quelle relative ai caratteri riservati come %2F (/) e %3F (?). Questo è il comportamento corretto quando si lavora con i singoli componenti di un URI, ma può causare problemi se applicato a un URL completo.

decodeURI() — Decodificare un URI completo

decodeURI() decodifica un URI completo preservandone la struttura. A differenza di decodeURIComponent(), non decodifica le sequenze che rappresentano caratteri riservati dell'URI come %2F (/), %3F (?), %23 (#) e %26 (&).

// decodeURI preserva la struttura dell'URI
console.log(decodeURI('https://example.com/my%20page?q=hello%20world'));
// "https://example.com/my page?q=hello world"
// Gli spazi vengono decodificati, ma /, ? e = vengono preservati

// Confronto con decodeURIComponent su un URL completo
console.log(decodeURIComponent('https%3A%2F%2Fexample.com%2Fpath'));
// "https://example.com/path" - decodifica correttamente se l'intero URL era codificato

// decodeURI non decodifica le sequenze dei caratteri riservati
console.log(decodeURI('path%2Fto%2Ffile'));
// "path%2Fto%2Ffile" - %2F NON viene decodificato perché / è riservato
console.log(decodeURIComponent('path%2Fto%2Ffile'));
// "path/to/file" - %2F VIENE decodificato

Usa decodeURI() quando vuoi rendere un URL più leggibile (ad esempio per la visualizzazione) senza alterarne la struttura. Nella maggior parte dei casi d'uso programmatici, invece, vorrai usare decodeURIComponent() applicato ai singoli componenti.

Gestire gli URI malformati

Sia decodeURI() sia decodeURIComponent() sollevano un URIError quando incontrano sequenze percent-encoded non valide. Questo accade con segni di percentuale isolati, sequenze incomplete o sequenze di byte UTF-8 non valide. Quando lavori con URL forniti dall'utente o provenienti da fonti esterne, racchiudi sempre le operazioni di decodifica in un blocco try-catch.

// Questi sollevano URIError: URI malformed
try {
  decodeURIComponent('%');         // percentuale isolata
} catch (e) {
  console.error(e.message);       // "URI malformed"
}

try {
  decodeURIComponent('%2');        // sequenza incompleta
} catch (e) {
  console.error(e.message);       // "URI malformed"
}

// Funzione di decodifica sicura
function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    console.warn('Failed to decode:', str);
    return str; // restituisce la stringa originale in caso di errore
  }
}

// Corregge le sequenze di percentuale malformate prima della decodifica
function fixAndDecode(str) {
  // Sostituisce le % isolate con %25 (segno di percentuale codificato)
  const fixed = str.replace(/%(?![0-9A-Fa-f]{2})/g, '%25');
  return decodeURIComponent(fixed);
}

console.log(fixAndDecode('100% complete'));
// "100% complete"

Usare l'API URL (consigliato)

Le moderne API URL e URLSearchParams offrono un modo più sicuro e strutturato per analizzare e decodificare gli URL. Gestiscono automaticamente la codifica e la decodifica, riducendo il rischio di errori.

// Analizza un URL e accede ai suoi componenti (decodificati automaticamente)
const url = new URL('https://example.com/path%20here?q=hello%20world&lang=en');

console.log(url.pathname);  // "/path here" (decodificato)
console.log(url.search);    // "?q=hello%20world&lang=en" (grezzo)

// URLSearchParams decodifica automaticamente i valori dei parametri
console.log(url.searchParams.get('q'));     // "hello world"
console.log(url.searchParams.get('lang')); // "en"

// Itera su tutti i parametri
for (const [key, value] of url.searchParams) {
  console.log(key, '=', value);
}
// q = hello world
// lang = en

// URLSearchParams gestisce + come spazio (codifica dei form)
const formParams = new URLSearchParams('q=hello+world&lang=en');
console.log(formParams.get('q'));  // "hello world"

// Costruzione di URL con codifica automatica
const newUrl = new URL('https://example.com/search');
newUrl.searchParams.set('q', 'C++ & Java');
newUrl.searchParams.set('page', '1');
console.log(newUrl.toString());
// "https://example.com/search?q=C%2B%2B+%26+Java&page=1"

Errori comuni nella decodifica

Errore 1: decodificare un URL completo con decodeURIComponent(). Questo può compromettere la struttura dell'URL se contiene caratteri riservati codificati. Un %2F nel valore di una query diventerebbe un /, alterando potenzialmente il significato dell'URL.

Errore 2: doppia decodifica. Se una stringa è già stata decodificata una volta, decodificarla di nuovo può produrre risultati inattesi o errori. Ad esempio, la stringa %2520 viene decodificata prima in %20, poi in uno spazio. Se ti aspetti un solo livello di codifica, la doppia decodifica corrompe i dati.

// Problema della doppia decodifica
const encoded = '%2520'; // Questo è un %20 codificato
console.log(decodeURIComponent(encoded));  // "%20" (corretto - un livello)
console.log(decodeURIComponent(decodeURIComponent(encoded)));  // " " (decodificato due volte!)

// Verifica se una stringa deve essere decodificata prima di decodificarla
function needsDecoding(str) {
  return str !== decodeURIComponent(str);
}

Errore 3: non gestire il segno +. decodeURIComponent() non converte i + in spazi. Se stai decodificando dati in formato form-urlencoded, devi prima sostituire i + con degli spazi, oppure usare URLSearchParams, che se ne occupa automaticamente.

// decodeURIComponent NON decodifica + come spazio
console.log(decodeURIComponent('hello+world'));
// "hello+world" (non "hello world"!)

// Soluzione: sostituisci i + prima di decodificare
function decodeFormValue(str) {
  return decodeURIComponent(str.replace(/\+/g, ' '));
}
console.log(decodeFormValue('hello+world'));
// "hello world"

// Oppure usa URLSearchParams (gestisce i + automaticamente)
const params = new URLSearchParams('q=hello+world');
console.log(params.get('q'));
// "hello world"