أصبح URLPattern الآن خطًا أساسيًا متاحًا حديثًا | مدونة | web.dev

تاريخ النشر: 20 أكتوبر 2025

إذا سبق لك إنشاء ميزة تحتاج إلى التفاعل مع تغييرات عنوان URL، فمن المحتمل أنك وجدت نفسك تكتب تعبيرات عادية معقدة أو تستعين بمكتبة خارجية للتوجيه. توفر واجهة برمجة تطبيقات نمط URL، التي أصبحت الآن Baseline Newly، حلاً قياسيًا وقويًا وقابلاً للتشغيل البيني لهذا التحدي المشترك.

فهو يتيح لك مطابقة عناوين URL مع بنية نمطية مألوفة، مما يجعل تحليل عناوين URL واستخراج البيانات باستخدام أساليب مثل ‎.exec() و.test()‎ أقل صعوبة بكثير.

const pattern = new URLPattern( pathname: "/products/:id" );
console.log(pattern.test("https://example.com/products/123")); // true

تتوفر وظيفة واجهة برمجة تطبيقات نمط URL في URLPattern واجهة. في هذا المنشور، سترى كيف يمكن أن يساعد استخدامه في تحسين قاعدة التعليمات البرمجية الخاصة بك عندما تواجه بعض التحديات الشائعة.

مطابقة نمط URL الأساسي

قبل توفر واجهة برمجة التطبيقات لنمط عنوان URL، كانت مطابقة نمط عنوان URL الأساسي تعني غالبًا الجمع بين الأنماط الأقدم URL واجهة لتحليل عنوان URL، ثم تطبيق تعبير عادي منفصل – غالبًا ما يكون معقدًا – على .pathname خاصية لاختبار المباراة.

const url = new URL(location.href);
const pathRegex = /^\/users\/([a-zA-Z0-9]+)\/?$/;
const isMatch = pathRegex.test(url.pathname);

مع URLPattern، تتطلب هذه المهمة الآن تعليمات برمجية أقل، كما أنها أسهل في القراءة:

const pattern = new URLPattern( pathname: "/users/:id" );
const isMatch = pattern.test(location.href);

حالة استخدام شائعة أخرى لـ URLPattern هو عندما تحتاج إلى استخراج المعلمات الديناميكية من عنوان URL. في الماضي، كان يتم الاعتماد غالبًا على مجموعات التقاط التعبير العادي المرقمة، وهي موضعية ومجهولة. كان عليك الوصول إلى المعلمات من خلال فهرس الصفيف الخاص بها (result[1], result[2])، وهو أمر هش عندما يتغير ترتيب مجموعات الالتقاط.

const pathRegex = /^\/books\/([a-z]+)\/(\d+)\/?$/;
const result = pathRegex.exec("/books/classics/12345");

// `result` is an array:
// ["/books/classics/12345", "classics", "12345"]
const category = result ? result[1] : null;
const bookId = result ? result[2] : null;

URLPattern تقوم بإرجاع كائن مجموعات منظمة، ويضم المعلمات المسماة. تتوافق الأسماء مباشرة مع المفاتيح الموجودة في الكائن الناتج، مما يؤدي إلى تعليمات برمجية واضحة وقوية.

// Pattern to match /books/<category>/<id>
const pattern = new URLPattern( pathname: "/books/:category/:id" );
const result = pattern.exec("/books/classics/12345");

// `result.pathname.groups` will return:
//  category: "classics", id: "12345" 
const  category, id: bookId  = result.pathname.groups;

إنشاء مباريات متعددة الأجزاء

الطريقة النموذجية لإنشاء مطابقات متعددة الأجزاء لعنوان URL في الماضي هي استخدام URL منشئ للحصول على الأجزاء الفردية (hostname, pathname)، ثم قم بإجراء عمليات فحص منفصلة أو تعبيرات عادية على كل منها.

const url = new URL(req.url);

if (url.hostname.endsWith(".cdn.com") && url.pathname.startsWith("/images/")) 
  // Do something

URLPattern يدعم هذا محليًا، مع عناصر تحكم يمكن التنبؤ بها:

const pattern = new URLPattern( hostname: "*.cdn.com", pathname: "/images/*" );

if (pattern.test(req.url)) 
  // Do something

تبعيات المشروع

قبل ذ لك URLPattern، غالبًا ما يتم تفويض معالجة سلاسل URL إلى مكتبة خارجية لحزمة التطبيق للتعامل مع منطق التوجيه بقوة.

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

الاستخدام التفصيلي

فائدة URLPattern هو في قدرته على خدمة حالات الاستخدام الأساسية والمتقدمة. يمكنك البدء بمطابقة مسار أبسط وإضافة ميزات أكثر قوة حسب حاجتك إليها. فيما يلي بعض السيناريوهات الشائعة.

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

إحدى حالات الاستخدام الشائعة لمطابقة نمط عنوان URL هي التوجيه من جانب العميل. URLPattern يجعلها نظيفة للغاية. يمكنك التحقق مما إذا كان عنوان URL يتطابق مع النمط .test()واستخراج الأجزاء الديناميكية باستخدام .exec().

const pattern = new URLPattern( pathname: "/products/:category/:id" );

// Use .test() for a boolean check
console.log(pattern.test("https://example.com/products/electronics/123")); // → true
console.log(pattern.test("https://example.com/blog")); // → false

// Use .exec() to extract the named groups
const result = pattern.exec("https://example.com/products/electronics/123");

if (result) 
  const  category, id  = result.pathname.groups;
  console.log(`Loading product $id from the $category category.`); // → "Loading product 123 from the electronics category."

كيفية مطابقة النطاقات الفرعية والمزيد

على عكس العديد من مكتبات التوجيه، URLPattern هو مُطابق كامل لعنوان URL. يعد هذا مثاليًا للتطبيقات التي تتصرف بشكل مختلف بناءً على اسم المضيف، مثل توجيه مكالمات واجهة برمجة التطبيقات (API) إلى نطاق فرعي محدد.

هنا، يتم إنشاء نمط يطابق الطلبات فقط api المجال الفرعي ومسار محدد.

const apiPattern = new URLPattern(
  hostname: ":subdomain.myapp.com",
  pathname: "/api/v:version/*"
);

const result = apiPattern.exec("https://api.myapp.com/api/v2/users");

if (result) 
  const  subdomain, version  = result.hostname.groups;
  console.log(`Request to the '$subdomain' subdomain, API version $version.`); // → "Request to the 'api' subdomain, API version 2."

أحرف البدل والتعبيرات العادية

عندما تحتاج إلى قدر أكبر من المرونة مما يمكن أن توفره المجموعات المسماة وحدها، URLPattern يدعم أحرف البدل (*) وتضمين التعبيرات العادية مباشرة في أنماطك للتحكم بشكل أفضل.

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

// :userId(\\d+) - Matches a named group 'userId', but only if it contains one or more digits.
// * - A wildcard that matches any character until the next separator (like a '.')
const assetPattern = new URLPattern(
  pathname: "/users/:userId(\\d+)/assets/*.(jpg);

const result1 = assetPattern.exec("/users/123/assets/profile.jpg");
console.log(result1?.pathname.groups.userId); // → "123" (It matches)

const result2 = assetPattern.exec("/users/abc/assets/avatar.png");
console.log(result2); // → null (It fails because 'abc' is not a digit)

مثال عملي: التوجيه في عامل الخدمة

يعد عمال الخدمة حالة استخدام مثالية لـ URLPattern. يمكنك الاعتراض بشكل نظيف fetch الطلبات وتطبيق استراتيجيات تخزين مؤقت مختلفة دون الحاجة إلى استخدام تعبيرات عادية أو عبارات شرطية فوضوية url.includes().

// Inside your service worker file:

const IMAGE_ASSETS = new URLPattern( pathname: "/images/*" );
const API_CALLS = new URLPattern( pathname: "/api/*" );

self.addEventListener("fetch", (event) => 
  const url = event.request.url;

  if (IMAGE_ASSETS.test(url)) 
    // Apply a cache-first strategy for images
    event.respondWith(cacheFirst(event.request));
   else if (API_CALLS.test(url)) 
    // Apply a network-first strategy for API calls
    event.respondWith(networkFirst(event.request));
  
);

لسنوات، كان توجيه عنوان URL في المتصفح يعني تعبيرات عادية معقدة أو مكتبات تابعة لجهات خارجية. URLPattern يغير ذلك من خلال تقديم حل قوي وقابل للتكيف وموحد مدمج مباشرة في المتصفح.

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

تمتلئ واجهة برمجة تطبيقات نمط URL بميزات أكثر مما يمكن تغطيته هنا. للتعمق أكثر والاطلاع على المرجع الكامل لجميع إمكانياته، راجع الوثائق الشاملة على MDN Web Docs.