منهج لتوحيد حالات الاستخدام الشائعة لمطابقة الأنماط
الخلفية
ويعدّ التوجيه جزءًا أساسيًا من كل تطبيق ويب. في الأساس، يتضمن التوجيه أخذ عنوان URL وتطبيق بعض مطابقة الأنماط أو منطق آخر خاص بالتطبيق عليه، ثم عرض محتوى الويب استنادًا إلى النتيجة عادةً. ويمكن تنفيذ التوجيه بعدة طرق: أحيانًا يكون الرمز قيد التشغيل على خادم يعيّن مسارًا للملفات على القرص، أو منطقًا في تطبيق من صفحة واحدة ينتظر التغييرات في الموقع الحالي وينشئ جزءًا من DOM لعرضه.
على الرغم من عدم توفّر معيار واحد ومحدد، اتّجه مطوّرو الويب
نحو بنية نحوية شائعة للتعبير عن أنماط توجيه عناوين URL التي تتشارك الكثير من
الشائعات مع
regular expressions
،
ولكن مع بعض الإضافات الخاصة بالنطاق، مثل الرموز المميّزة لمطابقة أجزاء المسار.
تستخدم أُطر العمل الشائعة من جهة الخادم، مثل
Express و
Ruby on Rails، هذه البنية (أو
شيء قريب جدًا منها)، ويمكن لمطوّري JavaScript استخدام وحدات مثل
path-to-regexp
أو
regexpparam
لإضافة
هذا المنطق إلى رموزهم البرمجية.
URLPattern
هي إضافة إلى منصة الويب تستند إلى الأساس الذي أنشأته
هذه الأطر. ويهدف إلى توحيد بنية نمط التوجيه،
بما في ذلك إتاحة العناصر النائبة ومجموعات الرموز المميّزة المُسمّاة ومجموعات التعبيرات العادية
ومُعدِّلات المجموعات. يمكن لعناصر URLPattern
التي تم إنشاؤها باستخدام هذه البنية
تنفيذ مهام التوجيه الشائعة، مثل المطابقة مع عناوين URL الكاملة أو عنوان URL
pathname
،
وعرض معلومات عن مطابقات الرمز المميّز والمجموعة.
من المزايا الأخرى لتوفير مطابقة عناوين URL مباشرةً في منصة الويب هي أنّه يمكن بعد ذلك مشاركة بنية شائعة مع واجهات برمجة تطبيقات أخرى تحتاج أيضًا إلى المطابقة مع عناوين URL.
توافُق المتصفّح ورموز polyfill
يكون URLPattern
مفعَّلاً تلقائيًا في الإصدار 95 من Chrome وEdge والإصدارات الأحدث.
توفّر مكتبة
urlpattern-polyfill
طريقة لاستخدام واجهة URLPattern
في المتصفحات
أو البيئات التي لا تتضمّن دعمًا مضمّنًا، مثل Node. إذا
كنت تستخدم رمز polyfill، تأكَّد من استخدام ميزة رصد الميزات لضمان
عدم تحميله إلا إذا كانت البيئة الحالية لا تتيح ذلك. بخلاف ذلك،
ستفقد إحدى المزايا الرئيسية URLPattern
: وهي أنّه
لا يلزم بيئات الدعم تنزيل رمز إضافي وتحليله لكي تتمكّن
من استخدامه.
if (!(globalThis && 'URLPattern' in globalThis)) {
// URLPattern is not available, so the polyfill is needed.
}
التوافق مع البنية
إنّ الفلسفة الأساسية التي نتّبعها في URLPattern
هي تجنُّب إعادة الابتكار. إذا كنت familiarizado
مع بنية التوجيه المستخدَمة في Express أو Ruby on Rails، لن تحتاج
إلى تعلُّم أي شيء جديد. ونظرًا إلى الاختلافات الطفيفة بين بناء الجملة في مكتبات التوجيه الشائعة، كان لا بدّ من اختيار أحد العناصر باعتباره البنية الأساسية، وقرّر مصمِّمو URLPattern
استخدام بنية النمط من path-to-regexp
(وليس سطح واجهة برمجة التطبيقات الخاص بها) كنقطة بداية.
تم اتخاذ هذا القرار بعد استشارة وثيقة مع المشرف الحالي لـ
path-to-regexp
.
إنّ أفضل طريقة للتعرّف على جوهر البنية المتوافقة هي
الاطّلاع على
المستندات الخاصة بملف
path-to-regexp
. يمكنك قراءة المستندات المخصّصة للنشر على MDN في مكانها الحالي على GitHub.
ميزات إضافية
تُعد بنية URLPattern
مجموعة شاملة لما يتوافق مع path-to-regexp
، وذلك لأنّ URLPattern
يتيح ميزة غير شائعة بين مكتبات التوجيه، وهي مطابقة المصادر، بما في ذلك أحرف البدل في أسماء المضيفين. تتعامل معظم مكتبات التوجيه الأخرى فقط مع
pathname،
وفي بعض الأحيان مع
البحث أو
التجزئة في
عنوان URL. ولا يحتاجون أبدًا إلى التحقّق من جزء المصدر في عنوان URL، لأنّه لا يتم استخدامه إلا
لتوجيه المصدر نفسه داخل تطبيق ويب مكتفٍ ذاتيًا.
وسيؤدّي أخذ الأصول في الاعتبار إلى فتح الباب أمام حالات استخدام إضافية، مثل توجيه الطلبات من مصادر متعددة داخل معالِج أحداث fetch
الخاص بعامل الخدمات. إذا كنت تُوجّه عناوين URL من المصدر نفسه فقط، يمكنك
تجاهُل هذه الميزة الإضافية بشكلٍ فعّال واستخدام URLPattern
مثل
المكتبات الأخرى.
أمثلة
إنشاء النمط
لإنشاء URLPattern
، مرِّر إلى عنصر الإنشاء إما سلاسل أو عنصر يحتوي على
سمات تحتوي على معلومات عن النمط المطلوب مطابقته.
يقدّم تمرير عنصر إمكانية التحكّم الأكثر وضوحًا في النمط الذي سيتم استخدامه لمحاولة مطابقة كل مكوّن من مكوّنات عنوان URL. في أبسط أشكالها، يمكن أن يبدو هذا على النحو التالي:
const p = new URLPattern({
protocol: 'https',
username: '',
password: '',
hostname: 'example.com',
port: '',
pathname: '/foo/:image.jpg',
search: '*',
hash: '*',
});
لن تتطابق سلسلة فارغة لموقع إلكتروني إلا إذا لم يتم ضبط الجزء المناظر
من عنوان URL. ستطابق العلامة النائبة *
أي قيمة لجزء معيّن
من عنوان URL.
يوفّر أداة الإنشاء العديد من الاختصارات لتسهيل الاستخدام. إنّ حذف
search
وhash
أو أيّ سمات أخرى تمامًا يعادل ضبطهما على العنصر النائب
'*'
. يمكن تبسيط المثال أعلاه على النحو التالي:
const p = new URLPattern({
protocol: 'https',
username: '',
password: '',
hostname: 'example.com',
port: '',
pathname: '/foo/:image.jpg',
});
كاختصار إضافي، يمكن
تقديم كل المعلومات عن المصدر في موقع واحد، وهو baseURL
، ما يؤدي إلى
const p = new URLPattern({
pathname: '/foo/:image.jpg',
baseURL: 'https://example.com',
});
تفترض كل هذه الأمثلة أنّ حالة الاستخدام تتضمن مطابقة المصادر. إذا كان
اهتمامك منصبًّا فقط على المطابقة في الأجزاء الأخرى من عنوان URL، باستثناء
المصدر (كما هو الحال في العديد من سيناريوهات توجيه
المصدر الواحد "التقليدية")، يمكنك حذف معلومات المصدر بالكامل، وتقديم
بعض التركيبات من السمات pathname
وsearch
وhash
فقط. كما في السابق،
سيتم التعامل مع السمات المُهمَلة كما لو تم ضبطها على *
نمط الحرف البديل.
const p = new URLPattern({pathname: '/foo/:image.jpg'});
كبديل لتمرير عنصر إلى الدالة الإنشائية، يمكنك تقديم
سلسلة واحدة أو سلسلتَين. في حال تقديم سلسلة واحدة، يجب أن تمثّل ملفًا كاملاً
لعنوان URL، بما في ذلك معلومات النمط المستخدَمة لمطابقة المصدر. إذا قدمت
سلسلتَين، يتم استخدام السلسلة الثانية كbaseURL
، ويتم اعتبار السلسلة
الأولى نسبةً إلى تلك القاعدة.
سواء تم تقديم سلسلة واحدة أو سلسلتَين، سيحلّل URLPattern
نمط عنوان URL الكامل، ويقسّمه إلى مكوّنات عنوان URL، ويربط كل جزء
من النمط الأكبر بالمكوّن المقابل. وهذا يعني أنّه في الأساس، يتم تمثيل كل URLPattern
تم إنشاؤه باستخدام سلاسل بطريقة مماثلة لURLPattern
مكافئ تم إنشاؤه باستخدام عنصر. إنّ باني ملف برمجي
للسلاسل هو اختصار فقط، لأولئك الذين يفضّلون واجهة
أقل تفصيلاً.
const p = new URLPattern('https://example.com/foo/:image.jpg?*#*');
عند استخدام سلاسل لإنشاء URLPattern
، هناك بعض التحذيرات التي يجب أخذها في الاعتبار.
إنّ حذف خاصية عند استخدام عنصر لإنشاء URLPattern
هو
معادل لتقديم علامة *
بدلاً من تلك السمة. عند تحليل نمط سلسلة عنوان URL بالكامل، إذا لم تتوفّر قيمة لأحد مكوّنات عنوان URL، يتم التعامل معه كما لو تم ضبط سمة المكوّن على ''
، ولن يتطابق إلا عندما يكون هذا المكوّن فارغًا.
عند استخدام سلاسل، عليك تضمين العناصر النائبة صراحةً إذا أردت
استخدامها في URLPattern
التي تم إنشاؤها.
// 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',
});
يجب أن تدرك أيضًا أن تحليل نمط سلسلة إلى مكوناته
من المحتمل أن يكون غامضًا. هناك أحرف، مثل :
، يمكن العثور عليها في عناوين URL،
ولكن لها أيضًا معنى خاص في بنية مطابقة الأنماط. لتجنُّب هذا
التفاهم، يفترض مُنشئ URLPattern
أنّ أيًا من هذه الأحرف
الخاصة هو جزء من نمط، وليس جزءًا من عنوان URL. إذا أردت تفسير رمز
غير واضح على أنّه جزء من عنوان URL، احرص على تشفيره باستخدام \` character. For example, the literal URL
about:blankshould be escaped as
'about\:blank'` عند تقديمه كسلسلة.
استخدام النمط
بعد إنشاء URLPattern
، لديك خياران لاستخدامه. تستخدم الطريقتان
test()
وexec()
الإدخال نفسه ويستخدمان الخوارزمية نفسها للبحث عن مطابقة، وتختلفان فقط في القيمة المعروضة. test()
تعرض القيمة true
عند تطابق الإدخال المحدّد، وfalse
في حال عدم التطابق.
تعرِض دالة exec()
معلومات مفصّلة عن المطابقة مع مجموعات الالتقاط،
أو null
في حال عدم توفّر مطابقة. توضِّح الأمثلة التالية استخدام
exec()
، ولكن يمكنك استبدال test()
بأيّ منها إذا كنت تريد فقط
قيمة منطقية بسيطة.
إنّ إحدى طرق استخدام الطريقتَين test()
وexec()
هي من خلال إدخال سلاسل.
على غرار ما تتيحه دالة الإنشاء، في حال توفير سلسلة واحدة، يجب أن تكون عنوان URL كاملاً، بما في ذلك المصدر. في حال تقديم سلسلةَين، تتم معاملة
السلسلة الثانية كقيمة baseURL
، ويتم تقييم السلسلة الأولى
بالنسبة إلى هذه القاعدة.
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.
بدلاً من ذلك، يمكنك تمرير النوع نفسه من الكائنات التي يقبلها المُنشئ، مع السمات التي تم ضبطها على أجزاء عنوان URL التي تهمّك مطابقتها فقط.
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()
في URLPattern
يحتوي على أحرف بدل أو رموز مميزة، ستمنحك القيمة المعروضة معلومات عن القيم المقابلة في عنوان URL الذي أدخلته. ويمكن أن تجنّبك هذه الطريقة عناء تحليل هذه القيمة
بنفسك.
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'
المجموعات المجهولة والمجموعات المُسمّاة
عند تمرير سلسلة عنوان URL إلى exec()
، ستحصل على قيمة تُعلمك بالأجزاء التي تطابقت مع جميع مجموعات النمط.
تحتوي القيمة المعروضة على سمات تتوافق مع مكوّنات
URLPattern
، مثل pathname
. وبالتالي، إذا تمّ تعريف مجموعة كجزء من القسم
pathname
من URLPattern
، يمكن العثور على المطابقات في pathname.groups
لقيمة الإخراج. يتم تمثيل التطابقات بشكل مختلف اعتمادًا على
ما إذا كان النمط المقابل عبارة عن مجموعة مجهولة أو المسماة.
يمكنك استخدام فهارس الصفيف للوصول إلى القيم من أجل مطابقة نمط مجهولة.
إذا كانت هناك أنماط مجهولة متعددة، سيمثّل الفهرس 0
القيمة المطابقة
للنمط الأيمن، مع استخدام 1
والفهارس الأخرى للأنماط التالية.
عند استخدام مجموعات مُسمّاة في نمط، سيتم عرض المطابقات كسمات تتطابق أسماؤها مع كل اسم مجموعة.
دعم Unicode وتحويل النص إلى نص عادي
يتيح URLPattern
استخدام أحرف Unicode بعدة طرق مختلفة.
يمكن أن تحتوي المجموعات المُسمّاة، مثل
:café
، على أحرف Unicode. تنطبق القواعد المستخدَمة في معرّفات JavaScript الصالحة على المجموعات المُسمّاة.سيتم ترميز النص الموجود داخل النمط تلقائيًا وفقًا لنفس القواعد المستخدمة لترميز عنوان URL لهذا المكون تحديدًا. سيتم ترميز أحرف Unicode بنسبة مئوية داخل
pathname
، وبالتالي سيتم تطبيع نمطpathname
مثل/café
إلى/caf%C3%A9
تلقائيًا. ويتم ترميز أحرف يونيكود فيhostname
تلقائيًا باستخدام Punycode، بدلاً من ترميز نسبة مئوية.يجب أن تحتوي مجموعات التعبيرات العادية على أحرف ASCII فقط. تجعل بنية التعبير العادي عملية ترميز أحرف Unicode في هذه المجموعات تلقائيًا صعبة وغير آمنة. إذا كنت تريد مطابقة حرف Unicode في مجموعة تعبير عادي، عليك ترميزه باستخدام النسبة المئوية يدويًا، مثل
(caf%C3%A9)
لمطابقةcafé
.
بالإضافة إلى ترميز أحرف يونيكود، تُجري URLPattern
أيضًا
تسوية عناوين URL. على سبيل المثال، يتم تجميع العنصر /foo/./bar
في العنصر pathname
ليصبح العنصر /foo/bar
المكافئ.
إذا كانت لديك شكوك حول كيفية تسويّة نمط إدخال معيّن، يمكنك فحص مثيل URLPattern
الذي تم إنشاؤه باستخدام أدوات المطوّر DevTools في المتصفّح.
خلاصة ما سبق ذكره
يوضّح الإصدار التجريبي من Glitch المضمّن أدناه حالة استخدام أساسية URLPattern
داخل
fetch event handler
للخدمة، ويتمثل ذلك في ربط أنماط معيّنة بوظائف غير متزامنة يمكنها إنشاء
استجابة لطلبات الشبكة. يمكن تطبيق المفاهيم الواردة في هذا المثال على سيناريوهات توجيه أخرى أيضًا،
سواء من جهة الخادم أو من جهة العميل.
الملاحظات والخطط المستقبلية
على الرغم من أنّ الوظائف الأساسية لتطبيق URLPattern
أصبحت متاحة في Chrome وEdge،
هناك إضافات مخطّط لها. لا تزال بعض جوانب URLPattern
قيد التطوير،
وهناك عدد من
الأسئلة المفتوحة
حول سلوكيات معيّنة قد لا تزال بحاجة إلى تحسين. ننصحك بتجربة
URLPattern
وتقديم أي ملاحظات من خلال
إبلاغ عن مشكلة في GitHub.
إتاحة استخدام النماذج
توفّر مكتبة path-to-regexp
دالة
compile() function
تعكس سلوك التوجيه بفعالية. تأخذ دالة compile()
نمطًا وقيمًا للعناصر النائبة للرموز المميّزة، وتُرجِع سلسلة لمسار
عنوان URL تم استبدال هذه القيم فيه.
نأمل أن تتم إضافة ذلك إلى URLPattern في المستقبل، ولكنّ ذلك ليس ضمن نطاق الإصدار الأولي.
تفعيل ميزات قاعدة الويب المستقبلية
بافتراض أنّ URLPattern
يصبح جزءًا أساسيًا من منصة الويب، يمكن أن تستند إليها
الميزات الأخرى التي يمكن أن تستفيد من التوجيه أو مطابقة الأنماط.
هناك مناقشات جارية حول استخدام URLPattern
للميزات المقترَحة، مثل
مطابقة أنماط نطاق الخدمة،
تطبيقات الويب التقدّمية كمعالِجات ملفات،
و
التحميل المُسبَق التوقّعي.
الشكر والتقدير
يمكنك الاطّلاع على مستند الشرح الأصلي للحصول على قائمة كاملة بالتقديرات.