معالجة سهلة لعناوين URL باستخدام URLSearchParams

توفّر واجهة برمجة التطبيقات URLSearchParams واجهة متّسقة لإدخال أجزاء عنوان URL والسماح بإجراء تعديلات بسيطة على سلسلة طلب البحث (الجزء الذي يأتي بعد ?).

في العادة، يستخدم مطوّرو البرامج التعبيرات العادية وتقسيم السلاسل لسحب مَعلمات طلب البحث من عنوان URL. لنكن صادقين مع أنفسنا، هذا ليس أمرًا ممتعًا. وقد يكون هذا الإجراء مرهقًا وقابلًا للخطأ. وأحد أسراري المظلمة هو أنني أعدت استخدام get|set|removeURLParameter أساليب المساعدة نفسها في العديد من تطبيقات Google.com الكبيرة، بما في ذلك Google Santa Tracker ومؤتمر Google I/O 2015 على الويب.

لقد حان الوقت لتوفير واجهة برمجة تطبيقات مناسبة تُجري هذه الإجراءات نيابةً عنا.

واجهة برمجة التطبيقات URLSearchParams

تجربة العرض التوضيحي

ينفِّذ Chrome 49 URLSearchParams من مواصفات عنوان URL، وهي واجهة برمجة تطبيقات مفيدة للتعامل مع معلَمات طلب البحث لعناوين URL. أرى أنّ URLSearchParams هي بديل ملائم لعناوين URL، تمامًا كما كان FormData بديلاً مناسبًا للنماذج.

ما هي الإجراءات التي يمكنك اتّخاذها؟ باستخدام سلسلة عنوان URL، يمكنك بسهولة استخراج قيم المَعلمات:

// Can also constructor from another URLSearchParams
const params = new URLSearchParams('q=search+string&version=1&person=Eric');

params.get('q') === "search string"
params.get('version') === "1"
Array.from(params).length === 3

for (let p of params) {
    console.log(p);
}

ضبط قيمة مَعلمة:

params.set('version', 2);

إضافة قيمة أخرى لمَعلمة حالية:

params.append('person', 'Tim');
params.getAll('person') === ['Eric', 'Tim']

حذف مَعلمات:

params.delete('person');

العمل مع عناوين URL

في معظم الأحيان، من المحتمل أن تعمل مع عناوين URL كاملة أو تعدِّل عنوان URL لتطبيقك. يمكن أن تكون طريقة وضع التصميم URL مفيدة بشكل خاص في الحالات التالية:

const url = new URL('https://example.com?foo=1&bar=2');
const params = new URLSearchParams(url.search);
params.set('baz', 3);

params.has('baz') === true
params.toString() === 'foo=1&bar=2&baz=3'

لإجراء تغييرات فعلية على عنوان URL، يمكنك الحصول على المَعلمات وتعديل قيمها، ثم استخدام history.replaceState لتعديل عنوان URL.

// URL: https://example.com?version=1.0
const params = new URLSearchParams(location.search);
params.set('version', 2.0);

window.history.replaceState({}, '', `${location.pathname}?${params}`);
// URL: https://example.com?version=2.0

لقد استخدمت هنا سلاسل نماذج ES6 لإعادة إنشاء عنوان URL معدّل من مسار عنوان URL الحالي للتطبيق والمعلمات المعدَّلة.

الدمج مع عناوين URL لأماكن أخرى

يؤدي إرسال FormData في طلب واجهة برمجة التطبيقات fetch() تلقائيًا إلى إنشاء نص مكوّن من عدة أجزاء. إذا كنت بحاجة إلى ذلك، يوفّر URLSearchParams آلية بديلة لبيانات POST التي يتم ترميزها باستخدام ترميز URL بدلاً من تنسيق MIME المتعدّد الأجزاء.

const params = new URLSearchParams();
params.append('api_key', '1234567890');

fetch('https://example.com/api', {
    method: 'POST',
    body: params
}).then(...)

على الرغم من أنّه لم يتم تنفيذه بعد في Chrome، يتم دمج URLSearchParams أيضًا مع علامة URL وعلامة a. يتوافق كلاهما مع الصديق الجديد من خلال توفير خاصية للقراءة فقط، .searchParams للوصول إلى مَعلمات طلب البحث:

const url = new URL(location);
const foo = url.searchParams.get('foo') || 'somedefault';

تحصل الروابط أيضًا على سمة .searchParams:

const a = document.createElement('a');
a.href = 'https://example.com?filter=api';

// a.searchParams.get('filter') === 'api';

رصد الميزات وتوافق المتصفّح

يتيح حاليًا الإصدار 49 من Chrome والإصدار 44 من Firefox والإصدار 36 من Opera استخدام URLSearchParams.

if ('URLSearchParams' in window) {
    // Browser supports URLSearchParams
}

بالنسبة إلى polyfills، أنصح باستخدام الرابط github.com/WebReflection/url-search-params.

عرض توضيحي

يُرجى تجربة النموذج.

للاطّلاع على URLSearchParams في تطبيق حقيقي، يمكنك الاطّلاع على أداة إنشاء مجموعة الرموز التعبيرية لتصميم المواد من Polymer. لقد استخدمتُها لإعداد الحالة الأولية للتطبيق من رابط لصفحة في التطبيق. مفيد جدًا :)