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

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

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

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

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

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

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

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

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

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

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

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

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

تتوفّر مؤهلات النقل التالية:

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

أمثلة

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

الأنواع

TransitionQualifier

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

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

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

سبب التنقّل يتم استخدام أنواع الانتقال نفسها المحدّدة في واجهة برمجة تطبيقات السجلّ. هذه هي أنواع الانتقال نفسها المحدّدة في 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()

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

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

المعلمات

  • التفاصيل

    عنصر

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

    • tabId

      الرقم

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

المرتجعات

  • Promise<object[] | undefined>

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

getFrame()

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

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

المعلمات

  • التفاصيل

    عنصر

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

    • documentId

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

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

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

    • frameId

      number اختياري

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

    • processId

      number اختياري

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

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

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

    • tabId

      number اختياري

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

المرتجعات

  • Promise<object | undefined>

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

الفعاليات

onBeforeNavigate

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

يتم إطلاقه عندما سيحدث تنقّل.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • processId

        الرقم

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

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

        قيمة -1

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onCommitted

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل أداة العرض لهذه اللقطة.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onCompleted

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل أداة العرض لهذه اللقطة.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onCreatedNavigationTarget

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • sourceFrameId

        الرقم

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

      • sourceProcessId

        الرقم

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

      • sourceTabId

        الرقم

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

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

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onDOMContentLoaded

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل أداة العرض لهذه اللقطة.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onErrorOccurred

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • خطأ

        سلسلة

        وصف الخطأ

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

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

        لم يعُد يتم ضبط processId لهذا الحدث.

        قيمة -1

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onHistoryStateUpdated

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل أداة العرض لهذه اللقطة.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onReferenceFragmentUpdated

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

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

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

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

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

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

      • processId

        الرقم

        رقم تعريف العملية التي تشغّل أداة العرض لهذه اللقطة.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • transitionQualifiers

        TransitionQualifier[]

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

      • transitionType

        TransitionType

        سبب التنقّل

      • url

        سلسلة

  • الفلاتر

    العنصر اختياري

    • url

      ‫events.UrlFilter[]

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

onTabReplaced

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • replacedTabId

        الرقم

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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