chrome.history

الوصف

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

الأذونات

history

البيان

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

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

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

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

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

نوع الانتقالالوصف
"typed"وصل المستخدم إلى هذه الصفحة من خلال كتابة عنوان URL في شريط العناوين. يُستخدم أيضًا لإجراءات التنقّل الصريحة الأخرى. راجِع أيضًا تم إنشاؤه، والذي يُستخدَم في الحالات التي يختار فيها المستخدم خيارًا لا يشبه عنوان 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 والإصدارات الأحدث

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

Enum

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

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

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

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

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

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

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

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

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

"keyword"
تم إنشاء عنوان 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>

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

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

deleteAll()

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

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

المعلمات

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

deleteRange()

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

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

المعلمات

  • النطاق

    عنصر

    • endTime

      الرقم

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

    • startTime

      الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

deleteUrl()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

getVisits()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • callback

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

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

    (results: VisitItem[]) => void

المرتجعات

  • Promise<VisitItem[]>

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

    لا تتوافق الوعود إلا مع الإصدار 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[]>

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

    لا تتوافق الوعود إلا مع الإصدار 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[] اختياري