תיאור
צריך להשתמש ב-API chrome.history
כדי לבצע פעולות ברשומת הדפדפן לגבי הדפים שבהם ביקרת. אתם יכולים להוסיף כתובות URL להיסטוריית הדפדפן, להסיר אותן ולשלוח שאילתות לגבין. כדי לשנות את דף ההיסטוריה לגרסה משלכם, אפשר לעיין במאמר שינוי דפים.
הרשאות
history
כדי לקיים אינטראקציה עם היסטוריית הדפדפן של המשתמש, יש להשתמש ב-History API.
כדי להשתמש ב-History API, מצהירים על ההרשאה "history"
במניפסט התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
מושגים ושימוש
סוגי מעברים
ממשק ה-API של ההיסטוריה משתמש בסוגי מעבר כדי לתאר את האופן שבו הדפדפן עבר לכתובת URL מסוימת בביקור מסוים. לדוגמה, במקרה שמשתמש מבקר בדף על ידי לחיצה על קישור בדף אחר, סוג ההעברה הוא 'קישור'. בתוכן העזר מופיעה רשימה של סוגי המעברים.
דוגמאות
כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה של History API מהמאגר chrome-extension-samples.
סוגים
HistoryItem
אובייקט שמקיף תוצאה אחת של שאילתת היסטוריה.
תכונות
-
id
מחרוזת
המזהה הייחודי של הפריט.
-
lastVisitTime
מספר אופציונלי
כאשר הדף הזה נטען לאחרונה, מיוצג באלפיות שנייה מאז תחילת התהליך.
-
title
מחרוזת אופציונלי
כותרת הדף בפעם האחרונה שהוא נטען.
-
typedCount
מספר אופציונלי
מספר הפעמים שהמשתמש ניווט לדף זה על ידי הקלדת כתובת.
-
כתובת אתר
מחרוזת אופציונלי
כתובת ה-URL שאליה המשתמש עבר.
-
visitCount
מספר אופציונלי
מספר הפעמים שהמשתמש ניווט לדף הזה.
טיפוסים בני מנייה (enum)
"קישור"
המשתמש הגיע לדף הזה בלחיצה על קישור בדף אחר.
"הוקלד"
המשתמש הגיע לדף הזה באמצעות הקלדת כתובת ה-URL בסרגל הכתובות. הפעולה הזו משמשת גם לפעולות ניווט מפורשות אחרות.
"auto_bookmark"
המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש, למשל דרך פריט בתפריט.
"auto_subframe"
המשתמש הגיע לדף הזה דרך ניווט במסגרת תת-מסגרת שהוא לא ביקש, למשל דרך טעינת מודעה במסגרת מסגרת בדף הקודם. הן לא תמיד יוצרות רשומות ניווט חדשות בתפריטים 'הקודם' ו'הבא'.
"Manual_subframe"
המשתמש הגיע לדף הזה על ידי בחירה בפריט מתוך תת-מסגרת.
"נוצר"
המשתמש הגיע לדף הזה על ידי הקלדת טקסט בסרגל הכתובות ובחירת ערך שלא נראה כמו כתובת אתר, למשל הצעה של חיפוש Google. לדוגמה, להתאמה עשויה להיות כתובת URL של דף תוצאות חיפוש ב-Google, אבל היא עשויה להופיע בפני המשתמש כ-"חיפוש ב-Google של ...". אלה שונים מניווטים שהוקלדו כי המשתמש לא הקליד או לא ראה את כתובת היעד. הן קשורות גם לניווטים באמצעות מילות מפתח.
"auto_toplevel"
הדף צוין בשורת הפקודה או שהוא דף הפתיחה.
"form_submit"
המשתמש הגיע לדף הזה על ידי מילוי ערכים בטופס ושליחה של הטופס. לא כל שליחת טפסים מתבצעת בסוג המעבר הזה.
"טעינה מחדש"
המשתמש טען מחדש את הדף על ידי לחיצה על לחצן הטעינה מחדש או על ידי הקשה על Enter בסרגל הכתובות. גם בשחזור הסשן ובפתיחה מחדש של כרטיסייה שנסגרה צריך להשתמש בסוג המעבר הזה.
"מילת מפתח"
כתובת ה-URL של הדף הזה נוצרה ממילת מפתח שניתנת להחלפה שאינה ספק החיפוש שמוגדר כברירת מחדל.
"keyword_generated"
תואם לביקור שנוצר עבור מילת מפתח.
UrlDetails
תכונות
-
כתובת אתר
מחרוזת
כתובת ה-URL של הפעולה. היא צריכה להיות בפורמט שהוחזר מקריאה ל-
history.search()
.
VisitItem
אובייקט שכולל סיכום ביקור אחד בכתובת URL.
תכונות
-
id
מחרוזת
המזהה הייחודי של
history.HistoryItem
המתאים. -
isLocal
boolean
Chrome 115 ומעלהTrue אם הביקור בוצע במכשיר הזה. False אם הוא סונכרן ממכשיר אחר.
-
referringVisitId
מחרוזת
מזהה הביקור של הגורם המפנה.
-
מעבר
סוג ההעברה של הביקור הזה מהגורם המפנה שלו.
-
visitId
מחרוזת
המזהה הייחודי של הביקור הזה.
-
visitTime
מספר אופציונלי
כאשר ביקור זה התרחש, הוא מיוצג באלפיות שנייה מאז תחילת התקופה.
שיטות
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
מוסיף כתובת URL להיסטוריה ברגע הנוכחי עם סוג העברה של 'קישור'.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
deleteAll()
chrome.history.deleteAll(
callback?: function,
)
מחיקת כל הפריטים מההיסטוריה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
)
הסרת כל הפריטים בטווח התאריכים שצוין מההיסטוריה. דפים לא יוסרו מההיסטוריה, אלא אם כל הביקורים נמצאים בטווח.
פרמטרים
-
טווח
אובייקט
-
endTime
מספר
פריטים שנוספו להיסטוריה לפני תאריך זה, מיוצגים באלפיות שנייה מאז תחילת התקופה.
-
startTime
מספר
פריטים שנוספו להיסטוריה לאחר תאריך זה, מיוצגים באלפיות שנייה מאז תחילת התקופה.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
כל המופעים של כתובת ה-URL הנתונה יוסרו מההיסטוריה.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
אחזור מידע על ביקורים בכתובת URL.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(results: VisitItem[]) => void
-
תוצאות
-
החזרות
-
Promise<VisitItem[]>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
search()
chrome.history.search(
query: object,
callback?: function,
)
מחפש בהיסטוריה את מועד הביקור האחרון של כל דף שתואם לשאילתה.
פרמטרים
-
שאילתה
אובייקט
-
endTime
מספר אופציונלי
הגבלת התוצאות לאלו שביקרו בהם לפני התאריך הזה, מיוצגים באלפיות השנייה מאז תחילת התקופה של זמן מערכת.
-
maxResults
מספר אופציונלי
המספר המקסימלי של תוצאות לאחזור. ברירת המחדל היא 100.
-
startTime
מספר אופציונלי
הגבילו את התוצאות לאלו שביקרו בהם אחרי התאריך הזה, מיוצגים באלפיות השנייה מאז תחילת התקופה של זמן מערכת. אם לא תציינו מאפיין, ברירת המחדל תהיה 24 שעות.
-
טקסט
מחרוזת
שאילתה של טקסט חופשי לשירות ההיסטוריה. אפשר להשאיר את השדה הזה ריק כדי לאחזר את כל הדפים.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(results: HistoryItem[]) => void
-
תוצאות
-
החזרות
-
Promise<HistoryItem[]>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
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
boolean
True אם כל ההיסטוריה הוסרה. אם הערך הוא True, כתובות ה-URL יהיו ריקות.
-
urls
string[] אופציונלי
-
-