chrome.history

refresh date: 2026-09-25 robots: noindex

תיאור

משתמשים ב-API של chrome.history כדי לבצע פעולות ברשומת הדפים שהמשתמשים ביקרו בהם בדפדפן. אתם יכולים להוסיף, להסיר ולשאול לגבי כתובות URL בהיסטוריה של הדפדפן. כדי לשנות את דף ההיסטוריה לגרסה משלכם, עיינו במאמר שינוי דפים.

הרשאות

history

ההרשאה הזו מפעילה אזהרה.

מניפסט

כדי להשתמש ב-History API, צריך להצהיר על ההרשאה "history" במניפסט של התוסף. לדוגמה:

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

סוגי המעברים

ה-API של ההיסטוריה משתמש בסוג הפניה כדי לתאר איך הדפדפן עבר לכתובת URL מסוימת בביקור מסוים. לדוגמה, אם משתמש נכנס לדף על ידי לחיצה על קישור בדף אחר, סוג המעבר הוא "קישור".

בטבלה הבאה מתוארים סוגי ההפניות השונים.

סוג ההפניה	תיאור
"link"	המשתמש הגיע לדף הזה בלחיצה על קישור בדף אחר.
"typed"	המשתמש הגיע לדף הזה על ידי הקלדת כתובת ה-URL בסרגל הכתובות. משמש גם לפעולות ניווט מפורשות אחרות. אפשר גם לעיין בערך generated, שמשמש במקרים שבהם המשתמש בחר אפשרות שלא נראתה בכלל כמו כתובת URL.
"auto_bookmark"	המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש, למשל דרך פריט בתפריט.
"auto_subframe"	ניווט במסגרת משנה. זהו כל תוכן שנטען באופן אוטומטי במסגרת שאינה ברמה העליונה. לדוגמה, אם דף מורכב מכמה מסגרות שמכילות מודעות, לכתובות ה-URL של המודעות האלה יש את סוג ההפניה הזה. יכול להיות שהמשתמש אפילו לא יבין שהתוכן בדפים האלה הוא מסגרת נפרדת, ולכן לא יהיה אכפת לו מכתובת ה-URL (ראו גם manual_subframe).
"manual_subframe"	לניווטים במסגרות משנה שהמשתמש ביקש במפורש, ויוצרים רשומות ניווט חדשות ברשימת הניווט קדימה/אחורה. פריים שנטען בעקבות בקשה מפורשת כנראה חשוב יותר מפריים שנטען באופן אוטומטי, כי למשתמש כנראה אכפת מכך שהפריים שביקש נטען.
"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

  מספר אופציונלי

  מספר הפעמים שהמשתמש עבר לדף הזה.

TransitionType

‫Chrome מגרסה 44 ואילך

סוג המעבר לביקור הזה מהמפנה שלו.

טיפוסים בני מנייה (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

‫Chrome מגרסה 88 ואילך

מאפיינים

• url

  מחרוזת

  כתובת ה-URL של הפעולה. הוא צריך להיות בפורמט שמוחזר מקריאה ל-history.search().

VisitItem

אובייקט שמכיל ביקור אחד בכתובת URL.

מאפיינים

• id [מזהה]

  מחרוזת

  המזהה הייחודי של history.HistoryItem התואם.

• isLocal

  בוליאני

  ‫Chrome מגרסה 115 ואילך

  True אם הביקור התחיל במכשיר הזה. הערך False אם הוא סונכרן ממכשיר אחר.

• referringVisitId

  מחרוזת

  מזהה הביקור של מקור ההפניה (referrer).

• מעבר בין סצנות

  TransitionType

  סוג המעבר לביקור הזה מהמפנה שלו.

• visitId

  מחרוזת

  המזהה הייחודי של הביקור הזה.

• visitTime

  מספר אופציונלי

  מתי הביקור התרחש, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).

Methods

addUrl()

Promise

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

הוספת כתובת URL להיסטוריה בזמן הנוכחי עם סוג מעבר של "קישור".

פרמטרים

• פרטים

  UrlDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

deleteAll()

Promise

chrome.history.deleteAll(
  callback?: function,
): Promise<void>

מחיקת כל הפריטים מההיסטוריה.

פרמטרים

• callback

  function optional

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

deleteRange()

Promise

chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

הסרת כל הפריטים בטווח התאריכים שצוין מההיסטוריה. הדפים לא יוסרו מההיסטוריה, אלא אם כל הביקורים בהם היו בטווח הזמן שנבחר.

פרמטרים

• טווח

  אובייקט

  • endTime

    number

    פריטים שנוספו להיסטוריה לפני התאריך הזה, מיוצגים באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).

  • startTime

    number

    פריטים שנוספו להיסטוריה אחרי התאריך הזה, מיוצגים באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).

• callback

  function optional

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

deleteUrl()

Promise

chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

הסרה של כל המופעים של כתובת ה-URL הנתונה מההיסטוריה.

פרמטרים

• פרטים

  UrlDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getVisits()

Promise

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

אחזור מידע על ביקורים בכתובת URL.

פרמטרים

• פרטים

  UrlDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  (results: VisitItem[]) => void

  • תוצאות

    VisitItem[]‎

החזרות

• Promise<VisitItem[]>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

search()

Promise

chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

חיפוש בהיסטוריה של מועד הביקור האחרון בכל דף שתואם לשאילתה.

פרמטרים

• שאילתה

  אובייקט

  • endTime

    מספר אופציונלי

    הגבלת התוצאות לאלה שביקרו לפני התאריך הזה, מיוצג באלפיות השנייה מאז תחילת התקופה.

  • maxResults

    מספר אופציונלי

    המספר המקסימלי של תוצאות שאפשר לאחזר. ברירת המחדל היא 100.

  • startTime

    מספר אופציונלי

    הגבלת התוצאות לאלה שביקרו אחרי התאריך הזה, מיוצג באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch). אם לא מציינים את המאפיין, ברירת המחדל היא 24 שעות.

  • text

    מחרוזת

    שאילתה בטקסט חופשי לשירות ההיסטוריה. כדי לאחזר את כל הדפים, צריך להשאיר את השדה הזה ריק.

• callback

  function optional

  הפרמטר callback נראה כך:

  (results: HistoryItem[]) => void

  • תוצאות

    HistoryItem[]

החזרות

• Promise<HistoryItem[]>

  ‫Chrome מגרסה 96 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

מופעל כשמשתמש נכנס לכתובת URL, ומספק את נתוני ה-HistoryItem של כתובת ה-URL הזו. האירוע הזה מופעל לפני שהדף נטען.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (result: HistoryItem) => void

  • תוצאה

    HistoryItem

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

מופעל כשכתובת URL אחת או יותר מוסרות מההיסטוריה. אחרי שכל הביקורים הוסרו, כתובת ה-URL נמחקת מההיסטוריה.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (removed: object) => void

  • הוסר

    אובייקט

    • allHistory

      בוליאני

      הערך True אם כל ההיסטוריה הוסרה. אם הערך הוא True, כתובות ה-URL יהיו ריקות.

    • כתובות אתרים

      string[] אופציונלי