الوصف
استخدام واجهة برمجة التطبيقات 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
الرقم اختياري
عدد المرّات التي انتقل فيها المستخدِم إلى هذه الصفحة.
التعداد
"رابط"
وصل المستخدم إلى هذه الصفحة من خلال النقر على رابط في صفحة أخرى.
"typed"
وصل المستخدم إلى هذه الصفحة عن طريق كتابة عنوان URL في شريط العناوين. يُستخدم هذا أيضًا في إجراءات التنقل الصريحة الأخرى.
"auto_bookmark"
وصل المستخدم إلى هذه الصفحة من خلال اقتراح في واجهة المستخدم، من خلال عنصر في القائمة مثلاً.
"auto_subframe"
وصل المستخدم إلى هذه الصفحة من خلال التنقّل في الإطار الفرعي ولم يطلبه، مثلاً من خلال تحميل إعلان في إطار ضمن الصفحة السابقة. لا تؤدي هذه دائمًا إلى إنشاء إدخالات تنقُّل جديدة في القائمتين الأمامية والخلفية.
"manual_subframe"
وصل المستخدم إلى هذه الصفحة من خلال اختيار عنصر في إطار فرعي.
"generate"
وصل المستخدم إلى هذه الصفحة عن طريق الكتابة في شريط العناوين واختيار إدخال لا يشبه عنوان URL، مثل أحد اقتراحات "بحث Google". على سبيل المثال، قد تتضمّن المطابقة عنوان URL لصفحة نتائج في "بحث Google"، ولكنّها قد تظهر للمستخدم بعبارة "البحث في Google عن ...". وتختلف هذه الخيارات عن عناوين التنقّل المكتوبة لأنّ المستخدم لم يكتب عنوان URL المقصود أو لم يرَه. وترتبط أيضًا بعمليات التنقّل باستخدام الكلمات الرئيسية.
"auto_toplevel"
تم تحديد الصفحة في سطر الأوامر أو هي الصفحة الرئيسية.
"form_submit"
وصل المستخدِم إلى هذه الصفحة من خلال ملء القيم في نموذج وإرسال النموذج. لا تستخدم بعض عمليات إرسال النماذج هذا النوع من النقل.
"إعادة التحميل"
أعاد المستخدم تحميل الصفحة إما من خلال النقر على زر إعادة التحميل أو بالضغط على Enter في شريط العناوين. تستخدم أيضًا علامة التبويب "استعادة الجلسة" و"إعادة فتح الإغلاق" نوع الانتقال هذا.
"الكلمة الرئيسية"
تم إنشاء عنوان URL لهذه الصفحة من كلمة رئيسية قابلة للاستبدال غير مزوّد البحث التلقائي.
"keyword_generated"
مقابل زيارة تم إنشاؤها لإحدى الكلمات الرئيسية
UrlDetails
أماكن إقامة
-
url
سلسلة
عنوان URL للعملية. ويجب أن تكون بالتنسيق الذي يظهر به الرقم التسلسلي من مكالمة إلى
history.search()
.
VisitItem
عنصر يضم زيارة واحدة إلى عنوان URL
أماكن إقامة
-
id
سلسلة
المعرّف الفريد لسمة
history.HistoryItem
المقابلة. -
isLocal
boolean
Chrome 115 والإصدارات الأحدثصحيح إذا نشأت الزيارة على هذا الجهاز. خطأ في حال مزامنتها من جهاز آخر
-
referringVisitId
سلسلة
رقم تعريف الزيارة للمُحيل.
-
انتقال
نوع الانتقال لهذه الزيارة من المُحيل الخاص بها.
-
visitId
سلسلة
المعرّف الفريد لهذه الزيارة.
-
visitTime
الرقم اختياري
وقت حدوث هذه الزيارة، ويتم تمثيله بالمللي ثانية منذ تاريخ بدء حساب الفترة
الطُرق
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
يضيف عنوان URL إلى السجلّ في الوقت الحالي باستخدام نوع نقل من نوع "الرابط".
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
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 المحدَّد من السجلّ.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
يسترد معلومات حول الزيارات إلى عنوان URL.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(results: VisitItem[]) => void
-
النتائج
-
المرتجعات
-
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
-
النتائج
-
المرتجعات
-
Promise<HistoryItem[]>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من 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
سلسلة[] اختيارية
-
-