chrome.history

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

history

البيان

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

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

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

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

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

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

أمثلة

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

الأنواع

HistoryItem

كائن يغلف نتيجة واحدة من طلب بحث في السجلّ

الخصائص

  • id

    سلسلة

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

  • lastVisitTime

    number اختياري

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

  • title

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

    تمثّل هذه السمة عنوان الصفحة عند تحميلها آخر مرة.

  • typedCount

    number اختياري

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

  • url

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

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

  • visitCount

    number اختياري

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

TransitionType

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

تمثّل هذه السمة نوع الانتقال لهذه الزيارة من الموقع الإحالي.

تعداد

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

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

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

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

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

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

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

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

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

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

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

UrlDetails

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

الخصائص

  • url

    سلسلة

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

VisitItem

عنصر يغلف زيارة واحدة إلى عنوان URL.

الخصائص

  • id

    سلسلة

    المعرّف الفريد history.HistoryItem ذي الصلة.

  • isLocal

    قيمة منطقية

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

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

  • referringVisitId

    سلسلة

    معرّف الزيارة الخاص بالمُحيل

  • الانتقال

    TransitionType

    تمثّل هذه السمة نوع الانتقال لهذه الزيارة من الموقع الإحالي.

  • visitId

    سلسلة

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

  • visitTime

    number اختياري

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

الطُرق

addUrl()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

deleteAll()

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

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

المعلمات

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

deleteRange()

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

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

المعلمات

  • النطاق

    عنصر

    • endTime

      الرقم

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

    • startTime

      الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

deleteUrl()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

getVisits()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • callback

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

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

    (results: VisitItem[]) => void

المرتجعات

  • Promise<VisitItem[]>

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

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

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

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

المعلمات

  • query

    عنصر

    • endTime

      number اختياري

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

    • maxResults

      number اختياري

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

    • startTime

      number اختياري

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

    • نصي

      سلسلة

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

  • callback

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

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

    (results: HistoryItem[]) => void

المرتجعات

  • Promise<HistoryItem[]>

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

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

الفعاليات

onVisited

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

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

المعلمات

  • callback

    دالة

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

    (result: HistoryItem) => void

onVisitRemoved

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

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

المعلمات

  • callback

    دالة

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

    (removed: object) => void

    • تمت الإزالة

      عنصر

      • allHistory

        قيمة منطقية

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

      • عناوين url

        string[] اختياري