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

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

const querystring = require(‘querystring’);

`querystring.escape(str)‎`

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

المُعامِلات (Parameters):

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.

المُعامِلات:

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 الرسمي.