encodeURIComponent مقابل encodeURI: متى تستخدم كلًّا منهما

دالتا ترميز الروابط في جافاسكريبت

توفر جافاسكريبت دالتين مدمجتين لترميز الروابط (URL encoding): encodeURI() و encodeURIComponent(). ورغم أنهما قد تبدوان متشابهتين، فإن استخدام الدالة الخاطئة قد يؤدي إلى روابط معطوبة، أو ثغرات أمنية، أو تلف في البيانات. لذا فإن فهم الفرق بينهما أمر بالغ الأهمية لمطوري الويب.

‏encodeURI() — لترميز الروابط الكاملة

صُممت دالة encodeURI() لترميز رابط URI كامل. فهي تُرمِّز جميع الأحرف باستثناء تلك التي تحمل معنى خاصًا في بنية الرابط. وعلى وجه التحديد، فإنها لا تُرمِّز:

• الأحرف المحجوزة (Reserved characters): ; , / ? : @ & = + $ #
• الأحرف غير المحجوزة (Unreserved characters): الحروف والأرقام و - _ . ! ~ * ' ( )

// تحافظ encodeURI على بنية الرابط
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// ملاحظة: لم تُرمَّز الأحرف :, /, ?, =, &

‏encodeURIComponent() — لترميز مكونات الرابط

صُممت دالة encodeURIComponent() لترميز مكوّن واحد من الرابط (مثل قيمة معامل استعلام). فهي تُرمِّز جميع الأحرف باستثناء:

• الأحرف غير المحجوزة (Unreserved characters): الحروف والأرقام و - _ . ! ~ * ' ( )

// تُرمِّز encodeURIComponent كل شيء عدا الأحرف غير المحجوزة
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// ملاحظة: تم ترميز & لأنه حرف محجوز

// استخدامها لقيمة معامل استعلام
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

أخطاء شائعة

الخطأ الأول: استخدام encodeURI لقيم الاستعلام

إذا استخدمت encodeURI() لترميز قيمة معامل استعلام تحتوي على علامة العطف (&)، فلن تُرمَّز هذه العلامة وسيُفسَّرها الخادم على أنها فاصل بين المعاملات، مما يؤدي إلى تعطّل الرابط.

// خطأ: علامة العطف داخل القيمة تُعطِّل الرابط
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// يرى الخادم: q="Tom " ومعاملًا " Jerry" بدون قيمة

// صحيح: استخدم encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// يرى الخادم بشكل صحيح: q="Tom & Jerry"

الخطأ الثاني: استخدام encodeURIComponent للروابط الكاملة

إذا استخدمت encodeURIComponent() على رابط كامل، فإنها ستُرمِّز النقطتين والشرطات المائلة وعلامات الاستفهام وغيرها من الأحرف البنيوية، مما يجعل الرابط غير صالح للاستخدام تمامًا.

متى تستخدم كلًّا منهما: القاعدة البسيطة

• استخدم encodeURI() عندما يكون لديك رابط URI كامل قد يحتوي على مسافات أو أحرف غير ASCII لكن بنيته سليمة
• استخدم encodeURIComponent() عندما تُرمِّز جزءًا واحدًا من البيانات سيُوضع داخل رابط (مثل قيم معاملات الاستعلام، أو مقاطع المسار، وما إلى ذلك)

البديل: URLSearchParams

توفر جافاسكريبت الحديثة واجهة URLSearchParams التي تتولى الترميز تلقائيًا. وغالبًا ما يكون هذا هو الأسلوب الأمثل لبناء سلاسل الاستعلام:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// أو استخدم واجهة URL
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());