encodeURIComponent()‎

الدالة encodeURIComponent()‎ تُرمِّز مكوِّن من مكونات روابط URI (اختصار للعبارة Uniform Resource Identifier) بتبديل كل نسخة من محارف معيّنة بعبارة مُهرَّبة (escape sequences) أو أكثر والتي تُمثِّل ترميز UTF-8 للمحرف المعني.

البنية العامة

encodeURIComponent(str);

str

سلسلة نصية تُمثِّل مكوِّنًا من مكوِّنات رابط URI.

القيمة المعادة

سلسلة نصية تُمثِّل النسخة المُرمَّزة من مكوِّن رابط URI.

الوصف

الدالة encodeURIComponent تُهرِّب (escape) جميع المحارف ما عدا:

A-Z a-z 0-9 - _ . ! ~ * ' ( )

تختلف الدالة encodeURIComponent عن الدالة encodeURI كما هو موضَّح في المثال الآتي، لاحظ أنَّ الاختلاف الرئيسي بينهما هو في ترميز المحارف المحجوزة (reserved characters) ورمز #:

var set1 = ";,/?:@&=+$#";  // محارف محجوزة
var set2 = "-_.!~*'()";    // علامات غير محجوزة
var set3 = "#";            // رمز المربع
var set3 = "ABC abc 123";  // أحرف وأرقام وفراغات

console.log(encodeURI(set1)); // ;,/?:@&=+$#
console.log(encodeURI(set2)); // -_.!~*'()
console.log(encodeURI(set3)); // #
console.log(encodeURI(set4)); // ABC%20abc%20123 (لاحظ كيف رُمِّزَ الفراغ)

console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24%23
console.log(encodeURIComponent(set2)); // -_.!~*'()
console.log(encodeURIComponent(set3)); // %23
console.log(encodeURIComponent(set4)); // ABC%20abc%20123 (لاحظ كيف رُمِّزَ الفراغ)

استخدم الدالة encodeURIComponent على الحقول التي أدخلها المستخدم من النماذج التي ستُرسَل بطريقة POST إلى الخادم، وهذا سيؤدي إلى ترميز المحرف & الذي قد يولَّد تلقائيًا أثناء عملية تحويل رموز HTML أو غيرها.

فمثلًا، إذا كتب المستخدم السلسلة النصية "Jack & Jill" فستُرمَّز السلسلة النصية إلى "Jack & Jill"، ودون استخدام الدالة encodeURIComponent فسيُفسَّر رمز & من الخادم على أنه بداية حقلٌ جديدٌ من حقول النموذج، مما يؤدي إلى أخطاء في معالجة النموذج.

عند استخدام نوع MIME الآتي application/x-www-form-urlencoded، فسيوضع الرمز + بدلًا من الفراغات، لذا يمكننا استخدام الدالة encodeURIComponent لترميز + إلى ‎%20.

إذا أردنا اتباع تعليمات RFC3986 (التي تحجز المحارف ! و ' و ) و ( و *، على الرغم من أنَّ هذه المحارف ليس لها استخدام خاص في روابط URI)، فيمكننا استخدام الدالة الآتية:

function fixedEncodeURIComponent(str) {
  return encodeURIComponent(str).replace(/[!'()*]/g, function(c) {
    return '%' + c.charCodeAt(0).toString(16);
  });
}

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1.
• معيار ECMAScript 3rd Edition .