browser.history

الوصف

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

الأذونات

history

للتفاعل مع سجلّ تصفُّح المستخدم، استخدِم واجهة برمجة التطبيقات history API.

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

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

المفاهيم والاستخدام

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

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

أمثلة

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

الأنواع

HistoryItem

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

الخصائص

• id

  سلسلة

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

• lastVisitTime

  number اختيارية

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

• title

  string اختياري

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

• typedCount

  number اختيارية

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

• url

  string اختياري

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

• visitCount

  number اختيارية

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

TransitionType

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من 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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• url

  سلسلة

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

VisitItem

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

الخصائص

• id

  سلسلة

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

• isLocal

  قيمة منطقية

  الإصدار 115 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• referringVisitId

  سلسلة

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

• انتقال

  TransitionType

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

• visitId

  سلسلة

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

• visitTime

  number اختيارية

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

الطُرق

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

المعلمات

• التفاصيل

  UrlDetails

المرتجعات

• وعد<فراغ>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

deleteAll()

browser.history.deleteAll(): Promise<void>

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

المرتجعات

• وعد<فراغ>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

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

المعلمات

• النطاق

  عنصر

  • endTime

    الرقم

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

  • startTime

    الرقم

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

المرتجعات

• وعد<فراغ>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

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

المعلمات

• التفاصيل

  UrlDetails

المرتجعات

• وعد<فراغ>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

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

المعلمات

• التفاصيل

  UrlDetails

المرتجعات

• Promise<VisitItem[]>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

search()

browser.history.search(
  query: object,
): Promise<HistoryItem[]>

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

المعلمات

• query

  عنصر

  • endTime

    number اختيارية

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

  • maxResults

    number اختيارية

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

  • startTime

    number اختيارية

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

  • نصي

    سلسلة

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

المرتجعات

• thought Promise<HistoryItem[]>

  الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onVisited

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

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

المعلمات

• callback

  دالة

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

  (result: HistoryItem) => void

  • نتيجة

    HistoryItem

onVisitRemoved

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

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

المعلمات

• callback

  دالة

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

  (removed: object) => void

  • تمت الإزالة

    عنصر

    • allHistory

      قيمة منطقية

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

    • عناوين url

      string[] اختياري