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

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

يستخدم مطوّرو البرامج في العادة التعبير العادي وتقسيم السلسلة لسحب معلَمات طلب البحث من عنوان URL. إذا كنا صادقين مع أنفسنا، فهذا ليس ممتعًا. قد يكون الأمر مملاً وعرضة للخطأ. أحد أسراري المظلمة هو أنني أعدت استخدام get|set|removeURLParameter الطرق المساعدة نفسها في العديد من تطبيقات Google.com الكبيرة، بما في ذلك Google سانتا 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);
}

set قيمة مَعلمة:

params.set('version', 2);

append بقيمة أخرى لمَعلمة حالية:

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(...)

URLSearchParams تتكامل أيضًا مع علامات URL الدالة الإنشائية وa، على الرغم من أنها لم يتم تنفيذها في Chrome حتى الآن. يدعم كلاهما أداة صديقنا الجديد من خلال توفير سمة للقراءة فقط، .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';

اكتشاف الميزات ودعم المتصفّح

في الوقت الحالي، يتيح Chrome 49 وFirefox 44 وOpera 36 استخدام URLSearchParams.

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

بالنسبة إلى رموز Polyfill البرمجية، أقترح عليك الرابط على github.com/WebReflection/url-search-params.

عرض توضيحي

ننصحك بتجربة العيّنة.

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