JavaScript URL ve URLSearchParams Kullanımı

URL'leri String Hileleriyle Parse Etmeyi Bırakın

URL API'si hayatımıza girmeden önce insanlar URL'leri split('?'), regex ve biraz da şansla parçalara ayırıyordu. Değerin içinde bir &, =, boşluk ya da ASCII dışı bir karakter çıkana kadar da iş görüyordu — ondan sonrası felaket. Oysa hem tarayıcıda hem de Node'da düzgün bir parser hazır geliyor. Onu kullanın.

Tek bir çağrıyla URL'in tüm parçaları ayrıştırılıp düzgünce decode edilmiş halde elinize geliyor. Geçersiz girdi verdiğinizde constructor bir TypeError fırlatır — ki genelde istediğiniz de budur: bozuk bir URL, sessizce ileriye bozuk veri taşımak yerine yüksek sesle patlamalıdır.

Query Parametrelerini Okumak

Her URL nesnesinin bir .searchParams özelliği vardır — query string'i okuyup yazmayı bilen bir URLSearchParams nesnesi:

Dikkat etmeniz gereken birkaç nokta var:

• Değerler size decode edilmiş halde döner. ?name=Ada%20Lovelace size "Ada Lovelace" verir.
• Her şey string'tir. "2", 2 değildir. Sayıya ihtiyacınız varsa Number() ile dönüştürün.
• Aynı key'i birden fazla kullanmak geçerlidir. get ilk eşleşmeyi, getAll ise tüm eşleşmeleri döner.
• Olmayan key'ler undefined değil null döner — yani ?? "default" ile güzel çalışır.

JavaScript ile Query String Oluşturma

Query string'i sıfırdan URLSearchParams ile oluşturabilirsiniz — elle escape etmeye ya da & ile birleştirmeye gerek yok:

Ya da bir nesneden oluşturabilirsin — [anahtar, değer] çiftlerinden oluşan herhangi bir iterable işe yarar, düz bir nesne de kullanılabilir:

set ile append arasındaki fark: set, o anahtara ait mevcut değeri ezip yerine yenisini yazar. append ise aynı anahtarla bir değer daha ekler. Bir anahtarın birden fazla kez bulunması mantıklıysa (etiketler, filtreler gibi) append kullan; tek değer taşıyan parametrelerde ise set tercih edilmeli.

URL'yi güncelleme

URL canlı bir nesne olduğu için searchParams üzerinde yaptığın değişiklikler .search ve .href alanlarına otomatik olarak yansır:

Bu, mevcut bir URL'ye query parametresi eklemenin en doğru yolu. "URL'de zaten ? var mı?" diye kontrol etmeye ya da başına & mi ? mi koyacağım diye kafa yormaya gerek yok.

URL'nin diğer kısımlarını da aynı mantıkla değiştirebilirsiniz:

Parametreler Üzerinde Döngü Kurmak

URLSearchParams iterable'dır, yani üzerinde döngü kurabilirsin. for...of ile sana [key, value] çiftleri döner; ayrıca alışık olduğumuz keys(), values() ve entries() yardımcıları da mevcut:

Dikkat et: tekrar eden anahtarlar birden fazla kez görünür — yani tag = web ve ardından tag = beginner ayrı ayrı yer alır. Bu, query string'in gerçek hâline birebir uyuyor.

Hızlı bir debug çıktısı için düz bir nesneye ihtiyacın varsa Object.fromEntries işini görür, ama tekrar eden anahtarları ezer; yalnızca sonuncu değeri tutar:

Hata ayıklama için iş görür. Ama tekrar eden bir anahtar olabiliyorsa yanlış yoldasınız.

Göreceli URL'lerde Taban Adres Şart

Tek başına new URL("/search?q=js") yazarsanız hata alırsınız — göreceli bir yol, başlı başına geçerli bir URL değildir. İkinci argüman olarak bir taban adres geçmeniz gerekir:

Buradaki çözümleme kuralları, tarayıcıların <a href> için kullandığı kurallarla aynı: başında / varsa host'a göre mutlak yol, slash yoksa mevcut yola göreceli, .. ise bir üst dizine çıkarır. Yapılandırılmış bir base URL'den API adresleri oluştururken epey işinize yarar.

Tarayıcı tarafında window.location.href, mevcut sayfanın URL'sini parse etmek için hazır bir base olarak kullanılabilir:

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

Geçersiz URL'lerle Başa Çıkmak

URL constructor, hatalı biçimdeki girdilerde hata fırlatır. Bu aslında işinize yarar — ama kullanıcıdan ya da dış bir sistemden gelen herhangi bir şeyi parse ederken try/catch kullanmanız gerektiği anlamına gelir:

Modern ortamlarda ayrıca URL.canParse(input) diye bir yöntem var — sadece doğrulama yapmak istediğinizde try/catch zahmetine girmeden boolean olarak sonuç dönen pratik bir kontrol:

Küçük Bir Çalışan Örnek

Şimdi hepsini birleştirelim: Bir URL'deki mevcut filtreleri okuyalım, üzerinde oynayalım ve yönlendirme yapmak için yeni bir URL üretelim:

null geçersen parametre silinir. Başka bir değer verirsen parametre set edilir ya da üzerine yazılır. Filtre arayüzleri, sayfalama ya da deep link kurarken bir şekilde hep bu kalıbı yazıyor olacaksın.

Akılda Kalması Gerekenler

• new URL(string) bir URL'i etiketli parçalara ayırır. Saçma bir değer verirsen hata fırlatır.
• url.searchParams bir URLSearchParams nesnesidir — get, getAll, set, append, delete, has metotlarını kullan.
• Encoding işini senin yerine hallediyor. Elle string kurmadığın sürece encodeURIComponent'e uzanma.
• Göreli yolları çözümlemek için ikinci argüman olarak bir temel URL geçebilirsin.
• Güvenilmeyen girdileri doğrulamak için URL.canParse (ya da try/catch) tam sana göre.

Ne zaman bir URL'i .split('?') ile parçalamak veya query parametresini regex ile çekmek aklına gelirse, onun yerine bu API'lere uzan. Hem daha kısalar, hem doğru çalışıyorlar, hem de zaten runtime'ın içinde hazır duruyorlar.