سلسلة الاستعلام

[مستقر: 2 - مستقر]

مستقر: 2 استقرار: 2 - مستقر

رمز المصدر: lib/querystring.js

يوفر مُعامل node:querystring أدوات مساعدة لتحليل وتنسيق سلاسل استعلامات عنوان URL. ويمكن الوصول إليه باستخدام:

const querystring = require('node:querystring')

يُعد querystring أكثر كفاءة من <URLSearchParams> ولكنه ليس واجهة برمجة تطبيقات معيارية. استخدم <URLSearchParams> عندما لا يكون الأداء أمرًا بالغ الأهمية أو عند الرغبة في التوافق مع كود المتصفح.

querystring.decode()

مضاف في: v0.1.99

دالة querystring.decode() هي اسم مستعار لـ querystring.parse().

querystring.encode()

مضاف في: v0.1.99

دالة querystring.encode() هي اسم مستعار لـ querystring.stringify().

querystring.escape(str)

مضاف في: v0.1.25

• str <سلسلة>

تقوم طريقة querystring.escape() بتشفير النسبة المئوية لعنوان URL على str المُعطى بطريقة مُحسّنة لمتطلبات سلاسل استعلامات عنوان URL المُحددة.

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

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

[التاريخ]

الإصدار	التغييرات
v8.0.0	يتم الآن تحليل إدخالات فارغة متعددة بشكل صحيح (مثل &=&=).
v6.0.0	لم يعد الكائن المُرجع يرث من Object.prototype.
v6.0.0, v4.2.4	قد يكون لمعامل eq الآن طول أكبر من 1.
v0.1.25	مضاف في: v0.1.25

• str <سلسلة> سلسلة استعلام عنوان URL التي سيتم تحليلها
• sep <سلسلة> السلسلة الفرعية المستخدمة لترسيم أزواج المفتاح والقيمة في سلسلة الاستعلام. الافتراضي: '&'.
• eq <سلسلة>. السلسلة الفرعية المستخدمة لترسيم المفاتيح والقيم في سلسلة الاستعلام. الافتراضي: '='.
• options <كائن>
  • decodeURIComponent <دالة> الدالة التي سيتم استخدامها عند فك ترميز الأحرف المُشفرة بنسبة مئوية في سلسلة الاستعلام. الافتراضي: querystring.unescape().
  • maxKeys <رقم> يحدد الحد الأقصى لعدد المفاتيح التي سيتم تحليلها. حدد 0 لإزالة قيود عدّ المفاتيح. الافتراضي: 1000.

تقوم طريقة querystring.parse() بتحليل سلسلة استعلام عنوان URL (str) إلى مجموعة من أزواج المفتاح والقيمة.

على سبيل المثال، يتم تحليل سلسلة الاستعلام 'foo=bar&abc=xyz&abc=123' إلى:

{
  "foo": "bar",
  "abc": ["xyz", "123"]
}

الكيان الذي تُرجعه طريقة querystring.parse() لا يرث نموذجيًا من Object في جافا سكريبت. هذا يعني أن طرق Object النموذجية مثل obj.toString(), obj.hasOwnProperty(), وغيرها غير مُعرّفة ولن تعمل.

افتراضيًا، سيتم افتراض أن الأحرف المُشفرة بنسبة مئوية داخل سلسلة الاستعلام تستخدم ترميز UTF-8. إذا تم استخدام ترميز أحرف بديل، فسيكون من الضروري تحديد خيار decodeURIComponent بديل:

// بافتراض وجود دالة gbkDecodeURIComponent بالفعل...

querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null, { decodeURIComponent: gbkDecodeURIComponent })

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

مضاف في: v0.1.25

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

طريقة querystring.stringify() تُنتج سلسلة استعلام URL من obj معين عن طريق التكرار خلال "الخصائص الخاصة" للكائن.

تقوم بتسلسل الأنواع التالية من القيم الممررة في obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <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. إذا كان هناك ترميز بديل مطلوب، فسيكون من الضروري تحديد خيار encodeURIComponent بديل:

// بافتراض وجود دالة gbkEncodeURIComponent بالفعل،

querystring.stringify({ w: '中文', foo: 'bar' }, null, null, { encodeURIComponent: gbkEncodeURIComponent })

querystring.unescape(str)

مضاف في: v0.1.25

• str <string>

تقوم طريقة querystring.unescape() بفك ترميز الأحرف المشفرة بنسبة مئوية لعنوان URL في str المعطى.

تُستخدم طريقة querystring.unescape() بواسطة querystring.parse()، ولا يُتوقع عمومًا استخدامها مباشرةً. يتم تصديرها في المقام الأول للسماح لرمز التطبيق بتوفير تنفيذ فك ترميز بديل إذا لزم الأمر عن طريق تعيين querystring.unescape إلى دالة بديلة.

بشكل افتراضي، ستحاول طريقة querystring.unescape() استخدام طريقة decodeURIComponent() المدمجة في JavaScript لفك التشفير. إذا فشل ذلك، فسيتم استخدام بديل أكثر أمانًا لا يُلقي استثناءً في عناوين URL غير الصحيحة.