Tutorial

URLSearchParams Rehberi: Filtre ve Sayfalama URL’leri

Mehmet Fatih Ünal
2 Kasım 2026
6 dk okuma
#JavaScript#URLSearchParams#Web API#Sayfalama#Frontend#Veri Doğrulama
URLSearchParams Rehberi: Filtre ve Sayfalama URL’leri

URLSearchParams ne işe yarar?

URLSearchParams, URL'nin sorgu bölümündeki anahtar ve değerleri okumak, değiştirmek ve yeniden üretmek için kullanılan Web API'sidir. Arama kutusu, kategori filtresi ve sayfa numarasını elle metin birleştirmeden adrese taşımayı sağlar. MDN URLSearchParams referansı, temel işlemleri ve kodlama davranışını açıklar.

Bir kullanıcı C++ & C# aradığında, bu metni doğrudan ?q= sonuna eklemek doğru değildir. Artı ve & karakterlerinin sorgu dizisinde özel anlamları vardır. Sorun yalnızca Türkçe karakterlerle sınırlı değildir; çok sıradan bir ürün adı da elle birleştirilen adresi değiştirebilir.

Filtre ve sayfalama URL'si nasıl oluşturulur?

Bir sorgu değeri eklerken ham metni URLSearchParams'a verin ve kodlamayı toString işlemine bırakın. Önceden encodeURIComponent uygulamak, yüzde işaretinin yeniden kodlanmasına ve çift kodlamaya yol açabilir.

Aşağıdaki örnekte q tek arama metnini, tag birden fazla etiketi, page ise pozitif bir tam sayıyı temsil eder. İlk sayfa URL'de yazılmaz; bu, örneğin seçtiği adres politikasıdır.

function productSearch({ query = '', tags = [], page = 1 } = {}) {
  if (!Number.isSafeInteger(page) || page < 1) {
    throw new Error('Invalid page');
  }

  const params = new URLSearchParams();
  if (query.trim()) params.set('q', query.trim());
  for (const tag of tags) params.append('tag', tag);
  if (page > 1) params.set('page', String(page));

  const search = params.toString();
  return '/products' + (search ? '?' + search : '');
}

console.log(productSearch({
  query: 'C++ & C#', tags: ['web', 'api'], page: 2,
}));
// /products?q=C%2B%2B+%26+C%23&tag=web&tag=api&page=2

Bu biçimde boşluklar + ile, gerçek artı karakterleri ise %2B ile temsil edilir. Bir değeri okuduğunuzda tekrar elle çözmeniz gerekmez. Kodlama kuralları WHATWG URL Standardı'nda tanımlanır.

set, append, get ve getAll arasındaki fark nedir?

set, bir anahtarın değerini belirler ve aynı anahtarın diğer değerlerini kaldırır. append yeni bir değer daha ekler; get ilk değeri, getAll ise bütün değerleri döndürür. append referansı ve getAll referansı bu ayrımı gösterir.

Çoklu etiket seçimini virgülle birleştirmek de mümkündür, fakat bu başka bir API sözleşmesidir. Etiketin kendisinde virgül varsa nasıl ayrılacağı tanımlanmalıdır. Örnekte aynı tag anahtarını tekrarlamak, bu ek ayrıştırma kuralını gerektirmez.

Tek değer beklenen bir parametrenin tekrarını da düşünün. ?page=2&page=9 için istemci ilk değeri kullanırken sunucunun son değeri seçmesi, iki katmanın farklı sonuç üretmesine neden olur. Kurala yalnızca arayüzde karar vermeyin; sunucu tarafında da aynı sözleşmeyi uygulayın.

URL'den okunan sayfa numarası nasıl doğrulanır?

URLSearchParams değerleri metin olarak verir; sayı türünü ve iş kuralını kendiliğinden doğrulamaz. Aşağıdaki okuyucu, q ve page tekrarını reddeder, tag tekrarını kabul eder ve page için güvenli pozitif tam sayı ister.

function readProductFilters(href) {
  const params = new URL(href, 'https://shop.example').searchParams;

  function one(name, fallback) {
    const values = params.getAll(name);
    if (values.length > 1) throw new Error('Duplicate ' + name);
    return values[0] ?? fallback;
  }

  const rawPage = one('page', '1');
  if (!/^[1-9][0-9]*$/.test(rawPage)) throw new Error('Invalid page');
  const page = Number(rawPage);
  if (!Number.isSafeInteger(page)) throw new Error('Invalid page');

  return {
    query: one('q', ''),
    tags: params.getAll('tag'),
    page,
  };
}

page=2abc değerini parseInt ile 2'ye indirmek yerine girdinin tamamı kontrol edilir. Boş değer, sıfır, negatif sayı ve ondalık sayı bu örnekte geçersizdir. Gerçek sunucu, sayfa boyutu ve arama metni uzunluğu gibi kendi sınırlarını da ayrıca uygulamalıdır.

Tam adresi doğrudan new URLSearchParams içine koymayın. URL searchParams özelliği, URL'nin sorgu kısmını ayırır; örnekte göreli adresler için verilen taban da bunu açık hale getirir.

Filtre değişince sayfa numarası korunmalı mı?

Filtre değiştiğinde sayfa numarasının sıfırlanması bir ürün kararıdır, URLSearchParams'ın otomatik davranışı değildir. Yeni sonuç kümesinde eski sayfa bulunmayabileceği için çoğu liste tasarımında ilk sayfaya dönmek anlaşılır bir başlangıçtır.

Geri ve ileri gezinmede formun adresi izlemesini de sağlayın. Yalnızca filtre seçerken URL yazan, sayfa açıldığında URL okumayan bir arayüz paylaşılabilir görünür ama paylaşılan durumu geri kuramaz. Cursor tabanlı bir API kullanıyorsanız sayfalama rehberindeki cursor kurallarını uygulayın; bir sayfa numarasını cursor yerine geçirmek yeterli değildir.

URL kodlamak veriyi güvenli hale getirir mi?

URL kodlama, sorgu metninin yapısını korur; yetkilendirme veya sunucu doğrulaması sağlamaz. Kullanıcının elle değiştirdiği page, tag veya kaynak kimliği her zaman sunucuda kontrol edilmelidir. 401 ve 403 rehberi erişim kararlarını ayrı ele alır.

Kontrol listenizde boş sorgu, Türkçe harfler, gerçek + işareti, & karakteri, birden fazla etiket ve yinelenen tekil alan bulunsun. Oluşturulan URL'yi okuyucuya geri verip aynı filtre durumuna ulaşıldığını doğrulayın.

Sık sorulan sorular

URLSearchParams tam URL'yi ayrıştırır mı? Hayır. Tam adres için URL nesnesi oluşturup searchParams özelliğini kullanın.

get bütün etiketleri döndürür mü? Hayır. Aynı anahtardaki bütün değerler için getAll gerekir.

Değer eklemeden önce encodeURIComponent gerekli mi? Bu örnekte hayır. Ham değeri verin; sorgu dizisinin kodlanmasını URLSearchParams yapar.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar