chrome.history

תיאור

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

הרשאות

history

מניפסט

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

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

סוגי מעברים

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

בטבלה הבאה מתואר כל סוג מעבר.

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

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

    המועד האחרון שבו הדף הזה נטען, במילי-שניות מאז תקופת ה-Epoch.

  • title

    מחרוזת אופציונלי

    הכותרת של הדף כשהוא נטען לאחרונה.

  • typedCount

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

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

  • כתובת אתר

    מחרוזת אופציונלי

    כתובת ה-URL שאליה המשתמש עבר.

  • visitCount

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

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

TransitionType

‫Chrome 44 ואילך

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

Enum

'קישור'
המשתמש הגיע לדף הזה אחרי שלחץ על קישור בדף אחר.

typed
המשתמש הגיע לדף הזה אחרי שהקליד את כתובת ה-URL בסרגל הכתובות. הוא משמש גם לפעולות ניווט מפורשות אחרות.

‫auto_bookmark
המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש, למשל דרך פריט בתפריט.

‫auto_subframe
המשתמש הגיע לדף הזה דרך ניווט ב-subframe שהוא לא ביקש, למשל דרך טעינת מודעה ב-frame בדף הקודם. הפעולות האלה לא תמיד יוצרות רשומות חדשות בתפריטי הניווט 'הקודם' ו'הבא'.

‫manual_subframe
המשתמש הגיע לדף הזה אחרי שבחר משהו ב-subframe.

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

‫auto_toplevel
הדף צוין בשורת הפקודה או שהוא דף הפתיחה.

‫form_submit
המשתמש הגיע לדף הזה אחרי שמילא ערכים בטופס ושלח אותו. לא כל השליחות של טפסים משתמשות בסוג המעבר הזה.

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

‫'keyword'
כתובת ה-URL של הדף הזה נוצרה ממילת מפתח שניתן להחליף אותה, ולא מספק החיפוש שמוגדר כברירת מחדל.

‫keyword_generated
מתאים לביקור שנוצר עבור מילת מפתח.

UrlDetails

‫Chrome 88 ואילך

מאפיינים

  • כתובת אתר

    מחרוזת

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

VisitItem

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • isLocal

    בוליאני

    ‫Chrome 115 ואילך

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

  • referringVisitId

    מחרוזת

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

  • מעבר

    TransitionType

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

  • visitId

    מחרוזת

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

  • visitTime

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

    הזמן שבו הביקור הזה התרחש, במיליוניות השנייה מאז תחילת התקופה של זמן מערכת.

Methods

addUrl()

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

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

פרמטרים

  • פרטים

    UrlDetails

  • callback

    פונקציה אופציונלית

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

deleteAll()

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

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

פרמטרים

  • callback

    פונקציה אופציונלית

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

deleteRange()

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

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

פרמטרים

  • טווח

    אובייקט

    • endTime

      number

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

    • startTime

      number

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

  • callback

    פונקציה אופציונלית

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

deleteUrl()

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

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

פרמטרים

  • פרטים

    UrlDetails

  • callback

    פונקציה אופציונלית

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getVisits()

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

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

פרמטרים

  • פרטים

    UrlDetails

  • callback

    פונקציה אופציונלית

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

    (results: VisitItem[]) => void

החזרות

  • Promise<VisitItem[]>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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

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

פרמטרים

  • שאילתה

    אובייקט

    • endTime

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

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

    • maxResults

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

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

    • startTime

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

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

    • text

      מחרוזת

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

  • callback

    פונקציה אופציונלית

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

    (results: HistoryItem[]) => void

החזרות

  • Promise<HistoryItem[]>

    ‫Chrome 96 ואילך

    ההבטחות נתמכות רק ב-Manifest 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

        בוליאני

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

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

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