URLPattern, web platformuna yönlendirme sağlar

Yaygın kalıp eşleştirme kullanım alanlarını standartlaştırmaya yönelik bir yaklaşım.

Yönlendirme, her web uygulamasının önemli bir parçasıdır. Yönlendirmenin temelinde, bir URL'yi almak, URL'ye bazı kalıp eşleştirmeleri veya uygulamaya özgü başka bir mantık uygulamak ve ardından genellikle sonuca göre web içeriği görüntülemek yer alır. Yönlendirme çeşitli şekillerde uygulanabilir: bazen bir yolu diskteki dosyalara eşleyen bir sunucuda kod çalıştırılabilir veya tek sayfalık bir uygulamada, geçerli konumdaki değişiklikleri bekleyen ve gösterilecek buna karşılık gelen bir DOM parçası oluşturan bir mantık uygulanabilir.

Kesin bir standart olmasa da web geliştiricileri, URL yönlendirme kalıplarını ifade etmek için regular expressions ile çok ortak noktası olan ancak yol segmentlerini eşleştirmek için jetonlar gibi alana özgü bazı eklemeler içeren ortak bir söz dizimi kullanmaya yönelmiştir. Express ve Ruby on Rails gibi popüler sunucu tarafı çerçeveler bu söz dizimini (veya buna çok yakın bir yapıyı) kullanır. JavaScript geliştiricileri de bu mantığı kendi kodlarına eklemek için path-to-regexp veya regexpparam gibi modülleri kullanabilir.

URLPattern, bu çerçevelerin oluşturduğu temeli temel alan web platformuna eklenen bir özelliktir. Amaç, joker karakterler, adlandırılmış jeton grupları, normal ifade grupları ve grup değiştiriciler için destek de dahil olmak üzere yönlendirme kalıbı söz dizimini standartlaştırmaktır. Bu söz dizimi ile oluşturulan URLPattern örnekleri, tam URL'lerle veya bir URLpathname ile eşleştirme gibi ortak yönlendirme görevlerini gerçekleştirebilir ve jeton ile grup eşleşmeleri hakkında bilgi döndürebilir.

URL eşleştirmeyi doğrudan web platformunda sağlamanın bir diğer avantajı, ortak bir söz dizisinin, URL'lerle eşleşmesi gereken diğer API'lerle paylaşılabilmesidir.

Tarayıcı desteği ve polyfill'ler

URLPattern, Chrome ve Edge 95 ve sonraki sürümlerinde varsayılan olarak etkindir.

urlpattern-polyfill kitaplığı, URLPattern arayüzünü tarayıcılarda veya yerleşik destekten yoksun Node gibi ortamlarda kullanmanın bir yolunu sağlar. Çoklu dolgu kullanıyorsanız özelliği yalnızca mevcut ortamda destek yoksa yüklediğinizden emin olmak için özellik algılamayı kullandığınızdan emin olun. Aksi takdirde, URLPattern'ün en önemli avantajlarından birini kaybedersiniz: Destek ortamlarının, kullanmak için ek kod indirip ayrıştırması gerekmez.

if (!(globalThis && 'URLPattern' in globalThis)) {
  // URLPattern is not available, so the polyfill is needed.
}

Söz dizimi uyumluluğu

URLPattern'ün temel felsefesi, yeniden keşif yapmaktan kaçınmaktır. Express veya Ruby on Rails'de kullanılan yönlendirme söz dizimine aşinaysanız yeni bir şey öğrenmeniz gerekmez. Ancak popüler yönlendirme kitaplıklarındaki söz dizimi farklılıkları göz önüne alındığında, temel söz dizimi olarak bir şey seçilmesi gerekiyordu. URLPattern'ün tasarımcıları, başlangıç noktası olarak path-to-regexp'teki kalıp söz dizimini (API yüzeyi değil) kullanmaya karar verdi.

Bu karar, path-to-regexp'ün mevcut geliştiricisiyle yapılan ayrıntılı bir danışma sürecinin ardından alınmıştır.

Desteklenen söz dizimi çekirdeğini öğrenmenin en iyi yolu, path-to-regexp ile ilgili dokümanları incelemektir. MDN'de yayınlanması planlanan belgeleri GitHub'daki mevcut ana sayfasından okuyabilirsiniz.

Ek özellikler

URLPattern söz dizimi, path-to-regexp tarafından desteklenen içeriğin bir üst kümesidir. Bunun nedeni URLPattern, yönlendirme kitaplıkları arasında yaygın olmayan bir özelliği (ana makine adlarındaki joker karakterler dahil olmak üzere kaynakları eşleştirme) destekler. Diğer yönlendirme kitaplıklarının çoğu yalnızca pathname ve bazen de URL'nin arama veya karma kısmıyla ilgilenir. URL'ler yalnızca bağımsız bir web uygulaması içinde aynı kaynaklı yönlendirme için kullanıldığından URL'nin kaynak kısmını hiçbir zaman kontrol etmeleri gerekmez.

Kaynakları dikkate almak, kaynak ötesi isteklerin bir hizmet çalışanının fetch etkinlik işleyicisinde yönlendirilmesi gibi ek kullanım alanlarına kapı açar. Yalnızca aynı kaynaktan gelen URL'leri yönlendiriyorsanız bu ek özelliği göz ardı edebilir ve URLPattern'yi diğer kitaplıklar gibi kullanabilirsiniz.

Örnekler

Deseni oluşturma

URLPattern oluşturmak için kurucusuna dizeleri veya özellikleri eşleştirilecek kalıpla ilgili bilgiler içeren bir nesneyi iletin.

Bir nesne iletmek, her URL bileşenini eşleştirmek için hangi kalıbın kullanılacağı konusunda en net kontrolü sağlar. En ayrıntılı şekilde şu şekilde görünebilir:

const p = new URLPattern({
  protocol: 'https',
  username: '',
  password: '',
  hostname: 'example.com',
  port: '',
  pathname: '/foo/:image.jpg',
  search: '*',
  hash: '*',
});

Bir mülk için boş bir dize sağlandığında eşleşme yalnızca URL'nin ilgili bölümü ayarlanmadığında gerçekleşir. Joker karakter *, URL'nin belirli bir bölümü için herhangi bir değerle eşleşir.

Oluşturucu, daha kolay kullanım için çeşitli kısayollar sunar. search ve hash veya diğer özelliklerin tamamen atlanması, bunları '*' joker karakterine ayarlamaya eşdeğerdir. Yukarıdaki örnek şu şekilde basitleştirilebilir:

const p = new URLPattern({
  protocol: 'https',
  username: '',
  password: '',
  hostname: 'example.com',
  port: '',
  pathname: '/foo/:image.jpg',
});

Ek bir kısayol olarak, kaynakla ilgili tüm bilgiler tek bir mülkte (baseURL) sağlanabilir. Bu,

const p = new URLPattern({
  pathname: '/foo/:image.jpg',
  baseURL: 'https://example.com',
});

Bu örneklerin tümü, kullanım alanınızda eşleşen kaynakların bulunduğu varsayılır. Kaynağı hariç tutarak (birçok "geleneksel" tek kaynaklı yönlendirme senaryosunda olduğu gibi) URL'nin yalnızca diğer kısımlarında eşleştirme yapmak istiyorsanız kaynak bilgisini tamamen atlayıp yalnızca pathname, search ve hash özelliklerinin bir kombinasyonunu sağlayabilirsiniz. Daha önce olduğu gibi, atlanan özellikler * joker karakter kalıbına ayarlanmış gibi değerlendirilir.

const p = new URLPattern({pathname: '/foo/:image.jpg'});

Oluşturucuya bir nesne göndermek yerine bir veya iki dize sağlayabilirsiniz. Tek bir dize sağlanırsa bu dize, kaynağı eşleştirmek için kullanılan kalıp bilgileri de dahil olmak üzere tam bir URL kalıbını temsil etmelidir. İki dize sağlarsanız ikinci dize baseURL olarak kullanılır ve ilk dize bu tabana göre kabul edilir.

Bir veya iki dize sağlanırsa URLPattern kurucusu, URL kalıbının tamamını ayrıştırarak URL bileşenlerine ayırır ve daha büyük kalıbın her bölümünü ilgili bileşenle eşleştirir. Bu, arka planda, dizelerle oluşturulan her URLPattern nesnesinin, nesneyle oluşturulan eşdeğer bir URLPattern ile aynı şekilde temsil edildiği anlamına gelir. strings yapıcısı, daha az ayrıntılı bir arayüz tercih edenler için yalnızca bir kısayoldur.

const p = new URLPattern('https://example.com/foo/:image.jpg?*#*');

URLPattern oluşturmak için dize kullanırken dikkate almanız gereken birkaç nokta vardır.

URLPattern oluşturmak için bir nesne kullanırken bir mülkü dışarıda bırakmak, söz konusu mülk için bir * joker karakteri sağlamaya eşdeğerdir. Tam URL dize kalıbı ayrıştırılırken URL bileşenlerinden birinde değer eksikse bileşenin özelliği '' olarak ayarlanmış gibi değerlendirilir. Bu durumda yalnızca bileşen boş olduğunda eşleşme olur.

Dize kullanırken, oluşturulan URLPattern içinde kullanılmasını istediğiniz joker karakterleri açıkça eklemeniz gerekir.

// p1 and p2 are equivalent.
const p1 = new URLPattern('/foo', location.origin);
const p2 = new URLPattern({
  protocol: location.protocol,
  hostname: location.hostname,
  pathname: '/foo',
  search: '',
  hash: '',
});

// p3 and p4 are equivalent.
const p3 = new URLPattern('/foo?*#*', location.origin);
const p4 = new URLPattern({
  protocol: location.protocol,
  hostname: location.hostname,
  pathname: '/foo',
});

Bir dize kalıbını bileşenlerine ayırmanın da belirsiz olabileceğini unutmayın. : gibi, URL'lerde bulunan ancak kalıp eşleştirme söz diziminde özel anlamı olan karakterler vardır. Bu belirsizliği önlemek için URLPattern kurucusu, bu özel karakterlerin URL'nin değil, bir kalıbın parçası olduğunu varsayar. Anlamsız bir karakterin URL'nin bir parçası olarak yorumlanmasını istiyorsanız karakteri, dize olarak sağlandığında \` character. For example, the literal URLabout:blankshould be escaped as'about\:blank' ile kaçak karakter olarak eklediğinizden emin olun.

Deseni kullanma

Bir URLPattern oluşturduktan sonra bunu kullanmanın iki seçeneğiniz vardır. test() ve exec() yöntemleri aynı girişi alır ve eşleşme olup olmadığını kontrol etmek için aynı algoritmayı kullanır. Bu yöntemler arasındaki tek fark, döndürülen değerdir. test(), belirli bir girişle eşleşme olduğunda true, aksi takdirde false değerini döndürür. exec(), yakalama gruplarıyla birlikte eşleşmeyle ilgili ayrıntılı bilgi döndürür veya eşleşme yoksa null döndürür. Aşağıdaki örneklerde exec() kullanımı gösterilmektedir, ancak yalnızca basit bir boole dönüş değeri istiyorsanız test() değerini bunlardan herhangi biriyle değiştirebilirsiniz.

test() ve exec() yöntemlerini kullanmanın bir yolu, dize göndermektir. Oluşturucunun desteklediğine benzer şekilde, tek bir dize sağlanırsa bu dize, kaynak da dahil olmak üzere tam bir URL olmalıdır. İki dize sağlanırsa ikinci dize, baseURL değeri olarak değerlendirilir ve ilk dize bu tabana göre değerlendirilir.

const p = new URLPattern({
  pathname: '/foo/:image.jpg',
  baseURL: 'https://example.com',
});

const result = p.exec('https://example.com/foo/cat.jpg');
// result will contain info about the successful match.
// const result = p.exec('/foo/cat.jpg', 'https://example.com')
// is equivalent, using the baseURL syntax.

const noMatchResult = p.exec('https://example.com/bar');
// noMatchResult will be null.

Alternatif olarak, URL'nin eşleşmesi gereken yalnızca bölümlerine ayarlanmış özelliklere sahip, kurucunun desteklediği türde bir nesne de iletebilirsiniz.

const p = new URLPattern({pathname: '/foo/:image.jpg'});

const result = p.exec({pathname: '/foo/:image.jpg'});
// result will contain info about the successful match.

exec() işlevi, joker karakter veya jeton içeren bir URLPattern üzerinde kullanıldığında döndürülen değer, giriş URL'sindeki ilgili değerlerin ne olduğu hakkında bilgi verir. Bu sayede, bu değerleri kendiniz ayrıştırmak zorunda kalmazsınız.

const p = new URLPattern({
  hostname: ':subdomain.example.com',
  pathname: '/*/:image.jpg'
});

const result = p.exec('https://imagecdn1.example.com/foo/cat.jpg');
// result.hostname.groups.subdomain will be 'imagecdn1'
// result.pathname.groups[0] will be 'foo', corresponding to *
// result.pathname.groups.image will be 'cat'

Anonim ve adlandırılmış gruplar

exec() işlevine bir URL dizesi ilettiğinizde, hangi bölümlerin kalıbın tüm gruplarıyla eşleştiğini belirten bir değer alırsınız.

Döndürülen değer, URLPattern bileşenlerine (ör. pathname) karşılık gelen özelliklere sahiptir. Dolayısıyla, bir grup URLPattern değerinin pathname kısmı olarak tanımlandıysa eşleşmeler, döndürülen değerin pathname.groups kısmında bulunabilir. Eşleşmeler, ilgili kalıbın anonim veya adlandırılmış bir grup olup olmadığına bağlı olarak farklı şekilde temsil edilir.

Anonim kalıp eşleşmesinin değerlerine erişmek için dizi dizinlerini kullanabilirsiniz. Birden fazla anonim kalıp varsa 0 dizini, en soldaki için eşleşen değeri temsil eder. 1 ve sonraki kalıplar için başka dizinler de kullanılır.

Bir kalıpta adlandırılmış gruplar kullanıldığında eşleşmeler, adları her grup adına karşılık gelen özellikler olarak gösterilir.

Unicode desteği ve normalleştirme

URLPattern, Unicode karakterlerini birkaç farklı şekilde destekler.

  • :café gibi adlandırılmış gruplar Unicode karakterleri içerebilir. Geçerli JavaScript tanımlayıcıları için kullanılan kurallar, adlandırılmış gruplar için geçerlidir.

  • Bir kalıptaki metin, ilgili bileşenin URL kodlaması için kullanılan kurallara göre otomatik olarak kodlanır. pathname içindeki Unicode karakterleri yüzde olarak kodlanır. Bu nedenle, /café gibi bir pathname kalıbı otomatik olarak /caf%C3%A9 olarak normalleştirilir. hostname içindeki Unicode karakterleri, yüzde kodlaması yerine Punycode kullanılarak otomatik olarak kodlanır.

  • Normal ifade grupları yalnızca ASCII karakterleri içermelidir. Normal ifade söz dizimi, bu gruplardaki Unicode karakterlerinin otomatik olarak kodlanmasını zor ve güvenli olmayan bir hale getirir. Normal ifade grubunda bir Unicode karakteriyle eşleşmek istiyorsanız karakteri manuel olarak yüzde kodlamanız gerekir (ör. café ile eşleşmek için (caf%C3%A9)).

URLPattern, Unicode karakterlerini kodlamaya ek olarak URL normalleştirmesi de gerçekleştirir. Örneğin, pathname bileşenindeki /foo/./bar, eşdeğer /foo/bar değerine daraltılır.

Belirli bir giriş kalıbının nasıl normalleştirildiğinden şüphe duyuyorsanız tarayıcınızın DevTools aracını kullanarak oluşturulan URLPattern örneğini inceleyin.

Tüm unsurların birleşimi

Aşağıda yerleştirilmiş Glitch demosunda, belirli kalıpların ağ isteklerine yanıt oluşturabilecek asenkron işlevlerle eşlenmesi yoluyla bir hizmet çalışanının fetch event handler içinde URLPattern'ün temel kullanım alanı gösterilmektedir. Bu örnekteki kavramlar, sunucu tarafı veya istemci tarafı diğer yönlendirme senaryolarına da uygulanabilir.

Geri bildirim ve gelecek planları

URLPattern'ün temel işlevleri Chrome ve Edge'e eklendi ancak daha fazla ekleme planlanıyor. URLPattern'ün bazı özellikleri henüz geliştirilme aşamasındadır ve belirli davranışlarla ilgili olarak daha da hassaslaştırılabilecek birçok açık soru vardır. URLPattern'yi denemenizi ve GitHub sorunu üzerinden geri bildirimde bulunmanızı öneririz.

Şablon oluşturma desteği

path-to-regexp kitaplığı, yönlendirme davranışını etkili bir şekilde tersine çeviren bir compile() function sağlar. compile(), jeton yer tutucuları için bir kalıp ve değerler alır ve bu değerlerin yerine geçtiği bir URL yolu dizesi döndürür.

Gelecekte bunu URLPattern'a eklemeyi umuyoruz, ancak ilk sürümün kapsamında değildir.

Gelecekteki web platformu özelliklerini etkinleştirme

URLPattern'ün web platformunun yerleşik bir parçası haline geleceği varsayıldığında, yönlendirme veya kalıp eşleştirmeden yararlanabilecek diğer özellikler, bunun üzerine temel öğe olarak inşa edilebilir.

Hizmet çalışanı kapsamı desen eşleştirme, dosya işleyici olarak PWA'lar ve tahmini ön getirme gibi önerilen özellikler için URLPattern kullanımıyla ilgili tartışmalar devam etmektedir.

Teşekkür ederiz

Teşekkürlerin tam listesi için orijinal açıklama belgesine bakın.