میانای برنامه‌سازی کاربردی notRestoredReasons حافظه نهان ناوبری بین صفحات

ببینید کدام ناوبری‌ها از استفاده از bfcache مسدود شده‌اند و چرا.

Chris Mills
Barry Pollard

ویژگی notRestoredReasons که به کلاس PerformanceNavigationTiming اضافه شده است، اطلاعاتی درباره اینکه آیا قاب‌های موجود در سند از استفاده از bfcache در ناوبری مسدود شده‌اند یا نه و دلیل آن را گزارش می‌دهد. توسعه‌دهندگان می‌توانند از این اطلاعات برای شناسایی صفحاتی که نیاز به به‌روزرسانی دارند استفاده کنند تا آن‌ها را با حافظه نهان ناوبری بین صفحات سازگار کنند و درنتیجه عملکرد سایت را بهبود بخشند.

وضعیت کنونی

‫notRestoredReasons API از Chrome 123 عرضه شده است و به‌تدریج درحال عرضه است.

مفاهیم و کاربرد

مرورگرهای مدرن ویژگی بهینه‌سازی‌ای برای پیمایش سابقه ارائه می‌دهند که حافظه نهان ناوبری بین صفحات (bfcache) نامیده می‌شود. این کار باعث می‌شود وقتی کاربران به صفحه‌ای که قبلاً بازدید کرده‌اند برمی‌گردند، تجربه بار کردن فوری داشته باشند. صفحه‌ها ممکن است به دلایل مختلفی از ورود به bfcache مسدود شوند یا درحالی‌که در bfcache هستند، حذف شوند؛ برخی از این دلایل به‌دلیل الزامات مشخصات فنی و برخی دیگر به‌دلیل پیاده‌سازی‌های خاص مرورگر است.

قبلاً هیچ راهی برای توسعه‌دهندگان وجود نداشت تا بفهمند چرا صفحه‌هایشان از استفاده از bfcache در فیلد مسدود شده است، اگرچه آزمایشی در ابزارهای توسعه Chrome وجود داشت. برای فعال کردن پایش در فیلد، کلاس PerformanceNavigationTiming گسترش یافته است تا ویژگی notRestoredReasons را دربرگیرد. این کار شیئی را برمی‌گرداند که حاوی اطلاعات مرتبط درباره قاب بالایی و همه iframeهای موجود در سند است:

  • دلایل مسدود شدن آن‌ها از استفاده از bfcache.

  • جزئیاتی مثل قاب id و name برای کمک به شناسایی iframe در HTML.

    این کار به توسعه‌دهندگان امکان می‌دهد تا برای سازگار کردن آن صفحه‌ها با bfcache اقدام کنند و درنتیجه عملکرد سایت را بهبود بخشند.

مثال‌ها

نمونه PerformanceNavigationTiming را می‌توان از ویژگی‌هایی مانند Performance.getEntriesByType() و PerformanceObserver دریافت کرد.

برای مثال، می‌توانید تابع زیر را فراخوانی کنید تا همه اشیاء PerformanceNavigationTiming موجود در خط زمان عملکرد را برگرداند و notRestoredReasons آن‌ها را ثبت کند:

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let< i = 0; i  navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

برای پیمایش‌های سابقه، ویژگی PerformanceNavigationTiming.notRestoredReasons شیئی با ساختار زیر برمی‌گرداند که نشان‌دهنده وضعیت مسدودشده قاب سطح بالا است:

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

ویژگی‌ها به‌صورت زیر است:

children
آرایه‌ای از اشیاء که وضعیت مسدودشده هر قاب هم‌مبدأ جاسازی‌شده در قاب سطح بالا را نشان می‌دهد. هر شیء ساختاری مشابه با شیء والد دارد — به این ترتیب، هر تعداد سطح از قاب‌های جاسازی‌شده را می‌توان به‌صورت بازگشتی در داخل شیء نمایش داد. اگر قاب فرزند نداشته باشد، آرایه خالی خواهد بود.
id
رشته‌ای که مقدار مشخصه id قاب را نشان می‌دهد (برای مثال <iframe id="foo" src="...">). اگر قاب id نداشته باشد، مقدار null خواهد بود. برای صفحه سطح بالا، این مقدار null است.
name
رشته‌ای که مقدار مشخصه name قاب را نشان می‌دهد (برای مثال <iframe name="bar" src="...">). اگر قاب name نداشته باشد، مقدار رشته‌ای خالی خواهد بود. برای صفحه سطح بالا، این مقدار null است.
reasons
آرایه‌ای از رشته‌ها که هرکدام نشان‌دهنده دلیلی است که چرا صفحه پیمایش‌شده از استفاده از bfcache مسدود شده است. دلایل مختلفی برای مسدود شدن وجود دارد. برای جزئیات بیشتر، بخش دلایل مسدود کردن را ببینید.
src
رشته‌ای که نشان‌دهنده مسیر منبع قاب است (برای مثال <iframe src="b.html">). اگر قاب src نداشته باشد، مقدار آن رشته‌ای خالی خواهد بود. برای صفحه سطح بالا، این مقدار null است.
url
رشته‌ای که نشان‌دهنده نشانی وب صفحه/iframe پیمایش‌شده است.

برای اشیای PerformanceNavigationTiming که نشان‌دهنده پیمایش‌های سابقه نیستند، ویژگی notRestoredReasons مقدار null را برمی‌گرداند.

توجه داشته باشید که notRestoredReasons همچنین زمانی که هیچ دلیل مسدودکننده‌ای وجود ندارد، null را برمی‌گرداند، بنابراین این null نشان‌دهنده استفاده یا عدم استفاده از bfcache نیست. برای این کار، باید از خصوصیت event.persisted استفاده کنید.

گزارش کردن مسدود شدن bfcache در قاب‌های هم‌مبدأ

وقتی صفحه‌ای دارای قاب‌های جاسازی‌شده با مبدأ یکسان باشد، مقدار notRestoredReasons برگردانده‌شده حاوی شیئی در ویژگی children خواهد بود که نشان‌دهنده وضعیت مسدودشده هر قاب جاسازی‌شده است.

برای مثال:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

گزارش کردن مسدود شدن bfcache در قاب‌های میان‌مبدئی

وقتی صفحه‌ای دارای قاب‌های میان‌مبدئی جاسازی‌شده باشد، مقدار اطلاعات هم‌رسانی‌شده درباره آن‌ها را محدود می‌کنیم تا از نشت اطلاعات میان‌مبدئی جلوگیری کنیم. ما فقط اطلاعاتی را اضافه می‌کنیم که صفحه بیرونی ازقبل می‌داند و اینکه آیا زیردرخت میان‌مبدئی حافظه نهان ناوبری بین صفحات را مسدود کرده است یا نه. هیچ‌گونه دلیل مسدودسازی یا اطلاعاتی درباره سطوح پایین‌تر زیردرخت (حتی اگر برخی‌از زیرسطح‌ها دارای مبدأ یکسان باشند) اضافه نمی‌کنیم.

برای مثال:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

برای همه iframeهای میان‌مبدئی، null را برای مقدار reasons برای قاب گزارش می‌کنیم و قاب سطح بالا دلیل "masked" را نشان می‌دهد. توجه داشته باشید که ممکن است از "masked" برای دلایل خاص نماینده کاربر نیز استفاده شود، بنابراین ممکن است همیشه نشان‌دهنده مشکل در iframe نباشد.

برای جزئیات بیشتر درباره ملاحظات امنیتی و حریم خصوصی، به بخش امنیت و حریم خصوصی در توضیح‌دهنده مراجعه کنید.

دلایل مسدود کردن

همان‌طور که قبلاً گفتیم، دلایل مختلفی برای مسدود شدن وجود دارد:

در زیر نمونه‌هایی از رایج‌ترین دلایلی که نمی‌توان از حافظه نهان ناوبری بین صفحات استفاده کرد آورده شده است:

  • unload-listener: صفحه یک گرداننده unload ثبت می‌کند که مانع از استفاده از bfcache در برخی مرورگرها می‌شود. توجه داشته باشید که Chrome دیگر این دلیل را از Chrome 155 صادر نمی‌کند، مگر در مواردی که سایت‌ها دوباره به رویدادهای unload بازگشته باشند. برای اطلاعات بیشتر، به منسوخ کردن رویداد unload مراجعه کنید.
  • response-cache-control-no-store: این صفحه از no-store به‌عنوان مقدار cache-control استفاده می‌کند.
  • related-active-contents: صفحه از صفحه دیگری باز شده است (بااستفاده از «برگه تکراری») که هنوز به این صفحه ارجاع می‌دهد.

بازخورد

تیم Chromium می‌خواهد درباره تجربه‌های شما با bfcache notRestoredReasons API بشنود.

درباره طراحی میانای برنامه‌سازی کاربردی به ما بگویید

آیا چیزی درباره API وجود دارد که طبق انتظار شما کار نمی‌کند؟ یا روش‌ها یا ویژگی‌هایی وجود دارد که برای پیاده‌سازی ایده‌تان به آن‌ها نیاز دارید؟ سؤال یا نظری درباره مدل امنیتی دارید؟ مشکل مشخصات را در مخزن GitHub مربوطه ثبت کنید یا نظرات خود را به مشکل موجود اضافه کنید.

گزارش کردن مشکل در پیاده‌سازی

آیا اشکالی در پیاده‌سازی Chromium پیدا کرده‌اید؟ یا پیاده‌سازی با مشخصات متفاوت است؟ اشکالی را در ردیاب مشکل ما ثبت کنید. حتماً تا جایی که می‌توانید جزئیات، دستورالعمل‌های بازتولید، و مؤلفه را به‌عنوان UI > Browser > Navigation > BFCache مشخص کنید.

نمایش پشتیبانی از API

آیا قصد دارید از bfcache notRestoredReasons API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chromium کمک می‌کند ویژگی‌ها را اولویت‌بندی کند و به دیگر فروشندگان مرورگر نشان می‌دهد که پشتیبانی از آن‌ها چقدر حیاتی است.

بااستفاده از هشتگ #NotRestoredReasons، توییتی به @ChromiumDev ارسال کنید و به ما بگویید کجا و چگونه از آن استفاده می‌کنید.

پیوندهای مفید