JavaScript URL API

Introduzione agli oggetti URL in JavaScript

JavaScript mette a disposizione una potente interfaccia URL integrata per costruire, analizzare e manipolare URL. Invece di tagliare stringhe con espressioni regolari o chiamate manuali a split() — che si rompono su casi limite come porte, caratteri codificati e componenti mancanti — l'oggetto URL analizza un indirizzo nelle sue parti strutturate e indirizzabili singolarmente.

L'interfaccia URL è disponibile nativamente nei browser e in Node.js (è un globale, non è necessario require). Questa guida illustra come creare e analizzare URL, leggere e modificare ciascun componente, lavorare con le query string tramite URLSearchParams e gestire attività comuni del mondo reale come la costruzione di richieste API e il tracciamento dei link.

Creare e analizzare URL con JavaScript

Creazione di base di una URL

Per creare una URL, passa la stringa dell'indirizzo al costruttore URL. Se la stringa non è una URL assoluta valida, il costruttore lancia un TypeError:

const url = new URL("https://www.w3docs.com");

Analisi dei componenti di una URL

Una volta creato un oggetto URL, puoi leggere qualsiasi sua parte tramite una proprietà dedicata:

L'insieme completo dei componenti per una URL come https://user:[email protected]:8080/path?q=1#top è:

Validare una URL prima dell'analisi

Poiché il costruttore lancia un'eccezione su input non validi, valida prima le stringhe non attendibili. Il metodo statico URL.canParse() restituisce un boolean senza lanciare eccezioni:

Manipolazione degli oggetti URL

Lavorare con la query string tramite URLSearchParams

Ogni URL espone una proprietà searchParams — un object URLSearchParams live le cui modifiche vengono scritte direttamente sulla URL. Questo è il metodo preferito per modificare una query string, perché gestisce la codifica automaticamente. L'esempio seguente utilizza un URLSearchParams separato per mostrare come i pezzi si incastrano:

In pratica di solito si salta l'object intermedio e si modifica url.searchParams direttamente — questo muta la URL in loco:

Chiavi ripetute e iterazione

Le query string possono contenere la stessa chiave più di una volta (ad esempio ?tag=js&tag=web). get() restituisce solo il primo valore, mentre getAll() restituisce tutti i valori. È anche possibile iterare su tutte le coppie con for...of:

Spiegazione

• Inizializzazione:
  • L'object URL viene creato con una URL base che include già un parametro di query (initial=123).
• Object URLSearchParams:
  • URLSearchParams viene inizializzato con url.search, che contiene la query string dalla URL.
• Aggiungere un parametro:
  • Il metodo .set() viene utilizzato per aggiungere un nuovo parametro (key=value) alla query string. Se la chiave esiste già, il suo valore viene aggiornato; in caso contrario, la coppia chiave-valore viene aggiunta.
• Leggere un parametro:
  • Il metodo .get() recupera il valore del parametro specificato dalla chiave (key), che viene poi registrato nella console.
• Rimuovere un parametro:
  • Il metodo .delete() rimuove il parametro specificato dalla chiave (initial). Questo serve a dimostrare come rimuovere un parametro dalla query string.
• Aggiornare la ricerca URL:
  • Dopo aver modificato i parametri, la proprietà search della URL viene aggiornata con la rappresentazione string dell'object URLSearchParams.
• Output:
  • Infine, la URL modificata viene registrata nella console, mostrando l'effetto delle operazioni.

Modifica del percorso e dell'hash

Ecco uno snippet JavaScript che mostra come modificare il pathname e l'hash di una URL:

Spiegazione

• Inizializzazione dell'object URL:
  • L'object URL viene inizialmente creato da una stringa che rappresenta una URL completa. Questa URL include un pathname, una query string e un frammento hash.
• Modifica del pathname:
  • La proprietà pathname dell'object URL viene impostata su un nuovo percorso (/path/to/resource). Questa proprietà specifica il percorso o la route sul server.
• Modifica dell'hash:
  • La proprietà hash viene aggiornata a "section". Nelle URL, l'hash rappresenta un segnalibro all'interno della pagina, spesso usato per scorrere fino a una sezione specifica.
• Registrazione delle modifiche:
  • La URL originale viene registrata prima delle modifiche per mostrare lo stato iniziale.
  • Dopo le modifiche, viene registrato il nuovo stato della URL per dimostrare gli effetti della modifica di pathname e hash.

Utilizzo avanzato degli oggetti URL

Gestione delle URL relative

L'object URL può anche risolvere URL relative rispetto a una URL base, il che è particolarmente utile per le applicazioni web che gestiscono link dinamici:

Lavorare con la codifica URL

Quando si gestiscono URL che includono caratteri che richiedono la codifica, l'object URL le gestisce automaticamente, garantendo la validità delle URL:

Per la gestione di file locali o blob, URL.createObjectURL() genera una string URL temporanea che fa riferimento all'object in memoria, utile per visualizzare in anteprima immagini o scaricare file direttamente da JavaScript.

Esempi pratici di manipolazione URL

Tracciamento delle URL di campagna

Puoi usare gli oggetti URL per gestire efficacemente le URL di campagna, spesso utilizzate nel marketing digitale per monitorare le prestazioni delle varie iniziative di marketing:

Integrazione con le Web API

Gli oggetti URL si abbinano naturalmente alla Fetch API: puoi passare un'istanza URL direttamente a fetch(), e searchParams garantisce che la query string sia correttamente codificata. Dopo che la richiesta viene risolta, in genere si analizza la risposta con i metodi JSON:

Alternativa moderna (async/await):

async function fetchPosts() {
  const apiUrl = new URL("https://jsonplaceholder.typicode.com/posts");
  apiUrl.searchParams.set("userId", "1");
  const response = await fetch(apiUrl);
  const data = await response.json();
  console.log(data[0]); // Outputs the first post by user with userId 1
}

Errori comuni

• Il costruttore lancia un'eccezione su input non valido. new URL("example.com") fallisce perché non ha un protocollo. Fornisci una URL assoluta completa, passa una URL base come secondo argomento, oppure proteggi con URL.canParse().
• Le stringhe relative richiedono una base. new URL("/about") lancia un'eccezione da sola; new URL("/about", "https://www.w3docs.com") risolve correttamente.
• origin è in sola lettura. Non è possibile assegnare a url.origin. Modifica invece protocol, hostname o port singolarmente.
• get() restituisce solo il primo valore. Per le chiavi che possono ripetersi, usa getAll().
• La normalizzazione è automatica. Leggere href può aggiungere uno slash finale (https://w3docs.com diventa https://w3docs.com/) e codificare in percentuale i caratteri riservati. Confronta URL analizzate, non stringhe grezze, quando si verifica l'uguaglianza.
• L'ordine di searchParams è l'ordine di inserimento. Usa params.sort() se hai bisogno di una query string canonica e stabile per la cache o la firma.

Conclusione

L'oggetto URL di JavaScript è uno strumento robusto per gestire tutti gli aspetti della manipolazione e dell'analisi delle URL. Padroneggiando le sue proprietà e i suoi metodi, gli sviluppatori possono semplificare l'interazione della loro applicazione web con le URL, migliorando sia la funzionalità che l'esperienza utente. Che tu stia gestendo strutture URL complesse, integrandoti con API, o tracciando campagne di marketing, l'oggetto URL offre un modo affidabile ed efficiente per lavorare con gli indirizzi web in JavaScript.

Pratica