chrome.history

الوصف

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

الأذونات

history

البيان

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

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

أنواع النقل

تستخدم واجهة برمجة تطبيقات السجلّ نوع نقل لوصف كيفية انتقال المتصفِّح إلى عنوان 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.
"الكلمة الرئيسية التي تم إنشاؤها"يناظر زيارة تم إنشاؤها لكلمة رئيسية. راجع أيضًا الكلمة الرئيسية.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت مثال على واجهة برمجة تطبيقات السجلّ من 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[] اختيارية