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

Jeff Posnick

تاريخ النشر: 22 تموز (يوليو) 2021

تُعدّ عملية التوجيه جزءًا أساسيًا من كل تطبيق ويب. في جوهرها، تتلقّى عملية التوجيه عنوان URL، وتطبّق عليه مطابقة الأنماط أو منطقًا آخر خاصًا بالتطبيق، ثم تعرض عادةً محتوى الويب استنادًا إلى النتيجة. يمكن تنفيذ التوجيه بعدة طرق:

رمز الخادم الذي يربط المسارات بالملفات على القرص
منطق في تطبيق من صفحة واحدة ينتظر إجراء تغييرات على الموقع الجغرافي الحالي، ثم ينشئ ويعرض جزءًا مطابقًا من DOM.

مع أنّه ليس هناك معيار نهائي واحد، إلا أنّ مطوّري الويب يميلون إلى استخدام صيغة شائعة للتعبير عن أنماط توجيه عناوين URL تتشارك الكثير مع regular expressions، ولكن مع بعض الإضافات الخاصة بالمجال، مثل الرموز المميزة لمطابقة أجزاء المسار. تستخدم أُطر العمل الشائعة من جهة الخادم، مثل Express وRuby on Rails، هذه البنية (أو بنية مشابهة جدًا)، ويمكن لمطوّري JavaScript استخدام وحدات مثل path-to-regexp أو regexpparam لإضافة هذه المنطق إلى الرمز الخاص بهم.

URLPattern هي إضافة إلى منصة الويب تستند إلى الأساس الذي تم إنشاؤه بواسطة أُطر العمل هذه. والهدف من ذلك هو توحيد صيغة نمط التوجيه، بما في ذلك إتاحة أحرف البدل ومجموعات الرموز المميزة المسماة ومجموعات التعبيرات العادية ومعدّلات المجموعات. يمكن أن تنفّذ مثيلات URLPattern التي تم إنشاؤها باستخدام هذه البنية مهام توجيه شائعة، مثل مطابقة عناوين URL الكاملة أو pathname، وإرجاع معلومات حول الرموز المميزة والمطابقات مع المجموعات.

من المزايا الأخرى لتوفير ميزة مطابقة عناوين URL مباشرةً في منصة الويب إمكانية مشاركة بنية مشتركة مع واجهات برمجة التطبيقات الأخرى التي تحتاج أيضًا إلى مطابقة عناوين URL.

المتصفّحات المتوافقة وPolyfills

يتم تفعيل 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 في تجنُّب إعادة الاختراع. إذا كنت معتادًا على بنية التوجيه المستخدَمة في Express أو Ruby on Rails، لن تحتاج إلى تعلّم أي شيء جديد. ولكن نظرًا إلى الاختلافات الطفيفة بين بنى الجمل في مكتبات التوجيه الشائعة، كان لا بد من اختيار بنية جملة أساسية، وقد قرّر مصمّمو URLPattern استخدام بنية الجملة النموذجية من path-to-regexp (مع أنّهم لم يستخدموا مساحة واجهة برمجة التطبيقات) كنقطة بداية.

تم اتّخاذ هذا القرار بعد التشاور بشكل وثيق مع المسؤول الحالي عن صيانة path-to-regexp.

وأفضل طريقة للتعرّف على أساسيات الصيغة المتوافقة هي الرجوع إلى المستندات الخاصة بـ path-to-regexp. يمكنك قراءة المستندات المخصّصة للنشر على MDN في موقعها الحالي على GitHub.

ميزات إضافية

بما أنّ URLPattern تتوافق مع ميزة غير شائعة بين مكتبات التوجيه، وهي مطابقة المصادر، بما في ذلك أحرف البدل في أسماء المضيفين، فإنّ بنية URLPattern هي مجموعة فرعية من البنية التي تتوافق معها path-to-regexp. تتعامل معظم مكتبات التوجيه الأخرى مع 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',
});

ملاحظة: عند تمرير baseURL إلى الدالة الإنشائية، يتم التعامل مع أي جوانب من عنوان URL لم يتم توفيرها كما لو تم ضبطها على سلسلة فارغة، وليس كحرف بدل '*'. على سبيل المثال، سيؤدي new URLPattern({baseURL: 'https://example.com/'}) إلى إنشاء URLPattern مع ضبط search وhash وسمات أخرى غير محدّدة على ''.

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

عند استخدام مجموعات مسماة في نمط، يتم عرض التطابقات كسمات تتوافق أسماؤها مع اسم كل مجموعة.

ملاحظة: إذا كنت على دراية بطريقة exec() للكائن RegExp، ستبدو القيم المعروضة من طريقة URLPattern.exec() مشابهة جدًا عندما يتعلق الأمر بتمثيل المجموعات المجهولة والمسمّاة.

التوافق مع Unicode والتسوية

تتيح URLPattern استخدام أحرف Unicode بعدة طرق مختلفة.

يمكن أن تحتوي المجموعات المسماة، مثل :café، على أحرف Unicode. تنطبق القواعد المستخدَمة في معرّفات JavaScript الصحيحة على المجموعات المسماة.
سيتم تلقائيًا ترميز النص ضمن نمط معيّن وفقًا للقواعد نفسها المستخدَمة في ترميز عنوان 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 أصبحت متاحة على Chrome وEdge، إلا أنّه من المخطط إضافة المزيد من الميزات. لا تزال بعض جوانب URLPattern قيد التطوير، وهناك عدد من الأسئلة المفتوحة حول سلوكيات معيّنة قد يتم تحسينها. ننصحك بتجربة URLPattern ومشاركة أي ملاحظات عبر مشكلة في GitHub.

التوافق مع النماذج

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

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

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

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

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

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

يوفر URLPattern التوجيه إلى النظام الأساسي للويب. تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المتصفّحات المتوافقة وPolyfills

توافق البنية

ميزات إضافية

أمثلة

إنشاء النمط

استخدام النقش

المجموعات المجهولة والمجموعات المُسمّاة

التوافق مع Unicode والتسوية

وضع كل العناصر معًا

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

التوافق مع النماذج

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

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