chrome.history

الوصف

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

الأذونات

history

يؤدي هذا الإذن إلى ظهور تحذير.

البيان

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

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

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

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

يوضّح الجدول التالي كل نوع من أنواع عمليات الانتقال.

نوع الانتقال	الوصف
"الرابط"	وصل المستخدِم إلى هذه الصفحة بالنقر على رابط في صفحة أخرى.
"تمت الكتابة"	حصل المستخدم على هذه الصفحة عن طريق كتابة عنوان URL في شريط العناوين. ويُستخدم أيضًا في إجراءات التنقل الصريحة الأخرى. يمكنك الاطّلاع أيضًا على القيمة التي تم إنشاؤها والتي تُستخدم للحالات التي اختار فيها المستخدم خيارًا لا يشبه عنوان URL على الإطلاق.
"auto_bookmark"	وصل المستخدِم إلى هذه الصفحة من خلال اقتراح في واجهة المستخدم، من خلال عنصر في القائمة مثلاً.
"auto_subframe"	التنقل في الإطار الفرعي وهذا هو أي محتوى يتم تحميله تلقائيًا في إطار ليس عالي المستوى. على سبيل المثال، إذا كانت الصفحة تحتوي على عدة إطارات تحتوي على إعلانات، تكون عناوين URL الخاصة بهذه الإعلانات من نوع الانتقال هذا. قد لا يدرك المستخدم أن المحتوى في هذه الصفحات هو إطار منفصل، وبالتالي قد لا يهتم بعنوان URL (يمكنك أيضًا الاطّلاع على manual_subframe).
"manual_subframe"	بالنسبة إلى عمليات التنقّل في الإطار الفرعي التي يطلبها المستخدم صراحةً وإنشاء إدخالات تنقُّل جديدة في قائمة "التخزين المؤقت للصفحات". قد يكون الإطار المطلوب صراحةً أكثر أهمية من الإطار الذي يتم تحميله تلقائيًا، لأنّ المستخدم على الأرجح يهتم بحقيقة تحميل الإطار المطلوب.
"تم الإنشاء"	وصل المستخدم إلى هذه الصفحة عن طريق الكتابة في شريط العناوين واختيار إدخال لا يشبه عنوان URL. على سبيل المثال، قد تشتمل المطابقة على عنوان URL لصفحة نتائج بحث على Google، ولكنّها قد تظهر للمستخدم على النحو التالي: "البحث في Google عن ...". وتتطابق هذه النتائج تمامًا مع عناوين URL التي تم كتابتها لأنّ المستخدم لم يكتب عنوان URL المقصود أو لم يرَه. راجِع أيضًا الكلمة الرئيسية.
"auto_toplevel"	تم تحديد الصفحة في سطر الأوامر أو صفحة البداية.
"form_submit"	ملأ المستخدم القيم في نموذج وأرسله. تجدر الإشارة إلى أنّه في بعض الحالات، مثل استخدام نص برمجي لإرسال المحتوى في نموذج، لا يؤدي إرسال نموذج إلى استخدام هذا النوع من الانتقالات.
"إعادة تحميل"	أعاد المستخدم تحميل الصفحة إما بالنقر على زر إعادة التحميل أو بالضغط على Enter في شريط العناوين. تستخدم علامة التبويب "استعادة الجلسة" و"إعادة فتح الإغلاق" نوع النقل هذا أيضًا.
"الكلمة الرئيسية"	تم إنشاء عنوان URL من كلمة رئيسية قابلة للاستبدال غير مُوفِّر خدمة البحث التلقائي. راجِع أيضًا keyword_generated.
"keyword_generated"	تناظر زيارة تم إنشاؤها لإحدى الكلمات الرئيسية. راجِع أيضًا الكلمة الرئيسية.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال واجهة برمجة التطبيقات للسجلّ من مستودع 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 والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

deleteAll()

وعد

chrome.history.deleteAll(
  callback?: function,
)

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

المَعلمات

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

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

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

  ()=>void

المرتجعات

• Promise<void>

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

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

deleteRange()

وعد

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

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

المَعلمات

• النطاق

  كائن

  • endTime

    الرقم

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

  • startTime

    الرقم

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

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

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

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

  ()=>void

المرتجعات

• Promise<void>

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

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

deleteUrl()

وعد

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

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

المَعلمات

• التفاصيل

  UrlDetails

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

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

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

  ()=>void

المرتجعات

• Promise<void>

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

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

getVisits()

وعد

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

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

المَعلمات

• التفاصيل

  UrlDetails

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

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

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

  (results: VisitItem[])=>void

  • النتائج

    VisitItem[]

المرتجعات

• Promise<VisitItem[]>

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

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

search()

وعد

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

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

المَعلمات

• query

  كائن

  • endTime

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

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

  • maxResults

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

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

  • startTime

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

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

  • text

    سلسلة

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

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

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

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

  (results: HistoryItem[])=>void

  • النتائج

    HistoryItem[]

المرتجعات

• Promise<HistoryItem[]>

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

  لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

فعاليات

onVisited

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

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

المَعلمات

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

  الوظيفة

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

  (result: HistoryItem)=>void

  • نتيجة

    HistoryItem

onVisitRemoved

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

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

المَعلمات

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

  الوظيفة

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

  (removed: object)=>void

  • مزال

    كائن

    • allHistory

      boolean

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

    • urls

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