URL e URLSearchParams in JavaScript: guida pratica

Smetti di analizzare gli URL con trucchi sulle stringhe

Prima che esistesse l'API URL, gli URL si spezzettavano con split('?'), regex e tanta speranza. Funzionava quasi sempre, finché un valore non conteneva un &, un =, uno spazio o un carattere non ASCII, e a quel punto non funzionava più. Sia il browser sia Node includono un vero parser. Usalo.

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

Una sola chiamata, e ogni parte dell'URL è già separata e decodificata correttamente. Il costruttore lancia un TypeError sugli input non validi, e di solito è proprio quello che vuoi: un URL senza senso deve fallire in modo evidente, invece di produrre in silenzio dati senza senso più avanti.

Leggere i parametri della query

Ogni URL ha una proprietà .searchParams: un oggetto URLSearchParams che sa leggere e scrivere la query string:

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

Alcune cose da notare:

• I valori arrivano già decodificati. ?name=Ada%20Lovelace ti restituisce "Ada Lovelace".
• Tutto è una stringa. "2" non è 2. Converti con Number() se ti serve un numero.
• Le chiavi ripetute sono ammesse. get restituisce la prima corrispondenza; getAll le restituisce tutte.
• Le chiavi mancanti restituiscono null, non undefined, quindi ?? "default" funziona bene con loro.

Costruire una query string

Puoi costruire una query string da zero con URLSearchParams, senza escape manuali e senza unire pezzi con &:

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

Oppure creala a partire da un oggetto: va bene qualsiasi iterabile di coppie [chiave, valore], e anche un semplice oggetto:

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set e append: set sostituisce qualsiasi valore esistente per quella chiave. append ne aggiunge un altro. Usa append quando una chiave può ripetersi legittimamente (tag, filtri); usa set per i parametri a valore singolo.

Modificare un URL

Dato che URL è un oggetto vivo, modificare searchParams aggiorna automaticamente .search e .href:

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // overwrites
u.searchParams.delete("utm_source");       // no-op if absent

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

È il modo idiomatico per aggiungere un parametro a un URL esistente. Nessun controllo del tipo "l'URL ha già un ?", nessun dubbio se anteporre & o ?.

Allo stesso modo puoi cambiare le altre parti dell'URL:

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

Scorrere i parametri

URLSearchParams è iterabile. for...of ti dà coppie [chiave, valore], e ci sono i soliti helper keys(), values() ed entries():

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

Nota che le chiavi ripetute compaiono più volte: vedrai tag = web e poi tag = beginner come voci separate. È fedele alla query string reale.

Se vuoi un semplice oggetto per una stampa di debug veloce, Object.fromEntries funziona, ma accorpa le ripetizioni tenendo solo l'ultimo valore:

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

Va bene per il debug. È sbagliato se una chiave può ripetersi.

Gli URL relativi hanno bisogno di una base

new URL("/search?q=js") da solo lancia un errore: un percorso relativo non è un URL valido di per sé. Passa una base come secondo argomento:

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

Le regole di risoluzione sono le stesse che i browser usano per <a href>: una / iniziale è assoluta rispetto all'host, senza barra è relativa al percorso corrente, .. risale di un livello. Molto comodo quando componi URL di API a partire da una base configurata.

Nel browser, window.location.href è una base già pronta per analizzare l'URL della pagina corrente:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Gestire gli URL non validi

Il costruttore URL lancia un errore sugli input malformati. È utile, ma significa che ti serve try/catch quando analizzi qualcosa digitato dall'utente o inviato da un sistema esterno:

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL object
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

Gli ambienti moderni espongono anche URL.canParse(input): un controllo booleano che ti evita il giro di try/catch quando vuoi solo validare:

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

Un piccolo esempio completo

Mettiamo tutto insieme: leggi i filtri correnti da un URL, modificali e produci un nuovo URL verso cui navigare:

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

Passare null elimina il parametro. Qualsiasi altro valore lo imposta o lo sovrascrive. È uno schema che finirai per scrivere in una forma o nell'altra ogni volta che costruisci interfacce con filtri, paginazione o deep link.

Cosa portarsi a casa

• new URL(string) analizza un URL e lo divide in parti con un nome. Lancia un errore se l'input non ha senso.
• url.searchParams è un URLSearchParams: usa get, getAll, set, append, delete, has.
• La codifica avviene da sola. Non ricorrere a encodeURIComponent a meno che tu non stia costruendo stringhe a mano.
• Passa un URL base come secondo argomento per risolvere i percorsi relativi.
• URL.canParse (oppure try/catch) è il tuo strumento di validazione per gli input non affidabili.

Ogni volta che ti viene la tentazione di spezzare un URL con .split('?') o di estrarre un parametro della query con una regex, usa invece queste API. Sono più brevi, corrette e già incluse nel runtime.