תאריך הרענון: 2026-09-25 robots: noindex
תיאור
משתמשים ב-chrome.history API כדי ליצור אינטראקציה עם הרשומה של הדפדפן לגבי דפים שבוקרו. אתם יכולים להוסיף כתובות URL להיסטוריה של הדפדפן, להסיר אותן ממנה ולחפש אותן בה. כדי להחליף את דף ההיסטוריה בגרסה משלכם, אפשר לעיין במאמר בנושא החלפת דפים.
הרשאות
historyמניפסט
כדי להשתמש ב-History API, צריך להצהיר על ההרשאה 'היסטוריה' במניפסט של התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
סוגי מעברים
ה-History API משתמש בסוג מעבר כדי לתאר איך הדפדפן ניווט לכתובת URL מסוימת בביקור מסוים. לדוגמה, אם משתמש נכנס לדף מסוים על ידי לחיצה על קישור בדף אחר, סוג המעבר הוא link.
בטבלה הבאה מתואר כל סוג מעבר.
| סוג המעבר | תיאור |
|---|---|
| "link" | המשתמש הגיע לדף הזה אחרי שלחץ על קישור בדף אחר. |
| "typed" | המשתמש הגיע לדף הזה על ידי הקלדת כתובת ה-URL בסרגל הכתובות. משמש גם לפעולות ניווט מפורשות אחרות. אפשר לעיין גם בערך generated, שמשמש למקרים שבהם המשתמש בחר באפשרות שלא נראית כמו כתובת URL. |
| "auto_bookmark" | המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש – לדוגמה, דרך פריט בתפריט. |
| "auto_subframe" | ניווט ב-iframe. כל תוכן שנטען באופן אוטומטי במסגרת שאינה ברמה העליונה. לדוגמה, אם דף מורכב מכמה מסגרות שמכילות מודעות, כתובות ה-URL של המודעות האלה הן מסוג המעבר הזה. יכול להיות שהמשתמש לא יבין שהתוכן בדפים האלה הוא פריים נפרד, ולכן לא יתעניין בכתובת ה-URL (ראו גם manual_subframe). |
| "manual_subframe" | לניווטים ב-iframe שהמשתמש מבקש באופן מפורש ויוצרים רשומות ניווט חדשות ברשימת החזרה/התקדמות. סביר להניח שפריים שנשלח לגביו בקשה מפורשת חשוב יותר מפריים שנשלח באופן אוטומטי, כי כנראה שהמשתמשים רוצים לדעת שהפריים המבוקש נטען. |
| "generated" | המשתמש הגיע לדף הזה על ידי הקלדה בסרגל הכתובות ובחירה בערך שלא נראה כמו כתובת URL. לדוגמה, יכול להיות שכתובת ה-URL של התאמה תהיה כתובת של דף תוצאות חיפוש ב-Google, אבל יכול להיות שהיא תופיע למשתמש כ'חיפוש ב-Google של…'. אלה לא בדיוק ניווטים שהוקלדו כי המשתמש לא הקליד את כתובת היעד ולא ראה אותה. מידע נוסף מופיע במאמר בנושא מילות מפתח. |
| "auto_toplevel" | הדף צוין בשורת הפקודה או שהוא דף הפתיחה. |
| "form_submit" | המשתמש מילא ערכים בטופס ושלח אותו. הערה: במצבים מסוימים – למשל, כשמשתמשים בסקריפט כדי לשלוח את התוכן של טופס – שליחת טופס לא מובילה למעבר מהסוג הזה. |
| "reload" | המשתמש טען מחדש את הדף, בלחיצה על לחצן הטעינה מחדש או בהקשה על Enter בסרגל הכתובות. גם שחזור סשן ופתיחה מחדש של כרטיסייה שנסגרה משתמשים בסוג המעבר הזה. |
| "מילת מפתח" | כתובת ה-URL נוצרה ממילת מפתח להחלפה שאינה ספק החיפוש שמוגדר כברירת מחדל. מידע נוסף מופיע במאמר בנושא keyword_generated. |
| "keyword_generated" | הערך הזה מתאים לביקור שנוצר עבור מילת מפתח. מידע נוסף מופיע במאמר בנושא מילות מפתח. |
דוגמאות
כדי לנסות את ממשק ה-API הזה, מתקינים את הדוגמה של history API ממאגר chrome-extension-samples.
סוגים
HistoryItem
אובייקט שמכיל תוצאה אחת של שאילתת היסטוריה.
מאפיינים
-
id [מזהה]
מחרוזת
המזהה הייחודי של הפריט.
-
lastVisitTime
מספר אופציונלי
המועד האחרון שבו הדף הזה נטען, באלפיות שנייה מאז ראשית זמן יוניקס (Unix epoch).
-
title
מחרוזת אופציונלי
הכותרת של הדף כשהוא נטען לאחרונה.
-
typedCount
מספר אופציונלי
מספר הפעמים שבהן המשתמש עבר לדף הזה על ידי הקלדת הכתובת.
-
url
מחרוזת אופציונלי
כתובת ה-URL שאליה המשתמש עבר.
-
visitCount
מספר אופציונלי
מספר הפעמים שבהן המשתמש עבר לדף הזה.
ספירה
link
המשתמש הגיע לדף הזה בלחיצה על קישור בדף אחר.
הקלדה
המשתמש הגיע לדף הזה על ידי הקלדת כתובת ה-URL בסרגל הכתובות. הוא משמש גם לפעולות ניווט מפורשות אחרות.
auto_bookmark
המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש, למשל דרך פריט בתפריט.
auto_subframe
המשתמש הגיע לדף הזה דרך ניווט ב-subframe שהוא לא ביקש, למשל דרך טעינת מודעה ב-frame בדף הקודם. הפעולות האלה לא תמיד יוצרות רשומות חדשות בניווט בתפריטים 'הקודם' ו'הבא'.
manual_subframe
המשתמש הגיע לדף הזה אחרי שבחר משהו במסגרת משנה.
'נוצר'
המשתמש הגיע לדף הזה אחרי שהקליד ב<b>סרגל הכתובות</b> ובחר ערך שלא נראה כמו <b>כתובת URL</b>, למשל <b>הצעה לחיפוש</b> ב-<b>חיפוש Google</b>. לדוגמה, יכול להיות שכתובת ה-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 ואילךהערך הוא True אם הביקור התחיל במכשיר הזה. הערך הוא False אם הוא סונכרן ממכשיר אחר.
-
referringVisitId
מחרוזת
מזהה הביקור של מקור ההפניה.
-
מעבר
סוג המעבר של הביקור הזה מהמפנה.
-
visitId
מחרוזת
המזהה הייחודי של הביקור הזה.
-
visitTime
מספר אופציונלי
הזמן שבו הביקור הזה התרחש, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
Methods
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
מוסיף כתובת URL להיסטוריה בזמן הנוכחי עם סוג מעבר של 'קישור'.
פרמטרים
-
פרטים
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:() =& gt;void
החזרות
-
Promise<void>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
deleteAll()
chrome.history.deleteAll(
callback?: function,
): Promise<void>
מחיקת כל הפריטים מההיסטוריה.
פרמטרים
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:() =& gt;void
החזרות
-
Promise<void>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
): Promise<void>
הסרת כל הפריטים בטווח התאריכים שצוין מההיסטוריה. דפים לא יוסרו מההיסטוריה אלא אם כל הביקורים יהיו בטווח.
פרמטרים
-
טווח
אובייקט
-
endTime
number
פריטים שנוספו להיסטוריה לפני התאריך הזה, במילישניות מאז ראשית הזמן.
-
startTime
number
פריטים שנוספו להיסטוריה אחרי התאריך הזה, בייצוג של אלפיות שנייה מאז ראשית הזמן.
-
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:() =& gt;void
החזרות
-
Promise<void>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
הסרת כל המופעים של כתובת ה-URL שצוינה מההיסטוריה.
פרמטרים
-
פרטים
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:() =& gt;void
החזרות
-
Promise<void>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
): Promise<VisitItem[]>
אחזור מידע על ביקורים בכתובת URL.
פרמטרים
-
פרטים
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:(results: VisitItem[]) =& gt;void
-
תוצאות
-
החזרות
-
Promise<VisitItem[]>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
search()
chrome.history.search(
query: object,
callback?: function,
): Promise<HistoryItem[]>
הפונקציה מחפשת בהיסטוריה את זמן הביקור האחרון בכל דף שתואם לשאילתה.
פרמטרים
-
שאילתה
אובייקט
-
endTime
מספר אופציונלי
הגבלת התוצאות לאלה שהיו בהן ביקורים לפני התאריך הזה, שמיוצג באלפיות שנייה מאז ראשית הזמן.
-
maxResults
מספר אופציונלי
המספר המקסימלי של התוצאות לאחזור. ברירת המחדל היא 100.
-
startTime
מספר אופציונלי
הגבלת התוצאות לביקורים שהתבצעו אחרי התאריך הזה, שמוצג באלפיות שנייה מאז ראשית זמן יוניקס (Unix epoch). אם לא מציינים את המאפיין, ברירת המחדל היא 24 שעות.
-
text
מחרוזת
שאילתה של טקסט חופשי לשירות ההיסטוריה. כדי לאחזר את כל הדפים, משאירים את השדה הזה ריק.
-
-
callback
פונקציה אופציונלית
הפרמטר
callbackנראה כך:(results: HistoryItem[]) =& gt;void
-
תוצאות
-
החזרות
-
Promise<HistoryItem[]>
Chrome 96 ואילךהתמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
אירועים
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
האירוע מופעל כשמבקרים בכתובת URL, ומספק את HistoryItem הנתונים של כתובת ה-URL הזו. האירוע הזה מופעל לפני שהדף נטען.
פרמטרים
-
callback
פונקציה
הפרמטר
callbackנראה כך:(result: HistoryItem) =& gt;void
-
תוצאה
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
האירוע מופעל כשמסירים כתובת URL אחת או יותר מההיסטוריה. אחרי שמסירים את כל הביקורים, כתובת ה-URL נמחקת מההיסטוריה.
פרמטרים
-
callback
פונקציה
הפרמטר
callbackנראה כך:(removed: object) =& gt;void
-
הוסר
אובייקט
-
allHistory
בוליאני
הערך הוא True אם כל ההיסטוריה הוסרה. אם הערך הוא True, כתובות ה-URL יהיו ריקות.
-
כתובות אתרים
string[] אופציונלי
-
-