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، مثل علامة التبويب التي يتم عرضها مسبقًا. لا يمكن الوصول إلى هذه العلامات من خلال واجهة برمجة التطبيقات الخاصة بالعلامات، كما لا يمكنك طلب معلومات عنها من خلال webNavigation.getFrame أو webNavigation.getAllFrames. وبعد تبديل علامة التبويب هذه، يتم تنشيط الحدث onTabReplaced، ويمكن الوصول إلى علامات التبويب من خلال واجهات برمجة التطبيقات هذه.

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

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

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

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

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

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

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

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

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

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

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

أمثلة

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

الأنواع

TransitionQualifier

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

تعداد

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

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

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

تعداد

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

الطُرق

getAllFrames()

وعد 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
): Promise<object[] | undefined>

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

المعلمات

  • التفاصيل

    عنصر

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

    • tabId

      الرقم

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

  • callback

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

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

    (details?: object[]) => void

    • التفاصيل

      object[] اختيارية

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

      • documentId

        سلسلة

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

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

      • documentLifecycle

        DocumentLifecycle

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

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

      • errorOccurred

        قيمة منطقية

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

      • frameId

        الرقم

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

      • frameType

        FrameType

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • processId

        الرقم

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

      • url

        سلسلة

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

المرتجعات

  • Promise<object[] | undefined>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات رد الاتصال.

getFrame()

وعد 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
): Promise<object | undefined>

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

المعلمات

  • التفاصيل

    عنصر

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

    • documentId

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

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

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

    • frameId

      number اختيارية

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

    • processId

      number اختيارية

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

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

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

    • tabId

      number اختيارية

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

  • callback

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

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

    (details?: object) => void

    • التفاصيل

      عنصر اختياري

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

      • documentId

        سلسلة

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

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

      • documentLifecycle

        DocumentLifecycle

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

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

      • errorOccurred

        قيمة منطقية

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

      • frameType

        FrameType

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

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

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • url

        سلسلة

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

المرتجعات

  • Promise<object | undefined>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات رد الاتصال.

الفعاليات

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

        الرقم

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