الوصف
استخدام واجهة برمجة التطبيقات 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
الرقم اختياري
عدد المرّات التي انتقل فيها المستخدِم إلى هذه الصفحة.
التعداد
"رابط"
وصل المستخدم إلى هذه الصفحة من خلال النقر على رابط في صفحة أخرى.
"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 والإصدارات الأحدثتتوفّر الوعود في إصدار 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 المحدَّد من السجلّ.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
يسترد معلومات حول الزيارات إلى عنوان URL.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(results: VisitItem[]) => void
-
النتائج
-
المرتجعات
-
Promise<VisitItem[]>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار 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 والإصدارات الأحدثتتوفّر الوعود في إصدار 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
سلسلة[] اختيارية
-
-