Back/Forward cache notRestoredReasons API

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

کریس میلز
بری پولارد

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

وضعیت فعلی

رابط برنامه‌نویسی کاربردی notRestoredReasons از کروم ۱۲۳ منتشر شده و به تدریج در حال انتشار است.

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

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

پیش از این، هیچ راهی برای توسعه‌دهندگان وجود نداشت تا بفهمند چرا صفحاتشان از استفاده از bfcache در فیلد مسدود شده‌اند، اگرچه آزمایشی در ابزارهای توسعه کروم وجود داشت. برای فعال کردن نظارت در فیلد، کلاس 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
رشته‌ای که نشان دهنده‌ی آدرس اینترنتی (URL) صفحه/آی‌فریم پیمایش شده است.

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

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

گزارش مسدود شدن bfcache در فریم‌های same-origin

وقتی یک صفحه فریم‌های با مبدا یکسان (same-origin) جاسازی شده داشته باشد، مقدار 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 در فریم‌های cross-origin

وقتی صفحه‌ای فریم‌های cross-origin را در خود جای داده است، ما میزان اطلاعات به اشتراک گذاشته شده در مورد آنها را محدود می‌کنیم تا از نشت اطلاعات cross-origin جلوگیری کنیم. ما فقط اطلاعاتی را که صفحه بیرونی از قبل می‌داند، و اینکه آیا زیردرخت cross-origin، bfcache را مسدود کرده است یا خیر، درج می‌کنیم. ما هیچ دلیل مسدود شدن یا اطلاعاتی در مورد سطوح پایین‌تر زیردرخت (حتی اگر برخی از زیرسطح‌ها از نوع same-origin باشند) درج نمی‌کنیم.

برای مثال:

{
  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 های cross-origin، ما null برای reasons فریم گزارش می‌دهیم و فریم سطح بالا دلیل "masked" را نشان می‌دهد. توجه داشته باشید که "masked" ممکن است برای دلایل خاص عامل کاربر نیز استفاده شود، بنابراین ممکن است همیشه نشان‌دهنده وجود مشکل در یک iframe نباشد.

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

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

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

در ادامه نمونه‌هایی از رایج‌ترین دلایلی که نمی‌توان از bfcache استفاده کرد، آورده شده است:

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

بازخورد

تیم کرومیوم می‌خواهد تجربیات شما را در مورد رابط برنامه‌نویسی کاربردی bfcache notRestoredReasons بشنود.

در مورد طراحی API به ما بگویید

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

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

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

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

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

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

لینک‌های مفید