chrome.history

الوصف

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

الأذونات

history

للتفاعل مع سجلّ المتصفّح الخاص بالمستخدم، استخدِم History API.

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

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

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

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

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

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال واجهة برمجة التطبيقات 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,
): Promise<void>

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

المعلمات

المرتجعات

  • Promise<void>

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

deleteAll()

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

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

المرتجعات

  • Promise<void>

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

deleteRange()

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

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

المعلمات

  • النطاق

    عنصر

    • endTime

      الرقم

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

    • startTime

      الرقم

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

المرتجعات

  • Promise<void>

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

deleteUrl()

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

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

المعلمات

المرتجعات

  • Promise<void>

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

getVisits()

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

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

المعلمات

المرتجعات

  • Promise<VisitItem[]>

    الإصدار 96 من Chrome والإصدارات الأحدث 
chrome.history.search(
  query: object,
): Promise<HistoryItem[]>

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

المعلمات

  • query

    عنصر

    • endTime

      number اختياري

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

    • maxResults

      number اختياري

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

    • startTime

      number اختياري

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

    • نص

      سلسلة

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

المرتجعات

  • Promise<HistoryItem[]>

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

الفعاليات

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[] اختياري