تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

تم اتّخاذ هذا القرار بعد استشارة دقيقة مع المشرف الحالي على path-to-regexp.

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

ميزات إضافية

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

دعم يونيكود وتسويته

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

يمكن أن تحتوي المجموعات المُعنونة، مثل :café، على أحرف يونيكود. وتنطبق القواعد المستخدمة لمعرّفات JavaScript الصالحة على المجموعات المُعنونة.
وسيتم تلقائيًا ترميز النص الموجود داخل نمط وفقًا للقواعد نفسها المستخدمة في تشفير عنوان URL لهذا المكون المحدد. سيتم ترميز أحرف يونيكود في pathname، لذا يتم ضبط نمط pathname مثل /café إلى /caf%C3%A9 تلقائيًا. يتم تلقائيًا ترميز أحرف يونيكود في hostname باستخدام Punycode، بدلاً من الترميز بنسبة مئوية.
يجب أن تحتوي مجموعات التعبير العادي على أحرف ASCII فقط. بنية التعبير العادي تجعل من الصعب وغير الآمن ترميز أحرف يونيكود تلقائيًا في هذه المجموعات. إذا كنت تريد مطابقة حرف 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 للميزات المقترَحة، مثل مطابقة نمط مشغّل الخدمات وتطبيقات PWA كمعالجات للملفات والجلب المُسبَق المبني على توقُّع.

شكر وتقدير

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