APIهای URL

آموزش جاوااسکریپت

مقدمه

آدرس‌های URL یکی از بخش‌های بنیادی وب هستند و ما به عنوان توسعه‌دهنده، دائماً با آنها سروکار داریم. در گذشته، برای تحلیل یا ساخت URLها، اغلب به دستکاری رشته‌ها یا استفاده از عبارات باقاعده (Regular Expressions) پیچیده متوسل می‌شدیم. هرچند شیء location ابزارهایی برای کار با URL صفحه فعلی ارائه می‌دهد، اما یک ابزار عمومی برای کار با هر رشته URL دلخواهی وجود نداشت.

URL API یک رابط برنامه‌نویسی مدرن و قدرتمند است که به صورت درونی در جاوااسکریپت و مرورگرها تعبیه شده تا این مشکل را حل کند. این API به ما اجازه می‌دهد تا URLها را به صورت شیءگرا و با متدهای مشخص، به راحتی تحلیل، ویرایش و ایجاد کنیم. این کار نه تنها کد ما را خواناتر می‌کند، بلکه از بروز بسیاری از خطاهای رایج در دستکاری رشته‌ها نیز جلوگیری می‌کند. دو جزء اصلی این API، شیء URL و رابط URLSearchParams هستند.

تحلیل و ساخت URL با شیء URL

شیء URL یک رشته URL را به اجزای تشکیل‌دهنده‌اش مانند پروتکل، دامنه، مسیر و پارامترها تجزیه می‌کند. برای ساخت یک نمونه از آن، از سازنده‌ی new URL(urlString, [base]) استفاده می‌کنیم. اگر urlString یک آدرس کامل باشد، آرگومان دوم نیاز نیست. اما اگر یک آدرس نسبی باشد (مانند '/about')، باید یک آدرس پایه (base) به عنوان آرگومان دوم ارائه دهیم.

پراپرتی‌های یک شیء URL

پس از ساخت یک شیء URL، می‌توانیم به تمام اجزای آن از طریق پراپرتی‌هایش دسترسی داشته باشیم. این پراپرتی‌ها هم قابل خواندن و هم (به جز origin) قابل نوشتن هستند و تغییر هر کدام، به صورت خودکار کل URL (در پراپرتی href) را به‌روزرسانی می‌کند.

  • href: کل رشته URL.
  • protocol: پروتکل (مثلاً 'https:').
  • hostname: نام دامنه (مثلاً 'www.example.com').
  • port: شماره پورت.
  • pathname: مسیر بعد از دامنه (مثلاً '/path/to/resource').
  • search: کل رشته کوئری شامل علامت سوال (مثلاً '?q=js&page=1').
  • hash: بخش فرگمنت شامل علامت # (مثلاً '#section-2').
  • origin: بخش پروتکل، دامنه و پورت به صورت یکجا (فقط خواندنی).
Copy Icon JAVASCRIPT 
const urlString = 'https://example.com:8080/api/users?page=2&limit=10#first-user';
const myUrl = new URL(urlString);

console.log('Protocol:', myUrl.protocol); // "https:"
console.log('Hostname:', myUrl.hostname); // "example.com"
console.log('Pathname:', myUrl.pathname); // "/api/users"
console.log('Search:', myUrl.search);   // "?page=2&limit=10"

// Let's modify a property
myUrl.pathname = '/api/posts';
console.log('New HREF:', myUrl.href);
// Output: "https://example.com:8080/api/posts?page=2&limit=10#first-user"

این مثال به خوبی نشان می‌دهد که چگونه سازنده‌ی URL به طور خودکار یک رشته را به اجزای معنادار تجزیه می‌کند. همچنین مشاهده می‌کنید که با تغییر تنها یک پراپرتی (pathname)، مقدار کلی href نیز به درستی به‌روز می‌شود.

مدیریت پارامترهای کوئری با URLSearchParams

بخش کوئری (query string) یک URL که بعد از علامت `?` می‌آید، اغلب شامل پارامترهای کلید-مقداری است. کار با این بخش به صورت رشته‌ای، نیازمند مدیریت کاراکترهای `&` و `=` و همچنین انکود کردن صحیح مقادیر است که می‌تواند پیچیده و مستعد خطا باشد.

رابط URLSearchParams یک ابزار قدرتمند برای کار با این پارامترها فراهم می‌کند. پراپرتی searchParams روی یک شیء URL، یک نمونه از URLSearchParams است که به ما اجازه می‌دهد پارامترها را به راحتی بخوانیم، اضافه، حذف یا ویرایش کنیم.

متدهای اصلی URLSearchParams

  • get(name): مقدار اولین پارامتر با نام مشخص شده را برمی‌گرداند.
  • getAll(name): آرایه‌ای از تمام مقادیر برای یک نام پارامتر (در صورتی که تکراری باشد) برمی‌گرداند.
  • set(name, value): مقدار یک پارامتر را تنظیم می‌کند. اگر پارامتر وجود داشته باشد، مقدارش به‌روز می‌شود و اگر نه، ایجاد می‌شود. اگر پارامترهای همنام دیگری وجود داشته باشند، حذف می‌شوند.
  • append(name, value): یک زوج کلید-مقدار جدید اضافه می‌کند، حتی اگر پارامتری با آن نام از قبل وجود داشته باشد.
  • has(name): بررسی می‌کند که آیا پارامتری با نام مشخص شده وجود دارد یا خیر (true/false).
  • delete(name): تمام پارامترهای با نام مشخص شده را حذف می‌کند.
  • toString(): رشته کوئری کامل را (بدون علامت `?`) برمی‌گرداند.
Copy Icon JAVASCRIPT 
const url = new URL('https://example.com/search?q=js&lang=en&lang=fa');
const params = url.searchParams;

console.log('Search query:', params.get('q'));               // "js"
console.log('All languages:', params.getAll('lang')); // ["en", "fa"]

// Modify parameters
params.set('q', 'javascript api');
params.delete('lang');
params.append('sort', 'new');

// The original URL object is updated automatically!
console.log('New URL:', url.href);
// Output: https://example.com/search?q=javascript+api&sort=new

این مثال قدرت URLSearchParams را به خوبی نشان می‌دهد. ما به راحتی پارامترها را خوانده، پارامتر q را با یک مقدار جدید که حاوی فاصله است (و به درستی انکود می‌شود) جایگزین کرده، تمام پارامترهای lang را حذف و یک پارامتر جدید sort اضافه می‌کنیم. تمام این تغییرات به صورت خودکار در شیء اصلی URL منعکس می‌شوند.

در این درس با `APIهای URL` و روش‌های مدرن و قابل اعتمادی که برای کار با آدرس‌ها در اختیار ما قرار می‌دهند، آشنا شدیم. شیء URL برای تجزیه و ساختاردهی، و URLSearchParams برای مدیریت پارامترهای کوئری، ابزارهایی ضروری در توسعه وب مدرن هستند که کد ما را تمیزتر و خطاهای مربوط به دستکاری رشته‌ها را کمتر می‌کنند. در درس بعدی، به سراغ `APIهای Timing` خواهیم رفت تا با روش‌های دقیق‌تر و بهینه‌تری برای اندازه‌گیری زمان و عملکرد کد در جاوااسکریپت آشنا شویم.