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