URL i query string w JavaScript: URL i URLSearchParams

Przestań parsować URL sztuczkami na stringach

Zanim pojawiło się API URL, adresy cięło się przez split('?'), wyrażenia regularne i nadzieję. Zwykle działało, dopóki wartość nie zawierała &, =, spacji albo znaku spoza ASCII, a wtedy przestawało. Zarówno przeglądarka, jak i Node mają porządny parser. Korzystaj z niego.

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"

Jedno wywołanie i każda część adresu jest już rozdzielona i poprawnie zdekodowana. Przy niepoprawnych danych konstruktor rzuca TypeError, a zwykle właśnie tego chcesz: bezsensowny URL powinien głośno zawieść, zamiast po cichu produkować bzdury dalej w kodzie.

Odczyt parametrów zapytania

Każdy URL ma właściwość .searchParams, czyli obiekt URLSearchParams, który umie czytać i zapisywać 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

Kilka rzeczy, na które warto zwrócić uwagę:

• Wartości wracają już zdekodowane. ?name=Ada%20Lovelace daje "Ada Lovelace".
• Wszystko jest stringiem. "2" to nie 2. Jeśli potrzebujesz liczby, zamień przez Number().
• Powtórzone klucze są dozwolone. get zwraca pierwsze dopasowanie, getAll zwraca wszystkie.
• Brakujące klucze zwracają null, a nie undefined, więc ?? "default" dobrze z nimi działa.

Budowanie query stringa

Query string możesz zbudować od zera przez URLSearchParams, bez ręcznego escapowania i bez łączenia przez &:

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"

Albo utworzyć go z obiektu: działa dowolny iterowalny zbiór par [key, value], a także zwykły obiekt:

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

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

set a append: set zastępuje istniejącą wartość dla danego klucza, append dodaje kolejną. Używaj append, gdy klucz może się zasadnie powtarzać (tagi, filtry), a set dla parametrów o pojedynczej wartości.

Modyfikowanie URL

Ponieważ URL to żywy obiekt, zmiana searchParams automatycznie aktualizuje .search i .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"

To idiomatyczny sposób dodawania parametru zapytania do istniejącego adresu. Bez sprawdzania, czy URL ma już ?, i bez zastanawiania się, czy dokleić & czy ?.

W ten sam sposób możesz zmieniać inne części adresu:

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

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

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

Iterowanie po parametrach

URLSearchParams jest iterowalny. for...of daje pary [key, value], są też standardowe pomocniki keys(), values() i 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);
}

Zauważ, że powtórzone klucze pojawiają się wielokrotnie: zobaczysz tag = web, a potem tag = beginner jako osobne wpisy. To wiernie odpowiada faktycznemu query stringowi.

Jeśli chcesz zwykły obiekt do szybkiego wypisania przy debugowaniu, zadziała Object.fromEntries, ale scala on powtórzenia i zostawia tylko ostatnią wartość:

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" }

Do debugowania wystarczy. Źle, jeśli jakikolwiek klucz może się powtarzać.

Względne adresy potrzebują bazy

Samo new URL("/search?q=js") rzuca błąd: ścieżka względna nie jest sama w sobie poprawnym adresem URL. Przekaż bazę jako drugi argument:

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"

Reguły rozwiązywania są takie same, jakich przeglądarki używają dla <a href>: początkowy / oznacza ścieżkę bezwzględną od hosta, brak ukośnika oznacza ścieżkę względną wobec bieżącej, a .. przechodzi poziom wyżej. Bardzo wygodne, gdy składasz adresy API ze skonfigurowanej bazy.

W przeglądarce window.location.href to gotowa baza do parsowania adresu bieżącej strony:

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

Obsługa niepoprawnych adresów

Konstruktor URL rzuca błąd przy źle sformatowanych danych. To przydatne, ale oznacza, że potrzebujesz try/catch przy parsowaniu wszystkiego, co wpisał użytkownik albo przysłał zewnętrzny system:

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

Nowoczesne środowiska udostępniają też URL.canParse(input), czyli sprawdzenie zwracające boolean, które pozwala uniknąć zabawy z try/catch, gdy chcesz tylko walidować:

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

Mały działający przykład

Wszystko razem: odczytaj bieżące filtry z adresu, zmień je i utwórz nowy URL, na który można przejść:

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"

Przekazanie null usuwa parametr. Każda inna wartość go ustawia albo nadpisuje. W takiej czy innej formie napiszesz ten wzorzec za każdym razem, gdy budujesz interfejs filtrów, paginację albo deep linki.

Co warto zapamiętać

• new URL(string) rozkłada adres na nazwane części. Przy bzdurach rzuca błąd.
• url.searchParams to URLSearchParams: używaj get, getAll, set, append, delete, has.
• Kodowanie dzieje się samo. Nie sięgaj po encodeURIComponent, chyba że budujesz stringi ręcznie.
• Przekaż bazowy URL jako drugi argument, żeby rozwiązać ścieżki względne.
• URL.canParse (albo try/catch) to twoje narzędzie do walidacji niezaufanych danych.

Za każdym razem, gdy kusi cię podzielenie adresu przez .split('?') albo wyłowienie parametru zapytania regexem, sięgnij zamiast tego po te API. Są krótsze, poprawne i już wbudowane w środowisko.