browser.webNavigation

الوصف

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

الأذونات

webNavigation

تتطلّب جميع طرق وأحداث browser.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 وأحداث webNavigation API. ومن الممكن أن تظل أحداث webRequest مستلَمة للإطارات التي بدأت بالفعل عملية تنقّل جديدة، أو أن عملية التنقّل لا تتم إلا بعد تحميل موارد الشبكة بالكامل.

بشكل عام، ترتبط أحداث webNavigation ارتباطًا وثيقًا بحالة التنقّل التي يتم عرضها في واجهة المستخدم، بينما تتوافق أحداث webRequest مع حالة حزمة الشبكة التي تكون غير واضحة للمستخدم بشكل عام.

أرقام تعريف علامات التبويب

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

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

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

أرقام تعريف الإطارات

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

بسبب طبيعة Chrome المتعددة العمليات، قد تستخدم علامة التبويب عمليات مختلفة لعرض مصدر صفحة الويب ووجهتها. لذلك، إذا تم التنقّل في عملية جديدة، قد تتلقّى أحداثًا من الصفحة الجديدة والقديمة إلى أن يتم تنفيذ عملية التنقّل الجديدة (أي يتم إرسال الحدث onCommitted للإطار الرئيسي الجديد). In other words, it is possible to have more than one pending sequence of webNavigation events with the same frameId. يمكن تمييز التسلسلات باستخدام مفتاح processId.

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

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

أنواع الانتقال والمحدِّدات

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

تتوفّر الشروط التالية للانتقال:

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

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال webNavigation API من مستودع chrome-extension-samples.

الأنواع

TransitionQualifier

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

الطُرق

getAllFrames()

browser.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

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

المعلمات

  • التفاصيل

    عنصر

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

    • tabId

      الرقم

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

المرتجعات

  • ‫Promise<object[] | undefined>

    الإصدار 93 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getFrame()

browser.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

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

المعلمات

  • التفاصيل

    عنصر

    معلومات عن الإطار المطلوب الحصول على معلومات عنه

    • documentId

      string اختياري

      الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

      المعرّف الفريد العالمي (UUID) للمستند إذا تم تقديم frameId و/أو tabId، سيتم التحقّق من صحتهما لمطابقة المستند الذي تم العثور عليه من خلال رقم تعريف المستند المقدَّم.

    • frameId

      number اختيارية

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

    • processId

      number اختيارية

      تم إيقافها نهائيًا منذ الإصدار 49 من Chrome

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

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

    • tabId

      number اختيارية

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

المرتجعات

  • Promise<object | undefined>

    الإصدار 93 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onBeforeNavigate

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

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

      • processId

        الرقم

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

        لم يعُد يتم ضبط processId لهذا الحدث، لأنّ العملية التي ستعرض المستند الناتج غير معروفة حتى onCommit.

        القيمة -1.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي سيتم التنقّل فيها

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onCommitted

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل المعالج لهذا الإطار

      • tabId

        الرقم

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

      • timeStamp

        الرقم

        وقت تنفيذ عملية التنقّل، بالمللي ثانية منذ بدء حساب الفترة

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onCompleted

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل المعالج لهذا الإطار

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onCreatedNavigationTarget

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • sourceFrameId

        الرقم

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

      • sourceProcessId

        الرقم

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

      • sourceTabId

        الرقم

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

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

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onDOMContentLoaded

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل المعالج لهذا الإطار

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onErrorOccurred

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • خطأ

        سلسلة

        وصف الخطأ

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

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

        لم يعُد معرّف العملية (processId) محدّدًا لهذا الحدث.

        القيمة -1.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onHistoryStateUpdated

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل المعالج لهذا الإطار

      • tabId

        الرقم

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

      • timeStamp

        الرقم

        وقت تنفيذ عملية التنقّل، بالمللي ثانية منذ بدء حساب الفترة

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onReferenceFragmentUpdated

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

        مرحلة النشاط التي يمر بها المستند

      • frameId

        الرقم

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

      • الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentDocumentId

        string اختياري

        الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • parentFrameId

        الرقم

        الإصدار 74 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل المعالج لهذا الإطار

      • tabId

        الرقم

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

      • timeStamp

        الرقم

        وقت تنفيذ عملية التنقّل، بالمللي ثانية منذ بدء حساب الفترة

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    object اختياري

    • الشروط التي يجب أن يستوفيها عنوان URL الذي يتم الانتقال إليه

onTabReplaced

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • replacedTabId

        الرقم

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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