chrome.history

תיאור

צריך להשתמש ב-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

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

    מספר הפעמים שהמשתמש ניווט לדף הזה.

TransitionType

Chrome 44 ואילך

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

טיפוסים בני מנייה (enum)

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

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

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

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

"Manual_subframe"
המשתמש הגיע לדף הזה על ידי בחירה בפריט מתוך תת-מסגרת.

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

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

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

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

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

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

UrlDetails

Chrome 88 ומעלה

תכונות

  • כתובת אתר

    מחרוזת

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

VisitItem

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

תכונות

  • id

    מחרוזת

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

  • isLocal

    boolean

    Chrome 115 ומעלה

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

  • referringVisitId

    מחרוזת

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

  • מעבר

    TransitionType

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

  • visitId

    מחרוזת

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

  • visitTime

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

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

שיטות

addUrl()

הבטחה 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    UrlDetails

  • קריאה חוזרת (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 הנתונה יוסרו מההיסטוריה.

פרמטרים

  • פרטים

    UrlDetails

  • קריאה חוזרת (callback)

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

getVisits()

הבטחה 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    UrlDetails

  • קריאה חוזרת (callback)

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

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

    (results: VisitItem[])=>void

החזרות

  • Promise<VisitItem[]>

    Chrome 96 ומעלה

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

הבטחה 
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[] אופציונלי