chrome.history

الوصف

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

الأذونات

history

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

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

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

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

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

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

أمثلة

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

الأنواع

HistoryItem

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

أماكن إقامة

  • id

    سلسلة

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

  • lastVisitTime

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

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

  • title

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

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

  • typedCount

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

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

  • url

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

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

  • visitCount

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

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

TransitionType

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

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

التعداد

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

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

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

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

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

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

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

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

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

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

"keyword_generated"
مقابل زيارة تم إنشاؤها لإحدى الكلمات الرئيسية

UrlDetails

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

أماكن إقامة

  • url

    سلسلة

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

VisitItem

عنصر يضم زيارة واحدة إلى عنوان URL

أماكن إقامة

  • id

    سلسلة

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

  • isLocal

    boolean

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

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

  • referringVisitId

    سلسلة

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

  • انتقال

    TransitionType

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

  • visitId

    سلسلة

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

  • visitTime

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

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

الطُرق

addUrl()

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

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

المَعلمات

  • التفاصيل

    UrlDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

deleteAll()

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

يؤدي إلى حذف جميع العناصر من السجلّ.

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

deleteRange()

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

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

المَعلمات

  • النطاق

    كائن

    • endTime

      الرقم

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

    • startTime

      الرقم

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

deleteUrl()

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

يؤدي هذا الإجراء إلى إزالة جميع مواضع ورود عنوان URL المحدَّد من السجلّ.

المَعلمات

  • التفاصيل

    UrlDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

getVisits()

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

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

المَعلمات

  • التفاصيل

    UrlDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (results: VisitItem[])=>void

المرتجعات

  • Promise<VisitItem[]>

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

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

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

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

المَعلمات

  • query

    كائن

    • endTime

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

      قصر النتائج على تلك التي تمت زيارتها قبل هذا التاريخ، ممثلة بالمللي ثانية منذ تلك الحقبة.

    • maxResults

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

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

    • startTime

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

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

    • text

      سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (results: HistoryItem[])=>void

المرتجعات

  • Promise<HistoryItem[]>

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

    تتوفّر الوعود في إصدار 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

        boolean

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

      • urls

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