תיאור
משתמשים ב-chrome.history API כדי ליצור אינטראקציה עם רשומת הדפדפן של הדפים שבוקרו. אפשר להוסיף, להסיר ולחפש כתובות URL בהיסטוריה של הדפדפן. כדי להחליף את דף ההיסטוריה בגרסה משלכם, אפשר לעיין במאמר בנושא החלפת דפים.
הרשאות
historyכדי לקיים אינטראקציה עם היסטוריית הגלישה של המשתמש, משתמשים ב-History API.
כדי להשתמש ב-History API, צריך להצהיר על ההרשאה "history" במניפסט התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
מושגים ושימוש
סוגי מעברים
ה-History API משתמש בסוגי מעברים כדי לתאר איך הדפדפן ניווט לכתובת URL מסוימת בביקור מסוים. לדוגמה, אם משתמש נכנס לדף על ידי לחיצה על קישור בדף אחר, סוג המעבר הוא link. במאמר בנושא תוכן של קובצי עזר מופיעה רשימה של סוגי מעברים.
דוגמאות
כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה של History API ממאגר chrome-extension-samples.
סוגים
HistoryItem
אובייקט שמכיל תוצאה אחת של שאילתת היסטוריה.
מאפיינים
-
id [מזהה]
מחרוזת
המזהה הייחודי של הפריט.
-
lastVisitTime
מספר אופציונלי
המועד האחרון שבו הדף הזה נטען, במילי-שניות מאז תקופת ה-Epoch.
-
title
מחרוזת אופציונלי
הכותרת של הדף כשהוא נטען לאחרונה.
-
typedCount
מספר אופציונלי
מספר הפעמים שבהן המשתמש עבר לדף הזה על ידי הקלדת הכתובת.
-
כתובת אתר
מחרוזת אופציונלי
כתובת ה-URL שאליה המשתמש עבר.
-
visitCount
מספר אופציונלי
מספר הפעמים שהמשתמש עבר לדף הזה.
Enum
'קישור'
המשתמש הגיע לדף הזה אחרי שלחץ על קישור בדף אחר.
typed
המשתמש הגיע לדף הזה אחרי שהקליד את כתובת ה-URL בסרגל הכתובות. הוא משמש גם לפעולות ניווט מפורשות אחרות.
auto_bookmark
המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש, למשל דרך פריט בתפריט.
auto_subframe
המשתמש הגיע לדף הזה דרך ניווט ב-subframe שהוא לא ביקש, למשל דרך טעינת מודעה ב-frame בדף הקודם. הפעולות האלה לא תמיד יוצרות רשומות חדשות בתפריטי הניווט 'הקודם' ו'הבא'.
manual_subframe
המשתמש הגיע לדף הזה אחרי שבחר משהו ב-subframe.
'נוצר'
המשתמש הגיע לדף הזה על ידי הקלדה בשורת הכתובת ובחירה בערך שלא נראה כמו כתובת URL, למשל הצעה לחיפוש ב-Google. לדוגמה, יכול להיות שכתובת ה-URL של התאמה תהיה כתובת של דף תוצאות בחיפוש Google, אבל המשתמש יראה את ההתאמה כ'חיפוש Google עבור…'. התאמות כאלה שונות מניווטים שהמשתמש הקליד, כי המשתמש לא הקליד את כתובת היעד ולא ראה אותה. הן קשורות גם לניווט באמצעות מילות מפתח.
auto_toplevel
הדף צוין בשורת הפקודה או שהוא דף הפתיחה.
form_submit
המשתמש הגיע לדף הזה אחרי שמילא ערכים בטופס ושלח אותו. לא כל השליחות של טפסים משתמשות בסוג המעבר הזה.
reload
המשתמש טען מחדש את הדף, בלחיצה על לחצן הטעינה מחדש או בהקשה על Enter בשורת הכתובת. גם שחזור סשן ופתיחה מחדש של כרטיסייה שנסגרה משתמשים בסוג המעבר הזה.
'keyword'
כתובת ה-URL של הדף הזה נוצרה ממילת מפתח שניתן להחליף אותה, ולא מספק החיפוש שמוגדר כברירת מחדל.
keyword_generated
מתאים לביקור שנוצר עבור מילת מפתח.
UrlDetails
מאפיינים
-
כתובת אתר
מחרוזת
כתובת ה-URL של הפעולה. הערך צריך להיות בפורמט שמוחזר מקריאה לפונקציה
history.search().
VisitItem
אובייקט שמכיל ביקור אחד בכתובת URL.
מאפיינים
-
id [מזהה]
מחרוזת
המזהה הייחודי של
history.HistoryItemהתואם. -
isLocal
בוליאני
Chrome 115 ואילךהערך הוא True אם הביקור התחיל במכשיר הזה. הערך הוא False אם הוא סונכרן ממכשיר אחר.
-
referringVisitId
מחרוזת
מזהה הביקור של מקור ההפניה.
-
מעבר
סוג המעבר של הביקור הזה מהמפנה.
-
visitId
מחרוזת
המזהה הייחודי של הביקור הזה.
-
visitTime
מספר אופציונלי
הזמן שבו הביקור הזה התרחש, במיליוניות השנייה מאז תחילת התקופה של זמן מערכת.
Methods
addUrl()
chrome.history.addUrl(
details: UrlDetails,
): Promise<void>
מוסיף כתובת URL להיסטוריה בזמן הנוכחי עם סוג מעבר של 'קישור'.
פרמטרים
-
פרטים
החזרות
-
Promise<void>
Chrome 96 ואילך
deleteAll()
chrome.history.deleteAll(): Promise<void>
מחיקה של כל הפריטים מההיסטוריה.
החזרות
-
Promise<void>
Chrome 96 ואילך
deleteRange()
chrome.history.deleteRange(
range: object,
): Promise<void>
הסרת כל הפריטים בטווח התאריכים שצוין מההיסטוריה. דפים לא יוסרו מההיסטוריה אלא אם כל הביקורים יהיו בטווח.
פרמטרים
-
טווח
אובייקט
-
endTime
number
פריטים שנוספו להיסטוריה לפני התאריך הזה, שמיוצג באלפיות שנייה מאז תקופת האפס.
-
startTime
number
פריטים שנוספו להיסטוריה אחרי התאריך הזה, שמיוצג באלפיות השנייה מאז תקופת האפס.
-
החזרות
-
Promise<void>
Chrome 96 ואילך
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
): Promise<void>
הסרת כל המופעים של כתובת האתר שצוינה מההיסטוריה.
פרמטרים
-
פרטים
החזרות
-
Promise<void>
Chrome 96 ואילך
getVisits()
chrome.history.getVisits(
details: UrlDetails,
): Promise<VisitItem[]>
אחזור מידע על ביקורים בכתובת URL.
פרמטרים
-
פרטים
החזרות
-
Promise<VisitItem[]>
Chrome 96 ואילך
search()
chrome.history.search(
query: object,
): Promise<HistoryItem[]>
החיפוש מתבצע בהיסטוריה כדי למצוא את שעת הביקור האחרונה בכל דף שתואם לשאילתה.
פרמטרים
-
שאילתה
אובייקט
-
endTime
מספר אופציונלי
הגבלת התוצאות לאלה שביקרו לפני התאריך הזה, שמוצג באלפיות שנייה מאז התקופה.
-
maxResults
מספר אופציונלי
המספר המקסימלי של תוצאות לאחזור. ברירת המחדל היא 100.
-
startTime
מספר אופציונלי
הגבלת התוצאות לאלה שבוצעו אחרי התאריך הזה, שמוצג באלפיות השנייה מאז תקופת האפוק. אם לא מציינים את המאפיין, ברירת המחדל היא 24 שעות.
-
text
מחרוזת
שאילתה של טקסט חופשי לשירות ההיסטוריה. כדי לאחזר את כל הדפים, משאירים את השדה הזה ריק.
-
החזרות
-
Promise<HistoryItem[]>
Chrome 96 ואילך
אירועים
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
האירוע מופעל כשמבקרים בכתובת URL, ומספק את HistoryItem הנתונים של כתובת ה-URL הזו. האירוע הזה מופעל לפני שהדף נטען.
פרמטרים
-
callback
פונקציה
הפרמטר
callbackנראה כך:(result: HistoryItem) => void
-
תוצאה
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
האירוע מופעל כשמסירים כתובת URL אחת או יותר מההיסטוריה. אחרי שמסירים את כל הביקורים, כתובת ה-URL נמחקת מההיסטוריה.
פרמטרים
-
callback
פונקציה
הפרמטר
callbackנראה כך:(removed: object) => void
-
הוסר
אובייקט
-
allHistory
בוליאני
הערך הוא True אם כל ההיסטוריה הוסרה. אם הערך הוא True, כתובות ה-URL יהיו ריקות.
-
כתובות אתרים
string[] אופציונלי
-
-