الوحدة Query String في Node.js

توفر الوحدة querystring مجموعة من الأدوات لتحليل وتنسيق سلاسل الاستعلامات في الروابط (URL query strings). يُمكِن استيراد الوحدة والبدء باستخدامها عبر تنفيذ:

const querystring = require(‘querystring’);

querystring.escape(str)‎

أُضيفَ في الإصدار 0.1.25.

• str من النوع <string>.

يرمِّز هذا التابع المحارِف المُمرَّرة للمُعامِل الأوَّل str بترميز النسبة المئويّة لتحويله إلى سلسلة استعلامات صالحة. مثال:

querystring.escape("foo=bar&bar=foo");
// 'foo%3Dbar%26bar%3Dfoo'

يُستخدَم التابع querystring.escape()‎ عبر التابع querystring.stringify()‎ ولا يتوقع منه أن يستدعى مباشرةً. يُستخدَم هذا التابِع عادةً لتوفير آلية بديلة تقوم بعمليّة ترميز النسبة المئويّة إن لزم الأمر. يتم ذلك عبر إسناد الخاصيّة querystring.escape إلى دالة بديلة.

querystring.parse(str[, sep[, eq[, options]]])‎

سجل التغييرات

الإصدار	التغييرات
8.0.0	تحليل مدخلات الاستعلام المتتالية بشكل صحيح (مثال: ‎&=&=‎).
6.0.0	الكائن الذي يُعيده التابع لم يعد يَرِث خصائص الكائِن Object.prototype.
4.2.4، 6.0.0	أصبح بالإمكان تمرير طول للمُعامِل eq أكبر من 1.
0.1.25	أُضيفَ في الإصدار 0.1.25.

• str من النوع <string>: سلسلة الاستعلامات لتحليلها.
• str من النوع <string>: السلسلة النصيّة الفرعيّة المُستخدمة لِفَصِل أزواج القيم والمفاتيح عن بعضها في سلسلة الاستعلامات. القيمة الافتراضيّة: '&'.
• eq من النوع <string>: السلسلة النصيّة الفرعيّة المُستخدمة لِفَصِل القيم والمفاتيح عن بعضها في سلسلة الاستعلامات. القيمة الافتراضيّة: '='.
• options من النوع <Object>:
  • decodeURIComponent من النوع <Function>: الدالة المُستخدمة لإجراء عمليّة فك ترميز النسبة المئويّة في سلسلة الاستعلامات. القيمة الافتراضيّة: querystring.unescape()‎‎.
  • maxKeys من النوع <number>: يُحدد الحد الأقصى للمفاتيح التي ستُحلَّل. عيّن قيمة المُعامِل لصفر (0) لتعطيل هذا الخيار. القيمة الافتراضيّة: 1000.

يعمل هذا التابع على تحليل سلسلة استعلامات (مُمرَّة عبر المُعامِل الأوَّل str) وتحويلها إلى أزواج من القيم والمفاتيح.

لنأخذ سلسلة الاستعلامات هذه 'foo=bar&abc=xyz&abc=123' على سبيل المثال. ستُحلَّل هذه السلسلة إلى مجموعة الأزواج التالية:

{
    foo: ‘bar’,
    abc: [‘xyz’, ‘123’]
}

الكائِن الذي يُعيده التابع querystring.parse()‎ لا يَرِث الكائن Object في JavaScript عبر سلسلة prototype، ما يعني أنَّ توابع الكائن Object، كالتابع obj.toString()‎ والتابع obj.hasOwnProperty()‎، لن تعمل إذا استدعيتها على القيمة المُعادة من هذا التابع. يفترض هذا التابِع أنَّ المحارِف (characters) الموضوعة داخل سلسلة الاستعلامات المُرَّرة مُرمَّزة بترميز UTF-8. ينبغي عليك تمرير مُرمِّز بديل عبر المُعامِل الفرعي decodeURIComponent إذا أردت استخدام نوع ترميز آخر، كما هو موضَّح أدناه:

// لنفترِض أنَّ الدالة gbkDecodeURIComponent التي سنستخدمها لفك الترميز مُعرِّفة بالفعل
querystring.parse(‘w=%D6%D0%CE%C4&foo=bar’, null, null, 
            { decodeURIComponent: gbkDecodeURIComponent });

querystring.stringify(obj[, sep[, eq[, options]]])‎

أُضيفَ في الإصدار 0.1.25.

• obj من النوع <Object>: الكائن الذي سيحوّل إلى سلسلة استعلامات.
• sep من النوع <string>: السلسلة النصيّة الفرعيّة المُستخدمة لفصل أزواج القيم والمفاتيح عن بعضها في سلسلة الاستعلامات. القيمة الافتراضيّة: '&'.
• eq من النوع <string>: السلسلة النصيّة الفرعيّة المُستخدمة لفصل القيم والمفاتيح عن بعضها في سلسلة الاستعلامات. القيمة الافتراضيّة: '='.
• options:
  • encodeURIComponent من النوع <Function>: الدالة المُستخدمة لترميز المحارِف المتواجدة في سلسلة الاستعلامات بترميز النسبة المئويّة. القيمة الافتراضيّة: querystring.escape()‎‎.

يحوِّل التابعُ querystring.stringify()‎ الكائنَ المُمرَّر obj (كأول وسيط) إلى سلسلة استعلامات عبر إجراء حلقة تكراريّة على الخاصيات التابعة للكائن مباشرةً.

يقبل التابِع أنواع القيم التالية لِتُمرَّر للمُعامِل obj: النوع <string>، و <number>، و <boolean>، و <[]string>، و <[]number>، و <[]boolean>. ستُعامَل أي قيمة مُدخلة، لذلك المُعامِل، غير مذكورة أعلاه على أنَّها سلسلة نصيّة فارغة.

querystring.stringify({ foo: ‘bar’, baz: [‘qux’, ‘quux’], corge: ‘’ });
// ‘foo=bar&baz=qux&baz=quux&corge='

querystring.stringify({ foo: ‘bar’, baz: ‘qux’ }, ‘;’, ‘:’);
// 'foo:bar;baz:qux'

ستُرمَّز المحارِف المُدخلة في سلسلة الاستعلامات بترميز UTF-8 افتراضيًا. ينبغي عليك تمرير مُرمِّز بديل عبر المُعامِل الفرعي decodeURIComponent إذا أردت استخدام نوع ترميز آخر، كما هو موضَّح أدناه:

// لنفترِض أنَّ الدالة gbkDecodeURIComponent التي سنستخدمها لترميز المحارِف مُعرِّفة بالفعل
querystring.stringify({ w: '中文', foo: ‘bar’ }, null, null, 
                 { encodeURIComponent: gbkEncodeURIComponent });

querystring.unescape(str)‎

أُضيفَ في الإصدار 0.1.25.

1. str من النوع ‎‎<string>‎.

يجري هذا التابع عمليّة فك ترميز النسبة المئويّة للمحارِف المُدخلة عبر المُعامِل str. مثال:

querystring.unescape("foo%3Dbar%26bar%3Dfoo");
// 'foo=bar&bar=foo'

يُستخدَم التابِع querystring.unescape()‎ عبر التابِع querystring.parse()‎ ولا يتوقع منه أن يستدعى مباشرةً. يُستخدَم هذا التابِع عادةً لتوفير آلية بديلة تقوم بعمليّة ترميز النسبة المئويّة إن لزم الأمر؛ وذلك عبر إسناد الخاصيّة querystring.unescape إلى الدالة البديلة.

يحاول التابِع ()querystring.unescape استخدام التابِع decodeURIComponent()‎ المبني في JavaScript لفك الترميز افتراضيًا. في حال فشل التابِع بالقيام بذلك، سيقوم باستخدام بديل مُماثِل آمن وفعّال لإنجاز المُهمة دون أن يرمي الاستثناء URIError.

مصادر

• صفحة Query String في توثيق Node.js الرسمي.