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

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

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

  • سيتم ترميز النص الموجود داخل النمط تلقائيًا وفقًا لنفس القواعد المستخدمة لترميز عنوان 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 للميزات المقترَحة، مثل مطابقة أنماط نطاق الخدمة، تطبيقات الويب التقدّمية كمعالِجات ملفات، و التحميل المُسبَق التوقّعي.

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

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