تسلط بر Navigation API: مسیریابی و مدیریت تاریخچه در برنامه‌های تک‌صفحه‌ای

Navigation API یک پیشرفت قابل توجه در نحوه مدیریت مسیریابی و تاریخچه در برنامه‌های تک‌صفحه‌ای (SPA) محسوب می‌شود. روش‌های سنتی اغلب به دستکاری شیء `window.location` یا استفاده از کتابخانه‌های شخص ثالث متکی هستند. در حالی که این رویکردها به خوبی به ما خدمت کرده‌اند، Navigation API یک راه‌حل ساده‌تر، پربازده‌تر و غنی از ویژگی‌ها را ارائه می‌دهد و به توسعه‌دهندگان کنترل بیشتری بر تجربه ناوبری کاربر می‌بخشد.

Navigation API چیست؟

Navigation API یک API مدرن مرورگر است که برای ساده‌سازی و بهبود روش مدیریت ناوبری، مسیریابی و تاریخچه در SPAها طراحی شده است. این API یک شیء جدید به نام `navigation` را معرفی می‌کند که متدها و رویدادهایی را فراهم می‌کند که به توسعه‌دهندگان اجازه می‌دهد رویدادهای ناوبری را رهگیری و کنترل کنند، URL را به‌روزرسانی کنند و یک تاریخچه مرور منسجم را بدون بارگذاری مجدد کامل صفحه حفظ کنند. این امر منجر به تجربه کاربری سریع‌تر، روان‌تر و واکنش‌گراتر می‌شود.

مزایای استفاده از Navigation API

• بهبود عملکرد: با حذف بارگذاری مجدد کامل صفحه، Navigation API به طور قابل توجهی عملکرد SPAها را بهبود می‌بخشد. انتقال بین نماهای مختلف سریع‌تر و روان‌تر می‌شود که منجر به تجربه کاربری جذاب‌تری می‌گردد.
• کنترل پیشرفته: این API کنترل دقیقی بر رویدادهای ناوبری فراهم می‌کند و به توسعه‌دهندگان اجازه می‌دهد تا رفتار ناوبری را در صورت نیاز رهگیری و اصلاح کنند. این شامل جلوگیری از ناوبری، هدایت مجدد کاربران و اجرای منطق سفارشی قبل یا بعد از وقوع ناوبری است.
• مدیریت ساده تاریخچه: مدیریت پشته تاریخچه مرورگر با Navigation API آسان‌تر شده است. توسعه‌دهندگان می‌توانند به صورت برنامه‌نویسی ورودی‌های تاریخچه را اضافه، جایگزین و پیمایش کنند و از یک تجربه مرور منسجم و قابل پیش‌بینی اطمینان حاصل کنند.
• ناوبری اعلانی (Declarative): Navigation API رویکردی اعلانی‌تر به مسیریابی را تشویق می‌کند و به توسعه‌دهندگان اجازه می‌دهد تا قوانین و رفتارهای ناوبری را به شیوه‌ای واضح و مختصر تعریف کنند. این امر خوانایی و قابلیت نگهداری کد را بهبود می‌بخشد.
• ادغام با فریمورک‌های مدرن: Navigation API برای ادغام یکپارچه با فریمورک‌ها و کتابخانه‌های مدرن جاوا اسکریپت مانند React، Angular و Vue.js طراحی شده است. این به توسعه‌دهندگان اجازه می‌دهد تا از ویژگی‌های این API در گردش کار توسعه موجود خود بهره ببرند.

مفاهیم و ویژگی‌های اصلی

۱. شیء navigation

قلب Navigation API شیء `navigation` است که از طریق شیء گلوبال `window` قابل دسترسی است (یعنی `window.navigation`). این شیء دسترسی به خصوصیات و متدهای مختلف مربوط به ناوبری را فراهم می‌کند، از جمله:

• currentEntry: یک شیء `NavigationHistoryEntry` را برمی‌گرداند که ورودی فعلی در تاریخچه ناوبری را نشان می‌دهد.
• entries(): آرایه‌ای از اشیاء `NavigationHistoryEntry` را برمی‌گرداند که تمام ورودی‌های تاریخچه ناوبری را نشان می‌دهد.
• navigate(url, { state, info, replace }): به یک URL جدید ناوبری می‌کند.
• back(): به ورودی قبلی در تاریخچه ناوبری می‌کند.
• forward(): به ورودی بعدی در تاریخچه ناوبری می‌کند.
• reload(): صفحه فعلی را دوباره بارگذاری می‌کند.
• addEventListener(event, listener): یک شنونده رویداد برای رویدادهای مربوط به ناوبری اضافه می‌کند.

۲. NavigationHistoryEntry

اینترفیس `NavigationHistoryEntry` یک ورودی واحد در تاریخچه ناوبری را نشان می‌دهد. این اینترفیس اطلاعاتی در مورد ورودی ارائه می‌دهد، مانند URL، state و شناسه منحصربه‌فرد آن.

• url: URL ورودی تاریخچه.
• key: یک شناسه منحصربه‌فرد برای ورودی تاریخچه.
• id: یک شناسه منحصربه‌فرد دیگر که به ویژه برای ردیابی چرخه حیات یک رویداد ناوبری مفید است.
• sameDocument: یک مقدار بولین که نشان می‌دهد آیا ناوبری منجر به ناوبری در همان سند می‌شود یا خیر.
• getState(): state مرتبط با ورودی تاریخچه را برمی‌گرداند (که در حین ناوبری تنظیم شده است).

۳. رویدادهای ناوبری

Navigation API چندین رویداد را ارسال می‌کند که به توسعه‌دهندگان اجازه می‌دهد رفتار ناوبری را نظارت و کنترل کنند. این رویدادها عبارتند از:

• navigate: زمانی که یک ناوبری آغاز می‌شود (مثلاً با کلیک کردن روی یک لینک، ارسال یک فرم یا فراخوانی `navigation.navigate()`) ارسال می‌شود. این رویداد اصلی برای رهگیری و مدیریت درخواست‌های ناوبری است.
• navigatesuccess: زمانی که یک ناوبری با موفقیت به پایان می‌رسد ارسال می‌شود.
• navigateerror: زمانی که یک ناوبری با شکست مواجه می‌شود (مثلاً به دلیل خطای شبکه یا یک استثنای مدیریت نشده) ارسال می‌شود.
• currentchange: زمانی که ورودی فعلی تاریخچه تغییر می‌کند (مثلاً هنگام ناوبری به جلو یا عقب) ارسال می‌شود.
• dispose: زمانی که یک `NavigationHistoryEntry` دیگر قابل دسترسی نیست، مانند زمانی که در حین عملیات `replaceState` از تاریخچه حذف می‌شود، ارسال می‌شود.

پیاده‌سازی مسیریابی با Navigation API: یک مثال عملی

بیایید نحوه استفاده از Navigation API را برای پیاده‌سازی مسیریابی پایه در یک SPA ساده نشان دهیم. یک برنامه با سه نما را در نظر بگیرید: خانه، درباره ما و تماس با ما.

ابتدا، یک تابع برای مدیریت تغییرات مسیر ایجاد کنید:

function handleRouteChange(url) {
  const contentDiv = document.getElementById('content');
  switch (url) {
    case '/':
      contentDiv.innerHTML = '
Home
Welcome to the Home page!
';
      break;
    case '/about':
      contentDiv.innerHTML = '
About
Learn more about us.
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
Contact
Get in touch with us.
';
      break;
    default:
      contentDiv.innerHTML = '
404 Not Found
Page not found.
';
  }
}

سپس، یک شنونده رویداد به رویداد `navigate` اضافه کنید:

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  event.preventDefault(); // Prevent default browser navigation

  const promise = new Promise((resolve) => {
      handleRouteChange(url);
      resolve(); // Resolve the promise after route handling
  });

  event.transition = promise;
});

این کد رویداد `navigate` را رهگیری می‌کند، URL را از شیء `event.destination` استخراج می‌کند، از ناوبری پیش‌فرض مرورگر جلوگیری می‌کند، تابع `handleRouteChange` را برای به‌روزرسانی محتوا فراخوانی می‌کند و پرامیس `event.transition` را تنظیم می‌کند. تنظیم `event.transition` تضمین می‌کند که مرورگر قبل از به‌روزرسانی بصری صفحه، منتظر تکمیل به‌روزرسانی محتوا می‌ماند.

در نهایت، می‌توانید لینک‌هایی ایجاد کنید که ناوبری را فعال کنند:

Home | About | Contact

و یک شنونده کلیک به آن لینک‌ها متصل کنید:

document.addEventListener('click', (event) => {
  if (event.target.tagName === 'A' && event.target.hasAttribute('data-navigo')) {
    event.preventDefault();
    window.navigation.navigate(event.target.href);
  }
});

این کد مسیریابی پایه سمت کلاینت را با استفاده از Navigation API تنظیم می‌کند. اکنون، کلیک کردن روی لینک‌ها یک رویداد ناوبری را فعال می‌کند که محتوای دیو `content` را بدون بارگذاری مجدد کامل صفحه به‌روز می‌کند.

افزودن مدیریت State

Navigation API همچنین به شما امکان می‌دهد تا state را با هر ورودی تاریخچه مرتبط کنید. این برای حفظ داده‌ها در طول رویدادهای ناوبری مفید است. بیایید مثال قبلی را برای گنجاندن یک شیء state تغییر دهیم.

هنگام فراخوانی `navigation.navigate()`، می‌توانید یک شیء `state` ارسال کنید:

window.navigation.navigate('/about', { state: { pageTitle: 'About Us' } });

درون شنونده رویداد `navigate`، می‌توانید با استفاده از `event.destination.getState()` به state دسترسی پیدا کنید:

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  const state = event.destination.getState();
  event.preventDefault();

  const promise = new Promise((resolve) => {
      handleRouteChange(url, state);
      resolve();
  });
  event.transition = promise;

});

function handleRouteChange(url, state = {}) {
  const contentDiv = document.getElementById('content');
  let title = state.pageTitle || 'My App'; // Default title

  switch (url) {
    case '/':
      contentDiv.innerHTML = '
Home
Welcome to the Home page!
';
      title = 'Home';
      break;
    case '/about':
      contentDiv.innerHTML = '
About
Learn more about us.
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
Contact
Get in touch with us.
';
      break;
    default:
      contentDiv.innerHTML = '
404 Not Found
Page not found.
';
      title = '404 Not Found';
  }
  document.title = title;
}

در این مثال اصلاح شده، تابع `handleRouteChange` اکنون یک پارامتر `state` را می‌پذیرد و از آن برای به‌روزرسانی عنوان سند استفاده می‌کند. اگر هیچ state ارسال نشود، به طور پیش‌فرض روی 'My App' تنظیم می‌شود.

استفاده از `navigation.updateCurrentEntry()`

گاهی اوقات ممکن است بخواهید state ورودی تاریخچه فعلی را بدون ایجاد یک ناوبری جدید به‌روز کنید. متد `navigation.updateCurrentEntry()` به شما امکان انجام این کار را می‌دهد. به عنوان مثال، اگر کاربر یک تنظیم را در صفحه فعلی تغییر دهد، می‌توانید state را برای منعکس کردن آن تغییر به‌روز کنید:

function updateUserSetting(setting, value) {
  const currentState = navigation.currentEntry.getState() || {};
  const newState = { ...currentState, [setting]: value };
  navigation.updateCurrentEntry({ state: newState });
  console.log('Updated setting:', setting, 'to', value);
}

// Example usage:
updateUserSetting('theme', 'dark');

این تابع state فعلی را بازیابی می‌کند، تنظیم به‌روز شده را در آن ادغام می‌کند و سپس ورودی تاریخچه فعلی را با state جدید به‌روز می‌کند.

موارد استفاده پیشرفته و ملاحظات

۱. مدیریت ارسال فرم‌ها

Navigation API می‌تواند برای مدیریت ارسال فرم‌ها در SPAها استفاده شود، از بارگذاری مجدد کامل صفحه جلوگیری کرده و تجربه کاربری یکپارچه‌تری را فراهم کند. شما می‌توانید رویداد ارسال فرم را رهگیری کرده و از `navigation.navigate()` برای به‌روزرسانی URL و نمایش نتایج بدون بارگذاری مجدد کامل صفحه استفاده کنید.

۲. عملیات ناهمزمان

هنگام مدیریت رویدادهای ناوبری، ممکن است نیاز به انجام عملیات ناهمزمان داشته باشید، مانند واکشی داده از یک API. خاصیت `event.transition` به شما امکان می‌دهد تا یک پرامیس را با رویداد ناوبری مرتبط کنید و تضمین می‌کند که مرورگر قبل از به‌روزرسانی صفحه، منتظر تکمیل عملیات ناهمزمان می‌ماند. به مثال‌های بالا مراجعه کنید.

۳. بازیابی موقعیت اسکرول

حفظ موقعیت اسکرول در حین ناوبری برای ارائه یک تجربه کاربری خوب بسیار مهم است. Navigation API مکانیزم‌هایی برای بازیابی موقعیت اسکرول هنگام ناوبری به عقب یا جلو در تاریخچه فراهم می‌کند. شما می‌توانید از خاصیت `scroll` در `NavigationHistoryEntry` برای ذخیره و بازیابی موقعیت اسکرول استفاده کنید.

۴. مدیریت خطا

مدیریت خطاهایی که ممکن است در حین ناوبری رخ دهند، مانند خطاهای شبکه یا استثناهای مدیریت نشده، ضروری است. رویداد `navigateerror` به شما امکان می‌دهد تا این خطاها را به خوبی دریافت و مدیریت کنید و از کرش کردن برنامه یا نمایش پیام خطا به کاربر جلوگیری کنید.

۵. بهبود تدریجی (Progressive Enhancement)

هنگام ساخت SPAها با Navigation API، در نظر گرفتن بهبود تدریجی مهم است. اطمینان حاصل کنید که برنامه شما حتی اگر Navigation API توسط مرورگر پشتیبانی نشود، به درستی کار می‌کند. شما می‌توانید از تشخیص ویژگی (feature detection) برای بررسی وجود شیء `navigation` استفاده کرده و در صورت لزوم به روش‌های مسیریابی سنتی بازگردید.

مقایسه با روش‌های مسیریابی سنتی

روش‌های مسیریابی سنتی در SPAها اغلب به دستکاری شیء `window.location` یا استفاده از کتابخانه‌های شخص ثالث مانند `react-router` یا `vue-router` متکی هستند. در حالی که این روش‌ها به طور گسترده استفاده می‌شوند و جا افتاده‌اند، دارای محدودیت‌هایی هستند:

• بارگذاری مجدد کامل صفحه: دستکاری مستقیم `window.location` می‌تواند باعث بارگذاری مجدد کامل صفحه شود که می‌تواند کند و برای تجربه کاربری مخرب باشد.
• پیچیدگی: مدیریت تاریخچه و state با روش‌های سنتی می‌تواند پیچیده و مستعد خطا باشد، به ویژه در برنامه‌های بزرگ و پیچیده.
• سربار عملکرد: کتابخانه‌های مسیریابی شخص ثالث می‌توانند سربار عملکرد قابل توجهی اضافه کنند، به خصوص اگر برای نیازهای خاص برنامه شما بهینه‌سازی نشده باشند.

Navigation API با ارائه یک راه‌حل ساده‌تر، پربازده‌تر و غنی از ویژگی‌ها برای مسیریابی و مدیریت تاریخچه، این محدودیت‌ها را برطرف می‌کند. این API بارگذاری مجدد کامل صفحه را حذف می‌کند، مدیریت تاریخچه را ساده می‌سازد و کنترل دقیقی بر رویدادهای ناوبری فراهم می‌کند.

سازگاری با مرورگرها

از اواخر سال ۲۰۲۴، Navigation API از پشتیبانی خوبی در مرورگرهای مدرن از جمله Chrome، Firefox، Safari و Edge برخوردار است. با این حال، همیشه تمرین خوبی است که قبل از پیاده‌سازی Navigation API در برنامه‌های تولیدی خود، آخرین اطلاعات سازگاری مرورگر را در منابعی مانند Can I use بررسی کنید. اگر پشتیبانی از مرورگرهای قدیمی‌تر ضروری است، استفاده از یک polyfill یا مکانیزم بازگشتی را در نظر بگیرید.

نتیجه‌گیری

Navigation API ابزاری قدرتمند برای ساخت SPAهای مدرن و پربازده با قابلیت‌های پیشرفته مسیریابی و مدیریت تاریخچه است. با بهره‌گیری از ویژگی‌های این API، توسعه‌دهندگان می‌توانند تجربیات کاربری سریع‌تر، روان‌تر و جذاب‌تری ایجاد کنند. در حالی که منحنی یادگیری اولیه ممکن است در مقایسه با استفاده از روش‌های ساده‌تر و قدیمی‌تر کمی تندتر باشد، مزایای Navigation API، به ویژه در برنامه‌های پیچیده، آن را به یک سرمایه‌گذاری ارزشمند تبدیل می‌کند. Navigation API را بپذیرید و پتانسیل کامل SPAهای خود را آزاد کنید.

یادگیری بیشتر

• مستندات وب MDN: Navigation API
• مشخصات WICG Navigation API