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

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

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

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

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

تجربة الإصدار التجريبي

ينفِّذ الإصدار 49 من Chrome 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. لقد استخدمتُها لإعداد الحالة الأولية للتطبيق من رابط لصفحة في التطبيق. ميزة مفيدة جدًا :)