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

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

Chris Mills

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

الوضع الحالي

الخطوة الحالة
1- إنشاء شرح مكتمل
2. إنشاء مسودة أولية للمواصفات Not started
3- جمع الملاحظات والتكرار التحسيني للتصميم قيد التقدّم
4. مرحلة التجربة والتقييم تم البدء
5- الإطلاق Not started

تجربة واجهة برمجة التطبيقات bfcache notRestoredReasons

بدءًا من الإصدار 109، تتوفّر واجهة برمجة التطبيقات bfcache notRestoredReasons API في شكل نسخة تجريبية من المصدر في Chromium. يمكنك العثور على معلومات محدَّثة حول الجدول الزمني لإصدار هذه الميزة من خلال الانتقال إلى صفحة ميزات ChromeStatus.com (راجِع خطة تحقيق أهداف Chrome لمعرفة تواريخ إصدار الإصدارات).

يمكنك تجربة واجهة برمجة التطبيقات bfcache notRestoredReasons من خلال التسجيل في مرحلة التجربة والتقييم واستخدامها في تجاربك. يُرجى الاطّلاع على صفحة المشاركة في مرحلة التجربة والتقييم للحصول على تعليمات حول كيفية استخدام الرمز المميّز بعد تسجيلك.

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

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

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

  • تفاصيل مثل الإطار id وname للمساعدة في التعرّف عليها في ترميز 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 عنصرًا بالبنية التالية، والتي تمثّل الحالة المحظورة لإطار المستوى الأعلى:

{
  blocked: true,
  children: [],
  id: "",
  name: "",
  reasons: [ "Internal Error", "Unload handler" ],
  src: "",
  url: "a.com"
}

في ما يلي السمات:

blocked
قيمة منطقية تحدد ما إذا كان سيتم حظر الصفحة التي تم التنقّل فيها من استخدام ذاكرة التخزين المؤقت (Bfcache) (true) أم لا (false).
children
مصفوفة من العناصر التي تمثل الحالة المحظورة لأي إطارات مضمّنة في إطار المستوى الأعلى. لكل كائن بنية الكائن الأصلي نفسها - وبهذه الطريقة، يمكن تمثيل أي عدد من مستويات الإطارات المضمنة داخل الكائن على نحو متكرر. إذا لم يكن للإطار عناصر ثانوية، ستكون المصفوفة فارغة.
id
سلسلة تمثل قيمة السمة id للإطار (على سبيل المثال <iframe id="foo" src="...">). إذا لم يكن الإطار يحتوي على id، ستكون القيمة سلسلة فارغة.
name
سلسلة تمثل قيمة السمة name للإطار (على سبيل المثال <iframe name="bar" src="...">). إذا لم يكن الإطار يحتوي على name، ستكون القيمة سلسلة فارغة.
reasons
مصفوفة من السلاسل تمثل كل منها سبب حظر الصفحة التي تم التنقل فيها من استخدام ميزة "التخزين المؤقت للصفحات". هناك العديد من الأسباب المختلفة التي قد تؤدي إلى حدوث الحظر. يمكنك مراجعة قسم أسباب الحظر أدناه للتعرُّف على مزيد من التفاصيل.
src
سلسلة تمثل المسار إلى مصدر الإطار (على سبيل المثال <iframe src="b.html">). وإذا لم يتضمّن الإطار src، ستكون القيمة سلسلة فارغة.
url
سلسلة تمثّل عنوان URL للصفحة التي تم الانتقال إليها

بالنسبة إلى عناصر PerformanceNavigationTiming التي لا تمثّل عمليات التنقّل في السجلّ، ستعرض السمة notRestoredReasons null. هذه الطريقة مفيدة لتحديد ما إذا كانت ميزة bfcache غير ذات صلة بعملية تنقّل معيَّنة، بدلاً من عدم توفُّر notRestoredReasons، وفي هذه الحالة ستعرض السمة undefined.

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

عند تضمين إطارات من المصدر نفسه في صفحة، ستتضمّن القيمة notRestoredReasons المعروضة عنصرًا داخل السمة children يمثّل الحالة المحظورة لكل إطار مضمّن.

مثال:

{
  blocked: false,
  children: [
    { url: "a.com", src: "b.a.com", id: "b", name: "b", blocked: false, reasons: [], children: [] },
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "BroadcastChannel" ], children: [] },
    { url: "a.com", src: "d.a.com", id: "d", name: "d", blocked: false, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

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

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

مثال:

{
  blocked: false,
  children: [
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "ScreenReader" ], children: [] },
    /* cross-origin frame */
    { url: "", src: "b.com", id: "d", name: "d", blocked: true, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

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

{
  blocked: false,
  children: [
    /* cross-origin frames */
    {url: "", src: "b.com", id: "b", name: "b", blocked: null, reasons: [], children: []},
    {url: "", src: "c.com", id: "c", name: "c", blocked: true, reasons: [], children: []},
    {url: "", src: "d.com", id: "d", name: "d", blocked: null, reasons: [], children: []}
  ]
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

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

أسباب الحظر

كما ذكرنا سابقًا، هناك العديد من الأسباب المختلفة التي قد تؤدي إلى حدوث الحظر. لقد جمّعنا جدول بيانات مفيد يعرض جميع سلاسل الأسباب وتوضيح معناها.

هناك عدة فئات رئيسية من الأسباب التي تستحق الذكر:

  • Circumstantial: يشير هذا الحقل إلى أسباب الحظر غير المرتبطة مباشرةً برمز صفحة المطوِّر. على سبيل المثال، تعطّل مكوِّن ذو صلة أو حدث خطأ في عملية التحميل، أو أنّ الصفحة في حالة مؤقتة لا يمكن تخزينها مؤقتًا، أو تم إيقاف ميزة "التخزين المؤقت للصفحات" بسبب عدم كفاية الذاكرة، أو نفّذ أحد مشغّلي الخدمات إجراءً ما على الصفحة يجعلها غير مؤهِّلة لتخزينها مؤقتًا.
  • Extensions: هناك سببان مختلفان للرسائل المتعلّقة بالإضافات. نحن نجمع بشكل عام بعض الأسباب المختلفة في سبب "الإضافات". لدينا غموض عن أسباب الحظر المتعلقة بالإضافات عن قصد، وذلك لأننا لا نرغب في الإفصاح عن كثير من المعلومات حول الإضافات التي ثبّتها المستخدم، والإضافات النشطة على الصفحة، وما يفعله، وما إلى ذلك.
  • PageSupportNeeded: يستخدم الرمز البرمجي للمطوّر إحدى ميزات النظام الأساسي للويب التي لا تحظر ميزة "التخزين المؤقت للصفحات" حاليًا، ولكنها حاليًا في حالة حظر باستخدام ميزة "التخزين المؤقت للصفحات". على سبيل المثال، تحتوي الصفحة حاليًا على BroadcastChannel يتضمّن أدوات مسجَّلة لمعالجة الحدث، أو اتصال IndexedDB مفتوح. أو سجلت الصفحة unload معالج، والذي يمنع استخدام ذاكرة التخزين المؤقت Bfcache في بعض المتصفحات.
  • SupportPending: يستخدم الرمز البرمجي لمطوّر البرامج إحدى ميزات النظام الأساسي للويب التي تجعل الصفحة غير مؤهّلة لاستخدام ميزة "التخزين المؤقت للصفحات"، مثل Web Serial API أو Web Authentication API أو File System Access API أو Media Session API. أو تستخدم الصفحة Cache-Control: no-store، والتي تمنع استخدام ميزة "التخزين المؤقت للصفحات" في بعض المتصفحات في الوقت الحالي. تُستخدَم هذه الفئة أيضًا للإبلاغ عن توفُّر أداة خارج الصفحة نفسها تحظر ميزة "التخزين المؤقت للصفحات"، مثل قارئ الشاشة أو مدير كلمات المرور في Chrome.

إضافة ملاحظات

يرغب فريق Chromium في التعرّف على تجاربك مع واجهة برمجة تطبيقات notRestoredReasons في ميزة "التخزين المؤقت للصفحات".

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

هل هناك مشكلة في واجهة برمجة التطبيقات لا تعمل كما توقعت؟ أو هل هناك طرق أو خصائص مفقودة تحتاج إلى تنفيذ فكرتك؟ هل لديك سؤال أو تعليق على نموذج الأمان؟ قدِّم مشكلة في المواصفات على [GitHub repo][feedback] المقابل، أو أضِف ملاحظاتك حول مشكلة حالية.

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

هل عثرت على خطأ في تنفيذ Chromium؟ أم أنّ التنفيذ مختلف عن المواصفات؟ عليك الإبلاغ عن الخطأ على new.crbug.com. واحرص على تضمين أكبر قدر ممكن من التفاصيل، وتعليمات بسيطة لإعادة الإنتاج، وتحديد المكوّن على أنّه UI > Browser > Navigation > bfcache. تعمل ميزة Glitch بشكل رائع لمشاركة عمليات إعادة الإنشاء بسرعة وسهولة.

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

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

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

روابط مفيدة