يوفر URLPattern التوجيه إلى النظام الأساسي للويب.

نهج لتوحيد حالات الاستخدام الشائعة لمطابقة الأنماط

Jeff Posnick

الخلفية

ويعدّ التوجيه جزءًا أساسيًا من كل تطبيق ويب. في الأساس، يتضمن التوجيه أخذ عنوان 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 URLabout: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 válida على المجموعات المُسمّاة.

• سيتم ترميز النص ضمن النمط تلقائيًا وفقًا للقواعد نفسها المستخدَمة لترميز عنوان URL لهذا المكوّن المحدّد. سيتم ترميز أحرف Unicode بالتنسيق ‎% في pathname، وسيتم تلقائيًا تحويل نمط pathname مثل /café إلى /caf%C3%A9. يتم ترميز أحرف Unicode في hostname تلقائيًا باستخدام Punycode بدلاً من الترميز باستخدام النسبة المئوية.

• يجب أن تحتوي مجموعات التعبيرات العادية على أحرف ASCII فقط. تجعل بنية التعبير العادي عملية ترميز أحرف Unicode في هذه المجموعات تلقائيًا صعبة وغير آمنة. إذا كنت تريد مطابقة حرف Unicode في مجموعة تعبير عادي، عليك ترميزه يدويًا باستخدام النسبة المئوية، مثل (caf%C3%A9) لمطابقة café.

بالإضافة إلى ترميز أحرف Unicode، تُجري URLPattern أيضًا عملية تسويف عناوين URL. على سبيل المثال، يتم تجميع العنصر /foo/./bar في العنصر pathname ليصبح العنصر /foo/bar المكافئ.

إذا كانت لديك شكوك حول كيفية تسويّة نمط إدخال معيّن، يمكنك فحص مثيل URLPattern الذي تم إنشاؤه باستخدام أدوات المطوّر DevTools في المتصفّح.

خلاصة ما سبق ذكره

يوضّح الإصدار التجريبي من Glitch المضمّن أدناه حالة استخدام أساسية URLPattern داخل fetch event handler عامل الخدمة، ويتمثل ذلك في ربط أنماط معيّنة بوظائف غير متزامنة يمكنها إنشاء URLPatternجواب لطلبات الشبكة. يمكن تطبيق المفاهيم الواردة في هذا المثال على سيناريوهات التوجيه الأخرى أيضًا، سواء من جهة الخادم أو من جهة العميل.

الملاحظات والخطط المستقبلية

على الرغم من أنّ الوظائف الأساسية لخدمة URLPattern أصبحت متاحة في Chrome وEdge، هناك إضافات مخطّط لها. لا تزال بعض جوانب URLPattern قيد التطوير، وهناك عدد من الأسئلة المفتوحة حول سلوكيات معيّنة قد لا تزال بحاجة إلى تحسين. ننصحك بتجربة URLPattern وتقديم أي ملاحظات من خلال إبلاغ عن مشكلة في GitHub.

إتاحة استخدام النماذج

توفّر مكتبة path-to-regexp دالة compile() function تعكس سلوك التوجيه بفعالية. تأخذ دالة compile() نمطًا وقيمًا للعناصر النائبة للرموز المميّزة، وتُرجِع سلسلة لمسار عنوان URL تم استبدال هذه القيم فيه.

نأمل أن تتم إضافة ذلك إلى URLPattern في المستقبل، ولكنّ ذلك ليس ضمن نطاق الإصدار الأولي.

تفعيل ميزات قاعدة الويب المستقبلية

بافتراض أنّ URLPattern يصبح جزءًا أساسيًا من منصة الويب، يمكن أن تستند إليها الميزات الأخرى التي يمكن أن تستفيد من التوجيه أو مطابقة الأنماط.

هناك مناقشات جارية حول استخدام URLPattern للميزات المقترَحة، مثل مطابقة أنماط نطاق الخدمة، تطبيقات الويب التقدّمية كمعالِجات ملفات، و التحميل المُسبَق التوقّعي.

الشكر والتقدير

يمكنك الاطّلاع على المستند الأصلي الذي يوضّح آلية عمل الميزة للحصول على قائمة كاملة بالجهات التي تمّ الشكر لها.