Yaygın kalıp eşleştirme kullanım alanlarını standartlaştırmaya yönelik bir yaklaşım.
Arka plan
Yönlendirme, her web uygulamasının temel bir parçasıdır. Yönlendirme, temel olarak bir URL almayı, ona bir kalıp eşleştirme veya uygulamaya özel başka bir mantık uygulamayı ve ardından, genellikle sonuca göre web içeriğini görüntülemeyi içerir. Yönlendirme birkaç şekilde uygulanabilir: Bazen diskteki dosyaların yolunu eşleyen bir sunucuda çalışan kod veya geçerli konumda değişiklik yapılmasını bekleyen ve görüntülenecek karşılık gelen bir DOM parçasını oluşturan tek sayfalık bir uygulamadaki mantıktır.
Tek bir kesin standart olmasa da web geliştiricileri, regular expressions
ile birçok ortak yöne sahip URL yönlendirme kalıplarını ifade etmek için ortak bir söz dizimine yönelmiş, ancak yol segmentlerini eşleştiren jetonlar gibi bazı alana özgü eklemeler yapmıştır.
Express ve Ruby on Rails gibi popüler sunucu tarafı çerçeveler bu söz dizimini (veya ona çok yakın bir şeyi) kullanır ve JavaScript geliştiricileri, path-to-regexp
veya regexpparam
gibi modülleri kullanarak bu mantığı kendi kodlarına ekleyebilir.
URLPattern
, bu çerçeveler tarafından oluşturulan temeli üzerine alan web platformuna yapılan bir eklemedir. Amacı; joker karakterler, adlandırılmış jeton grupları, normal ifade grupları ve grup değiştiricileri için destek de dahil olmak üzere bir yönlendirme kalıbı söz dizimini standartlaştırmaktır. Bu söz dizimiyle oluşturulan URLPattern
örnekleri, tam URL'ler veya bir URL pathname
ile eşleştirme, jeton ve grup eşleşmeleriyle ilgili bilgileri döndürme gibi yaygın yönlendirme görevlerini gerçekleştirebilir.
Doğrudan web platformunda URL eşleştirmesi sağlamanın bir başka yararı da ortak bir söz diziminin, URL'lerle eşleşmesi gereken diğer API'lerle de paylaşılabilmesidir.
Tarayıcı desteği ve çoklu dolgular
URLPattern
, Chrome ile Edge 95 ve sonraki sürümlerde varsayılan olarak etkindir.
urlpattern-polyfill
kitaplığı, URLPattern
arayüzünü yerleşik desteği olmayan Node gibi tarayıcılarda veya ortamlarda kullanmak için bir yol sağlar. Çoklu dolguyu kullanıyorsanız özelliği yalnızca mevcut ortamda desteklenmemesi durumunda yüklediğinizden emin olmak için özellik algılamayı kullandığınızdan emin olun. Aksi takdirde, URLPattern
ürününün önemli avantajlarından birini kaybedersiniz: yani desteklenen ortamların, kullanmak için ek kod indirip ayrıştırmasına gerek kalmaz.
if (!(globalThis && 'URLPattern' in globalThis)) {
// URLPattern is not available, so the polyfill is needed.
}
Söz dizimi uyumluluğu
URLPattern
için yol gösterici felsefe, yeniden buluşlardan kaçınmaktır. Express veya Ruby on Rails'de kullanılan yönlendirme söz dizimini zaten biliyorsanız yeni bir şey öğrenmenize gerek yoktur. Ancak popüler yönlendirme kitaplıklarındaki söz dizimleri arasındaki küçük farklılıklar nedeniyle bir şeyin temel söz dizimi olarak seçilmesi gerekiyordu ve URLPattern
tasarımcıları, başlangıç noktası olarak path-to-regexp
kalıbı söz dizimini kullanmaya karar verdi (ancak API yüzeyini kullanmadı).
Bu karar, path-to-regexp
cihazının mevcut koruyucusuyla yakından görüşüldükten sonra alınmıştır.
Desteklenen söz diziminin temelini öğrenmenin en iyi yolu path-to-regexp
ile ilgili belgelere bakmaktır. MDN'de yayınlanması planlanan
dokümanları şu anda GitHub'daki ana sayfasında okuyabilirsiniz.
Ek özellikler
URLPattern
, yönlendirme kitaplıkları arasında yaygın olmayan bir özelliği desteklediğinden URLPattern
söz dizimi, path-to-regexp
tarafından desteklenen özelliklerin üst kümesidir: ana makine adlarındaki joker karakterler dahil kaynakları eşleştirme. Diğer yönlendirme kitaplıklarının çoğu yalnızca yol adı ve bazen de bir URL'nin arama veya karma bölümüyle ilgilenir. URL'ler yalnızca bağımsız bir web uygulaması içinde aynı kaynak yönlendirmesi için kullanıldığından hiçbir zaman URL'nin kaynak kısmını kontrol etmeleri gerekmez.
Kaynakların dikkate alınması, Service Worker'ın fetch
etkinlik işleyicisi içinde kaynaklar arası isteklerin yönlendirilmesi gibi ek kullanım alanları için kapı açar. Yalnızca aynı kaynaklı URL'leri yönlendiriyorsanız bu ek özelliği etkili bir şekilde yok sayabilir ve URLPattern
öğesini diğer kitaplıklar gibi kullanabilirsiniz.
Örnekler
Kalıbı oluşturma
Bir URLPattern
oluşturmak için kurucusunu dizeleri veya özellikleri, eşleştirilecek kalıpla ilgili bilgiler içeren bir nesne iletin.
Bir nesnenin iletilmesi, her bir URL bileşenini eşleştirmek için hangi kalıbın kullanılacağı konusunda en açık kontrolü sağlar. En ayrıntılı haliyle,
const p = new URLPattern({
protocol: 'https',
username: '',
password: '',
hostname: 'example.com',
port: '',
pathname: '/foo/:image.jpg',
search: '*',
hash: '*',
});
Bir mülk için boş dize sağlanması, yalnızca URL'nin karşılık gelen bölümü ayarlanmadığında eşleşir. *
joker karakteri, URL'nin belirli bir bölümü için her değerle eşleşir.
Oluşturucu, daha basit kullanım için çeşitli kısayollar sunar. search
ve hash
özelliklerini ya da diğer özellikleri tamamen atlamak, bunları '*'
joker karakterine ayarlamakla eşdeğerdir. Yukarıdaki örnek aşağıdaki şekilde
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. Böylece,
const p = new URLPattern({
pathname: '/foo/:image.jpg',
baseURL: 'https://example.com',
});
Bu örneklerin tümünde, kullanım alanınızın eşleşen kaynaklar içerdiği varsayılır. Kaynağı hariç tutarak yalnızca URL'nin diğer bölümleriyle eşleştirme yapmak istiyorsanız (birçok "geleneksel" tek kaynak yönlendirme senaryosunda olduğu gibi) kaynak bilgilerini 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'});
Bir nesneyi oluşturucuya geçirmeye alternatif olarak bir veya iki dize sağlayabilirsiniz. Bir dize sağlanırsa kaynağı eşleştirmek için kullanılan kalıp bilgileri de dahil olmak üzere tam 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 değerlendirilir.
İster bir ister iki dize sağlanmış olsun, URLPattern
oluşturucusu tam URL kalıbını ayrıştırarak bunu URL bileşenlerine ayırır ve daha büyük kalıbın her bir bölümünü karşılık gelen bileşenle eşler. Bu da, dizelerle oluşturulan her URLPattern
öğesinin, bir nesneyle oluşturulmuş eşdeğer bir URLPattern
ile aynı şekilde temsil edileceği anlamına gelir. Dize oluşturucu, daha az ayrıntılı bir arayüzü tercih edenler için bir kısayoldur.
const p = new URLPattern('https://example.com/foo/:image.jpg?*#*');
URLPattern
oluşturmak için dizeleri kullanırken unutulmaması gereken birkaç nokta vardır.
URLPattern
oluşturmak için bir nesne kullanırken bir özelliğin dışarıda bırakılması, söz konusu özellik için *
joker karakteri sağlamaya eşdeğerdir. Tam URL dize kalıbı ayrıştırıldığında, URL bileşenlerinden birinde bir değer eksikse bileşenin özelliği ''
olarak ayarlanmış gibi değerlendirilir. Bu özellik, yalnızca bileşen boş olduğunda eşleşir.
Dizeleri kullanırken, oluşturulan URLPattern
içinde kullanılmasını istiyorsanız 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 ayrıştırmanın muhtemelen belirsiz olduğunu da unutmamalısınız. URL'lerde bulunan :
gibi karakterler vardır ancak kalıp eşleştirme söz diziminde de özel anlamları vardır. Bu belirsizliği önlemek için URLPattern
oluşturucusu, bu özel karakterlerden herhangi birinin URL'nin parçası değil, bir kalıbın parçası olduğunu varsayar. Belirsiz bir karakterin URL'nin bir parçası olarak yorumlanmasını istiyorsanız dize olarak sağlandığında \` character. For example, the literal URL
about:blankshould be escaped as
'about\:blank'` ile kod dışına alındığından emin olun.
Kalıbı kullanma
Bir URLPattern
oluşturduktan sonra bunu kullanmak için iki seçeneğiniz vardır. Hem test()
hem de exec()
yöntemi aynı girişi alır ve eşleşme olup olmadığını kontrol etmek için aynı algoritmayı kullanır ve yalnızca döndürülen değerleri birbirinden farklıdır. test()
, belirtilen giriş için eşleşme olduğunda true
değerini, aksi halde false
değerini döndürür.
exec()
, yakalama gruplarıyla birlikte eşleşme hakkında ayrıntılı bilgileri veya eşleşme yoksa null
değerini döndürür. Aşağıdaki örneklerde exec()
kullanımı gösterilmektedir ancak yalnızca basit bir boole döndürme değeri istiyorsanız bunlardan herhangi biriyle test()
değiştirebilirsiniz.
test()
ve exec()
yöntemlerini kullanmanın bir yolu dizeleri geçirmektir.
Oluşturucunun desteklediği gibi, tek bir dize sağlanırsa kaynak dahil olmak üzere tam URL olmalıdır. İki dize sağlanırsa ikinci dize bir 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, oluşturucunun desteklediği türden nesneyi aktarabilirsiniz. Bu tür nesneler, URL'nin yalnızca eşleştirmeyi önemsediğiniz bölümleri olarak ayarlanır.
const p = new URLPattern({pathname: '/foo/:image.jpg'});
const result = p.exec({pathname: '/foo/:image.jpg'});
// result will contain info about the successful match.
Joker karakter veya jeton içeren bir URLPattern
üzerinde exec()
kullandığınızda döndürülen değer, giriş URL'sindeki karşılık gelen değerlerin ne olduğu hakkında size bilgi verir. Böylece bu değerleri kendiniz ayrıştırma zahmetinden kurtulmuş olursunuz.
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()
öğesine bir URL dizesi ilettiğinizde, hangi bölümlerin modelin tüm gruplarıyla eşleştiğini bildiren bir değer alırsınız.
Döndürülen değer, URLPattern
bileşenlerine karşılık gelen özelliklere (ör. pathname
) sahiptir. Dolayısıyla, bir grup URLPattern
öğesinin pathname
bölümünün bir parçası olarak tanımlanmışsa eşleşmeler, döndürülen değerin pathname.groups
öğesinde bulunabilir. Eşleşmeler, karşılık gelen kalıbın anonim veya adlandırılmış grup olmasına bağlı olarak farklı şekilde temsil edilir.
Anonim bir kalıp eşleşmesine ilişkin değerlere erişmek için dizi dizinlerini kullanabilirsiniz.
Birden fazla anonim kalıp varsa 0
dizini, 1
ve sonraki kalıplar için kullanılan diğer dizinler en soldakiyle eşleşen değeri temsil eder.
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 karakterleri 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 de geçerlidir.Bir kalıp içindeki metin, söz konusu bileşenin URL kodlaması için kullanılan kurallara göre otomatik olarak kodlanır.
pathname
içindeki Unicode karakterleri yüzde kodlamalı olacaktır. Böylece/café
gibi birpathname
kalıbı, otomatik olarak/caf%C3%A9
şeklinde 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ı zorlaştırır ve güvenli değildir. Bir normal ifade grubundaki bir Unicode karakteriyle eşleştirmek istiyorsanız bunu,
café
ile eşleştirmek için(caf%C3%A9)
örneğinde olduğu gibi manuel olarak yüzde olarak kodlamanız gerekir.
URLPattern
, Unicode karakterlerini kodlamaya ek olarak URL normalleştirmesini de gerçekleştirir. Örneğin, pathname
bileşenindeki /foo/./bar
, eşdeğer /foo/bar
değerine daraltılmıştır.
Belirli bir giriş kalıbının nasıl normalleştirildiği konusunda şüpheye düşerseniz tarayıcınızın DevTools'nı kullanarak oluşturulan URLPattern
örneğini inceleyin.
Özet
Aşağıya yerleştirilen Arıza demosu, belirli kalıpları ağ isteklerine yanıt oluşturulabilecek eşzamansız işlevlerle eşleyerek bir Service Worker'ın fetch event handler
içinde yer alan temel URLPattern
kullanım alanını gösterir. Bu örnekteki kavramlar, sunucu tarafı veya istemci tarafında diğer yönlendirme senaryolarına da uygulanabilir.
Geri bildirim ve gelecek planları
URLPattern
için temel işlevler Chrome ve Edge'e ulaşmış olsa da bazı eklemeler yapılması planlanmaktadır. URLPattern
ürününün bazı yönleri hâlâ geliştirilme aşamasındadır ve belirli davranışlar hakkında hâlâ iyileştirilmesi gereken bazı açık sorular mevcuttur. URLPattern
ürününü denemenizi ve GitHub sorunu aracılığıyla geri bildirimlerinizi bizimle paylaşmanızı öneririz.
Şablon 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 değiştirildiği bir URL yolu için bir dize döndürür.
Gelecekte URLPattern'e bunu eklemeyi umuyoruz ancak ilk sürümün kapsamında değildir.
Gelecekteki web platformu özelliklerini etkinleştirme
URLPattern
ürününün web platformunun yerleşik bir parçası haline geldiği varsayıldığında, yönlendirme veya kalıp eşleştirmeden yararlanabilecek diğer özellikler, temel öğe olarak bunun üzerine inşa edilebilir.
Hizmet çalışanı kapsam kalıbı eşleşmesi, dosya işleyici olarak PWA'lar ve spekülatif önceden getirme gibi önerilen özellikler için URLPattern
kullanımıyla ilgili tartışmalar devam etmektedir.
Teşekkür
Tüm teşekkür listesi için orijinal açıklayıcı belgeye bakın.