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

ابحث عن عمليات التنقّل التي تم حظرها من استخدام ميزة "التخزين المؤقت للصفحات" ولماذا.

Chris Mills
Barry Pollard

تعرض السمة notRestoredReasons، التي تمت إضافتها إلى الفئة PerformanceNavigationTiming، معلومات حول ما إذا تم حظر استخدام الإطارات المتوفّرة في المستند 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 و أخبِرنا بالمكان الذي تستخدم فيه هذه الميزة وطريقة استخدامك لها.

روابط مفيدة