chrome.history

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.history للتفاعل مع سجلّ المتصفّح للصفحات التي تمت زيارتها. يمكنك إضافة عناوين URL وإزالتها والاستعلام عنها في سجلّ المتصفّح. لتجاوز صفحة السجلّ بنسختك الخاصة، يُرجى الاطّلاع على تجاوز الصفحات.

الأذونات

history

يؤدي هذا الإذن إلى ظهور تحذير.

البيان

يجب الإفصاح عن إذن "السجلّ" في بيان الإضافة لاستخدام واجهة برمجة التطبيقات الخاصة بالسجلّ. على سبيل المثال:

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

أنواع الانتقال

تستخدم واجهة برمجة التطبيقات History API نوع انتقال لوصف كيفية انتقال المتصفّح إلى عنوان URL معيّن في زيارة معيّنة. على سبيل المثال، إذا زار مستخدم صفحة من خلال النقر على رابط في صفحة أخرى، يكون نوع الانتقال هو "رابط".

يوضّح الجدول التالي كل نوع من أنواع الانتقال.

نوع الانتقال	الوصف
"link"	وصل المستخدم إلى هذه الصفحة من خلال النقر على رابط في صفحة أخرى.
"typed"	وصل المستخدم إلى هذه الصفحة من خلال كتابة عنوان URL في شريط العناوين. يُستخدم أيضًا لإجراءات التنقّل الصريحة الأخرى. يُرجى أيضًا الاطّلاع على generated، الذي يُستخدَم في الحالات التي اختار فيها المستخدم خيارًا لا يشبه عنوان URL على الإطلاق.
"auto_bookmark"	وصل المستخدم إلى هذه الصفحة من خلال اقتراح في واجهة المستخدم، على سبيل المثال، من خلال عنصر قائمة.
"auto_subframe"	التنقّل في الإطار الفرعي يشير ذلك إلى أي محتوى يتم تحميله تلقائيًا في إطار غير ذي مستوى أعلى. على سبيل المثال، إذا كانت الصفحة تتألف من عدة إطارات تحتوي على إعلانات، فإنّ عناوين URL الخاصة بهذه الإعلانات تكون من نوع الانتقال هذا. قد لا يدرك المستخدم أنّ المحتوى في هذه الصفحات هو إطار منفصل، وبالتالي قد لا يهتم بعنوان URL (راجِع أيضًا manual_subframe).
"manual_subframe"	بالنسبة إلى عمليات التنقّل في الإطارات الفرعية التي يطلبها المستخدم صراحةً وتنشئ إدخالات تنقّل جديدة في قائمة الرجوع/التقديم. من المرجّح أن يكون الإطار المطلوب صراحةً أكثر أهمية من الإطار الذي يتم تحميله تلقائيًا لأنّ المستخدم على الأرجح يهتم بحقيقة تحميل الإطار المطلوب.
"generated"	وصل المستخدم إلى هذه الصفحة من خلال الكتابة في شريط العناوين واختيار إدخال لا يشبه عنوان URL. على سبيل المثال، قد يتضمّن التطابق عنوان URL لصفحة نتائج بحث من Google، ولكن قد يظهر للمستخدم على النحو التالي: "البحث في Google عن ...". لا تتطابق هذه العناوين تمامًا مع عمليات الانتقال المكتوبة لأنّ المستخدم لم يكتب عنوان URL المقصود أو يطّلِع عليه. يمكنك أيضًا الاطّلاع على الكلمة الرئيسية.
"auto_toplevel"	تم تحديد الصفحة في سطر الأوامر أو هي صفحة البدء.
"form_submit"	ملأ المستخدم القيم في نموذج وأرسله. يُرجى العِلم أنّه في بعض الحالات، مثل عندما يستخدم نموذج نصًا برمجيًا لإرسال المحتوى، لا يؤدي إرسال النموذج إلى نوع الانتقال هذا.
"reload"	أعاد المستخدم تحميل الصفحة، إما بالنقر على زر إعادة التحميل أو بالضغط على مفتاح Enter في شريط العناوين. يستخدم هذا النوع من الانتقال أيضًا ميزتَي "استعادة الجلسة" و"إعادة فتح علامة التبويب المغلقة".
"الكلمة الرئيسية"	تم إنشاء عنوان URL من كلمة رئيسية قابلة للاستبدال غير مقدِّم محرّك البحث التلقائي. يمكنك أيضًا الاطّلاع على keyword_generated.
"keyword_generated"	يتوافق مع زيارة تم إنشاؤها لكلمة رئيسية. يمكنك أيضًا الاطّلاع على الكلمة الرئيسية.

أمثلة

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

الأنواع

HistoryItem

عنصر يتضمّن نتيجة واحدة لطلب بحث في السجلّ

الخصائص

• id

  سلسلة

  المعرّف الفريد للعنصر

• lastVisitTime

  number اختيارية

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

• title

  string اختياري

  عنوان الصفحة عند آخر تحميل لها

• typedCount

  number اختيارية

  عدد المرات التي انتقل فيها المستخدم إلى هذه الصفحة عن طريق كتابة العنوان.

• url

  string اختياري

  عنوان URL الذي انتقل إليه المستخدم

• visitCount

  number اختيارية

  عدد المرات التي انتقل فيها المستخدم إلى هذه الصفحة.

TransitionType

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

نوع الانتقال لهذه الزيارة من المُحيل

Enum

"link"
وصل المستخدم إلى هذه الصفحة من خلال النقر على رابط في صفحة أخرى.

"typed"
وصل المستخدم إلى هذه الصفحة عن طريق كتابة عنوان URL في شريط العناوين. ويُستخدم أيضًا لإجراءات التنقّل الصريحة الأخرى.

"auto_bookmark"
وصل المستخدم إلى هذه الصفحة من خلال اقتراح في واجهة المستخدم، على سبيل المثال، من خلال عنصر في القائمة.

‫"auto_subframe"
وصل المستخدم إلى هذه الصفحة من خلال التنقّل في إطار فرعي لم يطلبه، مثلاً من خلال تحميل الإعلان في إطار على الصفحة السابقة. ولا تؤدي هذه الإجراءات دائمًا إلى إنشاء إدخالات تنقّل جديدة في قائمتَي "الرجوع" و"التقديم".

"manual_subframe"
وصل المستخدم إلى هذه الصفحة من خلال اختيار عنصر في إطار فرعي.

"generated"
وصل المستخدم إلى هذه الصفحة من خلال الكتابة في شريط العناوين واختيار إدخال لا يشبه عنوان URL، مثل اقتراح بحث من "بحث Google". على سبيل المثال، قد تحتوي المطابقة على عنوان URL لصفحة نتائج بحث Google، ولكن قد تظهر للمستخدم على النحو التالي: "البحث في Google عن ...". تختلف هذه المطابقات عن عمليات التنقّل المكتوبة لأنّ المستخدم لم يكتب عنوان URL المقصود أو يطّلِع عليه. وهي مرتبطة أيضًا بعمليات التنقّل باستخدام الكلمات الرئيسية.

‫"auto_toplevel"
تم تحديد الصفحة في سطر الأوامر أو أنّها صفحة البدء.

"form_submit"
وصل المستخدِم إلى هذه الصفحة من خلال ملء القيم في نموذج وإرساله. لا تستخدم جميع عمليات إرسال النماذج نوع الانتقال هذا.

"reload"
أعاد المستخدم تحميل الصفحة، إما بالنقر على زر إعادة التحميل أو بالضغط على مفتاح Enter في شريط العناوين. تستخدم ميزتا "استعادة الجلسة" و"إعادة فتح علامة التبويب المغلقة" أيضًا نوع الانتقال هذا.

"keyword"
تم إنشاء عنوان URL لهذه الصفحة من كلمة رئيسية قابلة للاستبدال غير مقدِّم محرّك البحث التلقائي.

‫"keyword_generated"
تتوافق مع زيارة تم إنشاؤها لكلمة رئيسية.

UrlDetails

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

الخصائص

• url

  سلسلة

  عنوان URL للعملية يجب أن يكون بالتنسيق الذي تم عرضه من خلال طلب إلى history.search().

VisitItem

عنصر يمثّل زيارة واحدة لعنوان URL

الخصائص

• id

  سلسلة

  المعرّف الفريد لـ history.HistoryItem المقابل.

• isLocal

  قيمة منطقية

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

  تكون القيمة "صحيح" إذا كانت الزيارة قد بدأت على هذا الجهاز. وتكون القيمة "خطأ" إذا تمت مزامنتها من جهاز آخر.

• referringVisitId

  سلسلة

  رقم تعريف زيارة المُحيل

• انتقال

  TransitionType

  نوع الانتقال لهذه الزيارة من المُحيل

• visitId

  سلسلة

  المعرّف الفريد لهذه الزيارة

• visitTime

  number اختيارية

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

الطُرق

addUrl()

Promise

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

تضيف هذه الطريقة عنوان URL إلى السجلّ في الوقت الحالي مع نوع انتقال "رابط".

المعلمات

• التفاصيل

  UrlDetails

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

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

deleteAll()

Promise

chrome.history.deleteAll(
  callback?: function,
): Promise<void>

لحذف جميع العناصر من السجلّ

المعلمات

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

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

deleteRange()

Promise

chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

لإزالة جميع العناصر ضمن النطاق الزمني المحدّد من السجلّ لن تتم إزالة الصفحات من السجلّ إلا إذا كانت جميع الزيارات تقع ضمن النطاق.

المعلمات

• النطاق

  عنصر

  • endTime

    الرقم

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

  • startTime

    الرقم

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

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

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

deleteUrl()

Promise

chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

تزيل هذه الطريقة جميع تكرارات عنوان URL المحدّد من السجلّ.

المعلمات

• التفاصيل

  UrlDetails

• callback

  function اختياري

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

  () => void

المرتجعات

• وعد<فراغ>

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

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

getVisits()

Promise

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

تسترد معلومات عن الزيارات إلى عنوان URL.

المعلمات

• التفاصيل

  UrlDetails

• callback

  function اختياري

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

  (results: VisitItem[]) => void

  • النتائج

    VisitItem[]

المرتجعات

• Promise<VisitItem[]>

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

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

search()

Promise

chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

للبحث في السجلّ عن وقت آخر زيارة لكل صفحة تطابق طلب البحث.

المعلمات

• query

  عنصر

  • endTime

    number اختيارية

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

  • maxResults

    number اختيارية

    الحد الأقصى لعدد النتائج التي يمكن استردادها. القيمة التلقائية هي 100.

  • startTime

    number اختيارية

    يتم حصر النتائج في تلك التي تمت زيارتها بعد هذا التاريخ، ويتم تمثيلها بالملي ثانية منذ بدء حساب الفترة. إذا لم يتم تحديد السمة، سيتم ضبطها تلقائيًا على 24 ساعة.

  • نصي

    سلسلة

    طلب بحث بنص حر لخدمة السجلّ اترك هذا الحقل فارغًا لاسترداد جميع الصفحات.

• callback

  function اختياري

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

  (results: HistoryItem[]) => void

  • النتائج

    HistoryItem[]

المرتجعات

• thought Promise<HistoryItem[]>

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

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

الفعاليات

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

يتم تشغيل هذا الحدث عند زيارة عنوان URL، ما يوفّر بيانات HistoryItem لعنوان URL هذا. يتم تنشيط هذا الحدث قبل تحميل الصفحة.

المعلمات

• callback

  دالة

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

  (result: HistoryItem) => void

  • نتيجة

    HistoryItem

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

يتم تنشيطه عند إزالة عنوان URL واحد أو أكثر من السجلّ. عند إزالة جميع الزيارات، تتم إزالة عنوان URL نهائيًا من السجلّ.

المعلمات

• callback

  دالة

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

  (removed: object) => void

  • تمت الإزالة

    عنصر

    • allHistory

      قيمة منطقية

      صحيح إذا تمت إزالة السجلّ بالكامل. إذا كانت القيمة "صحيح"، ستكون عناوين URL فارغة.

    • عناوين url

      string[] اختياري