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

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

Chris Mills
Barry Pollard

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

الوضع الحالي

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

المفاهيم والاستخدام

توفِّر المتصفّحات الحديثة ميزة تحسين للتنقّل في السجلّ باسم التخزين المؤقت للصفحات (bfcache). يتيح ذلك تجربة التحميل الفوري عندما يعود المستخدمون إلى صفحة سبق أن زاروها. يمكن حظر الصفحات من الدخول إلى ذاكرة التخزين المؤقت أو إزالتها أثناء استخدام ذاكرة التخزين المؤقت في ذاكرة التخزين المؤقت لأسباب مختلفة، بعضها تتطلّب مواصفات والبعض الآخر يتعلّق بعمليات تنفيذ المتصفّح.

في السابق، لم تكن هناك طريقة تتيح للمطوّرين معرفة سبب حظر صفحاتهم من استخدام ميزة "التخزين المؤقت للصفحات" في الحقل، ولكن كان هناك اختبار في أدوات مطوّري برامج Chrome. لتفعيل التتبُّع في الحقل، تم توسيع الفئة PerformanceNavigationTiming لتشمل السمة notRestoredReasons. يؤدي ذلك إلى عرض كائن يحتوي على معلومات ذات صلة في الإطار العلوي وجميع إطارات iframe الحالية في المستند:

  • أسباب حظرهم من استخدام ميزة "التخزين المؤقت للصفحات"

  • تفاصيل مثل الإطارَين id وname للمساعدة في تحديد إطارات iframe في HTML

    ويسمح ذلك للمطوّرين باتخاذ إجراءات لجعل هذه الصفحات متوافقة مع ذاكرة التخزين المؤقت، وبالتالي تحسين أداء المواقع الإلكترونية.

أمثلة

يمكن الحصول على مثيل 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
مصفوفة من السلاسل تمثل كل منها سبب حظر الصفحة التي تم الانتقال إليها من استخدام ميزة "التخزين المؤقت للصفحات". هناك العديد من الأسباب المختلفة لحدوث الحظر. يمكنك الاطّلاع على قسم أسباب الحظر للحصول على مزيد من التفاصيل.
src
سلسلة تمثّل المسار إلى مصدر الإطار (على سبيل المثال <iframe src="b.html">). إذا كان الإطار لا يحتوي على src، ستكون القيمة سلسلة فارغة. هذا هو العنوان null في صفحة المستوى الأعلى.
url
سلسلة تمثِّل عنوان URL للصفحة التي تم الانتقال إليها/إطار iframe الذي تم الانتقال إليه

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

يُرجى العِلم أنّ notRestoredReasons تعرض أيضًا الرمز null عندما لا تكون هناك أسباب حظر، وبالتالي لا يُعدّ استخدام null هذا مؤشرًا على استخدام أو عدم استخدام ذاكرة التخزين المؤقت. لإجراء ذلك، يجب استخدام السمة 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.

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

أسباب الحظر

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

في ما يلي أمثلة على بعض الأسباب الأكثر شيوعًا لعدم إمكانية استخدام ميزة "التخزين المؤقت للصفحات":

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

ملاحظات

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

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

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

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

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

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

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

يمكنك إرسال تغريدة إلى @ChromiumDev باستخدام علامة التصنيف #NotRestoredReasons وإعلامنا بمكان استخدامها وكيفية استخدامها.

روابط مفيدة