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