chrome.history

الوصف

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

الأذونات

history

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

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

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

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

أنواع النقل

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

أمثلة

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

الأنواع

HistoryItem

يشير ذلك المصطلح إلى كائن يغلف نتيجة واحدة لطلب بحث في السجلّ.

أماكن إقامة

  • id

    سلسلة

    المعرّف الفريد للسلعة.

  • lastVisitTime

    الرقم اختياري

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

  • title

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

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

  • typedCount

    الرقم اختياري

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

  • url

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

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

  • visitCount

    الرقم اختياري

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

TransitionType

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

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

Enum

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

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

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

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

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

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

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

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

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

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

"keyword_generate"
تتوافق مع زيارة ناتجة عن كلمة رئيسية.

UrlDetails

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

أماكن إقامة

  • url

    سلسلة

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

VisitItem

يشير هذا المصطلح إلى كائن يغلف زيارة واحدة إلى عنوان URL.

أماكن إقامة

  • id

    سلسلة

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

  • isLocal

    منطقي

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

    صحيح إذا نشأت الزيارة على هذا الجهاز. خطأ إذا تمت مزامنته من جهاز آخر.

  • referringVisitId

    سلسلة

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

  • انتقال

    TransitionType

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

  • visitId

    سلسلة

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

  • visitTime

    الرقم اختياري

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

الطُرق

addUrl()

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

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

المعلمات

  • التفاصيل

    UrlDetails

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

deleteAll()

وعود 
chrome.history.deleteAll(
  callback?: function,
)

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

المعلمات

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

deleteRange()

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

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

المعلمات

  • النطاق

    كائن

    • endTime

      الرقم

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

    • startTime

      الرقم

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

deleteUrl()

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

إزالة جميع مواضع ورود عنوان URL المحدّد من السجلّ.

المعلمات

  • التفاصيل

    UrlDetails

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

getVisits()

وعود 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

المعلمات

  • التفاصيل

    UrlDetails

  • رد الاتصال

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

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

    (results: VisitItem[]) => void

المرتجعات

  • Promise&lt;VisitItem[]&gt;

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

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

وعود 
chrome.history.search(
  query: object,
  callback?: function,
)

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

المعلمات

  • query

    كائن

    • endTime

      الرقم اختياري

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

    • maxResults

      الرقم اختياري

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

    • startTime

      الرقم اختياري

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

    • text

      سلسلة

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

  • رد الاتصال

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

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

    (results: HistoryItem[]) => void

المرتجعات

  • Promise&lt;HistoryItem[]&gt;

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

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

فعاليات

onVisited

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (result: HistoryItem) => void

onVisitRemoved

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (removed: object) => void

    • تمت الإزالة

      كائن

      • allHistory

        منطقي

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

      • عناوين url

        string[] اختيارية