واجهة برمجة التطبيقات "التخزين المؤقت للصفحات" notRestoredreasons API

معرفة عمليات التنقّل التي تم حظرها من استخدام bfcache، وسبب ذلك

Chris Mills
Barry Pollard

تُبلغ سمة notRestoredReasons، التي تمت إضافتها إلى فئة PerformanceNavigationTiming، عن معلومات حول ما إذا تم حظر استخدام الإطارات المتوفّرة في المستند من bfcache أثناء التنقّل، والسبب في ذلك. يمكن للمطوّرين استخدام هذه المعلومات لتحديد الصفحات التي تحتاج إلى تعديلات لجعلها متوافقة مع bfcache، ما يؤدي إلى تحسين أداء الموقع الإلكتروني.

الوضع الحالي

تم طرح واجهة برمجة التطبيقات notRestoredReasons في الإصدار 123 من Chrome، ويتم طرحها تدريجيًا.

المفاهيم وطريقة الاستخدام

توفّر المتصفّحات الحديثة ميزة تحسين للتنقّل في السجلّ تُعرف باسم التخزين المؤقت للصفحات (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
سلسلة تمثّل عنوان URL للصفحة/إطار iframe الذي تم الانتقال إليه

بالنسبة إلى عناصر PerformanceNavigationTiming التي لا تمثّل عمليات التنقّل في السجلّ، ستُعرِض السمة notRestoredReasons القيمة null.

يُرجى العلم أنّ notRestoredReasons يعرض أيضًا القيمة null في حال عدم توفّر أسباب لحظر المحتوى، لذا فإنّ ظهور القيمة null لا يشير إلى ما إذا تم استخدام bfcache أو لا. ولإجراء ذلك، عليك استخدام السمة event.persisted.

الإبلاغ عن حظر ميزة "التخزين المؤقت للصفحات" في إطارات المصدر نفسه

عندما تحتوي الصفحة على إطارات من المصدر نفسه، ستحتوي قيمة 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.

اطّلِع على قسم الأمان والخصوصية في الشرح للحصول على مزيد من التفاصيل حول اعتبارات الأمان والخصوصية.

أسباب الحظر

كما ذكرنا سابقًا، هناك العديد من الأسباب المختلفة التي قد تؤدي إلى الحظر:

في ما يلي أمثلة على بعض الأسباب الأكثر شيوعًا لعدم إمكانية استخدام bfcache:

  • unload-listener: تسجِّل الصفحة معالِج unload، ما يمنع استخدام ميزة "التخزين المؤقت للصفحات" في بعض المتصفحات. اطّلِع على إيقاف حدث unload نهائيًا للحصول على مزيد من المعلومات.
  • response-cache-control-no-store: تستخدم الصفحة no-store كقيمة cache-control.
  • related-active-contents: تم فتح الصفحة من صفحة أخرى (إما باستخدام "علامة تبويب مكرّرة") لا تزال تحتوي على إشارة إلى هذه الصفحة.

ملاحظات

يريد فريق Chromium معرفة تجاربك مع واجهة برمجة التطبيقات bfcache notRestoredReasons.

أخبِرنا عن تصميم واجهة برمجة التطبيقات.

هل هناك مشكلة في واجهة برمجة التطبيقات لا تعمل على النحو المتوقّع؟ هل هناك طُرق أو سمات مفقودة تحتاجها لتنفيذ فكرتك؟ هل لديك سؤال أو تعليق حول ملف أمان الحساب؟ يمكنك الإبلاغ عن مشكلة في المواصفات في مستودع GitHub المقابل، أو إضافة ملاحظاتك إلى مشكلة حالية.

الإبلاغ عن مشكلة في التنفيذ

هل عثرت على خطأ في عملية تنفيذ Chromium؟ أم أنّ عملية التنفيذ مختلفة عن المواصفات؟ يمكنك الإبلاغ عن خطأ في أداة تتبُّع المشاكل. احرص على تضمين أكبر قدر ممكن من التفاصيل، وتعليمات بسيطة لإعادة إنتاج المشكلة، وحدِّد المكوّن على أنّه UI > Browser > Navigation > BFCache. يُعدّ تطبيق Glitch مثاليًا لمشاركة عمليات إعادة الإنتاج بسرعة وسهولة.

إظهار الدعم لواجهة برمجة التطبيقات

هل تخطّط لاستخدام واجهة برمجة التطبيقات bfcache notRestoredReasons؟ يساعد دعمك العلني فريق Chromium في تحديد الميزات ذات الأولوية وإظهار مدى أهمية توفيرها لمطوّري المتصفّحات الآخرين.

أرسِل تغريدة إلى ‎@ChromiumDev باستخدام الهاشتاغ #NotRestoredReasons و أخبِرنا بالمكان الذي تستخدم فيه هذه الميزة وطريقة استخدامك لها.

روابط مفيدة