chrome.history

תיאור

אפשר להשתמש ב-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

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

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

TransitionType

Chrome 44 ואילך

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

Enum

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

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

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

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

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

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

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

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

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

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

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

UrlDetails

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

מאפיינים

  • כתובת אתר

    מחרוזת

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

VisitItem

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • isLocal

    בוליאני

    Chrome 115+

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

  • referringVisitId

    מחרוזת

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

  • מעבר

    TransitionType

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

  • visitId

    מחרוזת

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

  • visitTime

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

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

שיטות

addUrl()

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

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

פרמטרים

  • פרטים

    UrlDetails

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

פרמטרים

  • פרטים

    UrlDetails

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

getVisits()

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

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

פרמטרים

  • פרטים

    UrlDetails

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

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

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

    (results: VisitItem[]) => void

החזרות

  • Promise&lt;VisitItem[]&gt;

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

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

הבטחה 
chrome.history.search(
  query: object,
  callback?: function,
)

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

פרמטרים

  • שאילתה

    אובייקט

    • endTime

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

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

    • maxResults

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

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

    • startTime

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

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

    • טקסט

      מחרוזת

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

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

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

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

    (results: HistoryItem[]) => void

החזרות

  • Promise&lt;HistoryItem[]&gt;

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