chrome.webNavigation

الوصف

يمكنك استخدام واجهة برمجة التطبيقات chrome.webNavigation لتلقّي الإشعارات عن حالة طلبات التنقّل أثناء الطيران.

الأذونات

webNavigation

تتطلّب منك جميع طُرق وأحداث chrome.webNavigation تقديم بيان عن إذن "webNavigation" في بيان الإضافة. مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

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

ترتيب الحدث

بالنسبة إلى عملية التنقّل التي يتم إكمالها بنجاح، يتم تنشيط الأحداث بالترتيب التالي:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

وأي خطأ يحدث أثناء العملية سيؤدي إلى حدث onErrorOccurred. بالنسبة إلى التنقّل المحدّد، ما مِن أحداث أخرى يتم تنشيطها بعد onErrorOccurred.

إذا كان إطار التنقّل يحتوي على إطارات فرعية، يتم تفعيل onCommitted قبل أي من الإطارات onBeforeNavigate الثانوية الخاصة به، بينما يتم تنشيط onCompleted بعد كل عناصر onCompleted الثانوية.

وإذا تم تغيير الجزء المرجعي لإطار، يتم تنشيط حدث onReferenceFragmentUpdated. يمكن تنشيط هذا الحدث في أي وقت بعد onDOMContentLoaded، حتى بعد onCompleted.

في حال استخدام History API لتعديل حالة الإطار (مثلاً باستخدام history.pushState()، يتم تنشيط حدث onHistoryStateUpdated. يمكن تنشيط هذا الحدث في أي وقت بعد onDOMContentLoaded.

إذا استعاد التنقّل صفحة من التخزين المؤقت للصفحات، لن يتم تنشيط الحدث onDOMContentLoaded. لا يتم تنشيط الحدث لأنّ المحتوى قد اكتمل تحميل المحتوى عند زيارة الصفحة لأول مرة.

إذا تم بدء عملية تنقّل باستخدام البحث الفوري من Chrome أو الصفحات الفورية، يتم نقل الصفحة التي تم تحميلها بالكامل إلى علامة التبويب الحالية. وفي هذه الحالة، يتم تنشيط حدث "onTabReplaced".

العلاقة بأحداث WebRequest

لا يوجد ترتيب محدّد بين أحداث webRequest API وأحداث Web Navigation API. من الممكن أن يستمر تلقّي أحداث webRequest للإطارات التي بدأت فعلاً انتقالاً جديدًا، أو أن لا يتم متابعة التنقل إلا بعد تحميل موارد الشبكة بالكامل مسبقًا.

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

معرّفات علامات التبويب

لا تتوافق كل علامات تبويب التنقل مع علامات التبويب الفعلية في واجهة المستخدم في Chrome، مثل علامة تبويب يتم عرضها مسبقًا. لا يمكن الوصول إلى علامات التبويب هذه باستخدام Tabs API ولا يمكنك طلب معلومات عنها من خلال الاتصال بـ webNavigation.getFrame() أو webNavigation.getAllFrames(). بعد تبديل علامة التبويب هذه، يتم تنشيط حدث onTabReplaced ويصبح بالإمكان الوصول إليها من خلال واجهات برمجة التطبيقات هذه.

الطوابع الزمنية

تجدر الإشارة إلى أن بعض الانحرافات الفنية في التعامل مع عمليات Chrome المختلفة قد تتسبب في انحراف الساعة بين المتصفح نفسه وعمليات الإضافات. هذا يعني أنه يمكن ضمان اتساق خاصية timeStamp WebNavigation الحدث timeStamp داخليًا. وعند مقارنة حدث بحدث آخر، ستحصل على معادلة صحيحة بينهما، لكن مقارنتهما بالوقت الحالي داخل الإضافة (باستخدام (new Date()).getTime() مثلاً) قد تؤدي إلى نتائج غير متوقعة.

معرّفات الإطارات

يمكن تحديد اللقطات داخل علامة تبويب من خلال معرِّف إطار. معرّف الإطار للإطار الرئيسي هو 0 دائمًا، ورقم تعريف الإطارات الفرعية هو رقم موجب. بعد إنشاء مستند في إطار، يظل معرّف الإطار ثابتًا خلال فترة بقاء المستند. وبدءًا من Chrome 49، يظل هذا المعرّف ثابتًا أيضًا طوال عمر الإطار (عبر عمليات التنقّل المتعددة).

بسبب طبيعة Chrome المتعدّدة العمليات، قد تستخدم علامة التبويب عمليات مختلفة لعرض مصدر ووجهة صفحة الويب. وبالتالي، في حال إجراء عملية تنقّل ضمن عملية جديدة، قد تتلقّى أحداثًا من الصفحة الجديدة والقديمة إلى أن يتم تنفيذ عملية التنقّل الجديدة (أي إرسال حدث onCommitted للإطار الرئيسي الجديد). وبعبارة أخرى، من الممكن أن يكون لديك أكثر من تسلسل واحد معلق لأحداث Webnavigation باستخدام frameId نفسه. ويمكن تمييز التسلسلات باستخدام المفتاح processId.

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

هناك مفهوم آخر يمثل مشكلة في الإضافات وهو دورة حياة الإطار. يستضيف الإطار مستندًا (مرتبطًا بعنوان URL مخصص). يمكن أن يتغير المستند (من خلال التنقل مثلاً) إلا أنّ frameId لن تتغير، لذا من الصعب ربط أن شيئًا ما حدث في مستند معين بـ frameIds فقط. نقدّم مفهومًا عن documentId، وهو معرِّف فريد لكل مستند. إذا تم التنقل في إطار وفتح مستند جديدًا، فإن المعرف سيتغير. يُعدّ هذا الحقل مفيدًا في تحديد الوقت الذي تغيّر فيه حالة الصفحات خلال نشاطها (بين العرض المُسبَق/النشط/التخزين المؤقت) لأنها تظل كما هي.

أنواع الانتقال ومؤهِّلاته

يتضمّن حدث onCommitted webNavigation السمة transitionType والسمة transitionQualifiers. نوع النقل هو نفسه المستخدَم في واجهة برمجة التطبيقات للسجلّ والذي يصف طريقة انتقال المتصفّح إلى عنوان URL هذا تحديدًا. بالإضافة إلى ذلك، يمكن عرض العديد من مؤهِّلات النقل التي تحدِّد التنقّل بشكل أكبر.

مؤهلات الانتقال التالية:

مؤهِّل الانتقال	الوصف
"client_redirect"	تمت عملية إعادة توجيه واحدة أو أكثر ناتجة عن علامات JavaScript أو علامات إعادة التحميل الوصفية على الصفحة أثناء التنقّل.
"server_redirect"	تمت عملية إعادة توجيه واحدة أو أكثر ناتجة عن عناوين HTTP المُرسَلة من الخادم أثناء التنقّل.
"forward_back"	استخدم المستخدم الزر "أمام" أو "رجوع" لبدء التنقل.
"from_address_bar"	بدأ المستخدم عملية التنقّل من شريط العناوين (المعروف أيضًا باسم "المربّع المتعدد الاستخدامات").

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت مثال web Navigation API من مستودع chrome-extension-pattern.

الأنواع

TransitionQualifier

Chrome 44 والإصدارات الأحدث

التعداد

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 والإصدارات الأحدث

سبب التنقّل يتم استخدام أنواع عمليات النقل نفسها كما هو محدَّد في History API. هذه هي أنواع عمليات النقل نفسها كما هو محدّد في history API، باستثناء "start_page" بدلاً من "auto_toplevel" (للتوافق مع الأنظمة القديمة).

التعداد

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"start_page"

"form_submit"

الطُرق

getAllFrames()

وعد

chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

تسترجع المعلومات حول جميع الإطارات في علامة تبويب معينة.

المَعلمات

• التفاصيل

  كائن

  معلومات حول علامة التبويب لاسترداد جميع الإطارات منها.

  • tabId

    الرقم

    رقم تعريف علامة التبويب.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (details?: object[])=>void

  • التفاصيل

    object[] اختياري

    قائمة بالإطارات في علامة التبويب المحدّدة تكون قيمة فارغة إذا كان رقم تعريف علامة التبويب المحدّد غير صالح.

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • errorOccurred

      boolean

      صحيح إذا تمت مقاطعة آخر عملية تنقُّل في هذا الإطار بسبب خطأ، أي أنّه تم تنشيط حدث onErrorOccurred

    • frameId

      الرقم

      رقم تعريف الإطار يشير 0 إلى أن هذا هو الإطار الرئيسي؛ وتشير القيمة الموجبة إلى معرف الإطار الفرعي.

    • frameType

      FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • url

      سلسلة

      تمثّل هذه السمة عنوان URL المرتبط حاليًا بهذا الإطار.

المرتجعات

• Promise<object[]|undefined>

  Chrome 93 والإصدارات الأحدث

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

getFrame()

وعد

chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

يسترد معلومات حول الإطار المحدد. يشير الإطار إلى إطار <iframe> أو <frame> لصفحة ويب، ويتم تحديده باستخدام معرّف علامة تبويب ومعرّف إطار.

المَعلمات

• التفاصيل

  كائن

  معلومات حول الإطار لاسترداد المعلومات عنه.

  • documentId

    سلسلة اختيارية

    Chrome 106 والإصدارات الأحدث

    المعرِّف الفريد العالمي للمستند. إذا تم تقديم معرّف الإطار و/أو رقم TabId، سيتم التحقّق من صحتهما لمطابقة المستند الذي تم العثور عليه من خلال معرّف المستند الذي تم تقديمه.

  • frameId

    الرقم اختياري

    رقم تعريف الإطار في علامة التبويب المحدّدة.

  • processId

    الرقم اختياري

    تم إيقافها نهائيًا منذ Chrome 49

    يتم الآن تحديد اللقطات بشكلٍ فريد من خلال رقم تعريف علامة التبويب ومعرّف الإطار؛ ولم يعد رقم تعريف العملية مطلوبًا، وبالتالي سيتم تجاهله.

    تمثّل هذه السمة رقم تعريف العملية التي تؤدي إلى تشغيل العارض لعلامة التبويب هذه.

  • tabId

    الرقم اختياري

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

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (details?: object)=>void

  • التفاصيل

    الكائن اختياري

    تكون المعلومات حول الإطار المطلوب فارغة إذا كان رقم تعريف الإطار و/أو رقم تعريف علامة التبويب المحدَّد غير صالحَين.

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • errorOccurred

      boolean

      صحيح إذا تمت مقاطعة آخر عملية تنقُّل في هذا الإطار بسبب خطأ، أي أنّه تم تنشيط حدث onErrorOccurred

    • frameType

      FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • url

      سلسلة

      عنوان URL المرتبط حاليًا بهذا الإطار، إذا كان الإطار الذي تم تحديده من خلالframeId متوفّرًا في مرحلة ما ضمن علامة التبويب المحدّدة. وارتباط عنوان URL بمعرّف إطار معين لا يعني أن الإطار المقابل لا يزال متوفرًا.

المرتجعات

• Promise<object|undefined>

  Chrome 93 والإصدارات الأحدث

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

فعاليات

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عندما يكون التنقّل على وشك الحدوث.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. تكون أرقام تعريف الإطارات فريدة لعلامة تبويب معيّنة وعملية معيّنة.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      تم إيقافه منذ إصدار 50 من Chrome

      لم يعُد معرّف العملية محدّدًا لهذا الحدث، لأنّ العملية التي ستعرض المستند الناتج لا تكون معروفة حتى موقع onCommit.

      قيمة -1.

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يوشك التنقل فيها على أن يحدث.

    • timeStamp

      الرقم

      الوقت الذي كان فيه المتصفِّح على وشك بدء عملية التنقّل بالمللي ثانية منذ الفترة التي بدأ فيها المتصفِّح

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      الوقت الذي تم فيه تنفيذ التنقّل، بالمللي ثانية منذ الفترة

    • transitionQualifiers

      TransitionQualifier[]

      قائمة بمؤهِّلات الانتقال.

    • transitionType

      TransitionType

      سبب التنقّل

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند تحميل وتهيئة مستند بالكامل، بما في ذلك الموارد التي يشير إليها.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      الوقت الذي انتهى فيه تحميل المستند بالمللي ثانية منذ تاريخ انتهاء تحميل المستند

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند إنشاء نافذة جديدة أو علامة تبويب جديدة في نافذة حالية لاستضافة عملية تنقُّل.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • sourceFrameId

      الرقم

      رقم تعريف الإطار الذي يتضمّن sourceTabId الذي يظهر فيه التنقّل. يشير الرقم 0 إلى الإطار الرئيسي.

    • sourceProcessId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض للإطار المصدر

    • sourceTabId

      الرقم

      رقم تعريف علامة التبويب التي يتم تشغيل التنقّل فيها.

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي تم فتح عنوان URL فيها

    • timeStamp

      الرقم

      الوقت الذي كان فيه المتصفِّح على وشك إنشاء طريقة عرض جديدة، بالمللي ثانية منذ تلك الفترة.

    • url

      سلسلة

      عنوان URL الذي سيتم فتحه في النافذة الجديدة.

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند اكتمال إنشاء DOM للصفحة بالكامل، ولكن قد لا ينتهي تحميل الموارد المُشار إليها.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      الوقت الذي تم فيه إنشاء نموذج العناصر في المستند (DOM) للصفحة بالكامل، بالمللي ثانية منذ البداية.

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند حدوث خطأ وإلغاء التنقّل. ويمكن أن يحدث ذلك في حال حدوث خطأ في الشبكة، أو إلغاء المستخدم لعملية التنقُّل.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • خطأ

      سلسلة

      وصف الخطأ

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      تم إيقافه منذ إصدار 50 من Chrome

      لم يعد رقم العملية محدّدًا لهذا الحدث.

      قيمة -1.

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      وقت حدوث الخطأ بالمللي ثانية منذ تاريخ حدوثه

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند تعديل سجلّ الإطار إلى عنوان URL جديد. وستستخدِم جميع الأحداث المستقبلية لهذا الإطار عنوان URL المعدَّل.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      الوقت الذي تم فيه تنفيذ التنقّل، بالمللي ثانية منذ الفترة

    • transitionQualifiers

      TransitionQualifier[]

      قائمة بمؤهِّلات الانتقال.

    • transitionType

      TransitionType

      سبب التنقّل

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند تعديل الجزء المرجعي لإطار ما. وستستخدِم جميع الأحداث المستقبلية لهذا الإطار عنوان URL المعدَّل.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • documentId

      سلسلة

      Chrome 106 والإصدارات الأحدث

      معرّف المستخدم الفريد (UUID) للمستند الذي تم تحميله

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 والإصدارات الأحدث

      دورة حياة المستند.

    • frameId

      الرقم

      0 يشير إلى أن التنقل يحدث في نافذة محتوى علامة التبويب؛ وتشير القيمة الموجبة إلى التنقل في إطار فرعي. معرّفات الإطارات فريدة داخل علامة التبويب.

    • frameType

      extensionTypes.FrameType

      Chrome 106 والإصدارات الأحدث

      نوع الإطار الذي حدث فيه التنقّل.

    • parentDocumentId

      سلسلة اختيارية

      Chrome 106 والإصدارات الأحدث

      معرّف فريد عالمي (UUID) للمستند الرئيسي الذي يحتوي على هذا الإطار لا يتم ضبط هذا الإعداد في حال عدم توفّر عنصر رئيسي.

    • parentFrameId

      الرقم

      الإصدار 74 من Chrome والإصدارات الأحدث

      رقم تعريف الإطار الرئيسي، أو -1 إذا كان هذا هو الإطار الرئيسي

    • processId

      الرقم

      رقم تعريف العملية التي تؤدي إلى تشغيل العارض لهذا الإطار

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي يحدث فيها التنقّل.

    • timeStamp

      الرقم

      الوقت الذي تم فيه تنفيذ التنقّل، بالمللي ثانية منذ الفترة

    • transitionQualifiers

      TransitionQualifier[]

      قائمة بمؤهِّلات الانتقال.

    • transitionType

      TransitionType

      سبب التنقّل

    • url

      سلسلة

• الفلاتر

  الكائن اختياري

  • url

    events.UrlFilter[]

    الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليها. ويتم تجاهل حقلَي "schemes" و"ports" لـ UrlFilter في هذا الحدث.

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

يتم تنشيطها عند استبدال محتوى علامة التبويب بعلامة تبويب مختلفة (تم عرضها مسبقًا عادةً).

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (details: object)=>void

  • التفاصيل

    كائن

    • replacedTabId

      الرقم

      رقم تعريف علامة التبويب التي تم استبدالها.

    • tabId

      الرقم

      رقم تعريف علامة التبويب التي حلّت محل علامة التبويب القديمة.

    • timeStamp

      الرقم

      الوقت الذي حدث فيه الاستبدال بالمللي ثانية منذ البداية