chrome.history

תיאור

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

הרשאות

history

מניפסט

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

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

סוגי מעבר

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

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

סוג המעברתיאור
"typed"המשתמש קיבל את הדף לאחר הקלדת כתובת ה-URL בסרגל הכתובות. משמש גם לפעולות ניווט בוטות אחרות. בקטע נוצרה האפשרות הזו משמשת למקרים שבהם המשתמש בחר בחירה שלא נראית בכלל כמו כתובת URL.
'auto_bookmark'המשתמש הגיע לדף הזה דרך הצעה בממשק המשתמש – לדוגמה, דרך אפשרות בתפריט.
'auto_subframe'ניווט בתת-מסגרות. כל תוכן שנטען באופן אוטומטי במסגרת שאינה ברמה העליונה. לדוגמה, אם דף מורכב מכמה מסגרות שמכילות מודעות, סוג המעבר בכתובות ה-URL של המודעות האלה הוא כזה. ייתכן שהמשתמש אפילו לא מבין שהתוכן בדפים האלה הוא מסגרת נפרדת, ולכן כתובת ה-URL לא חשובה לו (ראו גם manual_subframe).
"ידני_subframe"לניווטים בתת-מסגרות שהתבקשו במפורש על ידי המשתמש, ונוצרים רשומות ניווט חדשות ברשימת הניווט הקודם/הבא. מסגרת שהתבקשה במפורש היא כנראה יותר חשובה ממסגרת שנטענה באופן אוטומטי, כי למשתמש כנראה יש חשיבות לעובדה שהפריים המבוקש נטענה.
'נוצר'המשתמש הגיע לדף הזה על ידי הקלדת בסרגל הכתובות ובחירה ברשומה שלא נראית כמו כתובת URL. לדוגמה, התאמה עשויה לכלול את כתובת האתר של דף תוצאות חיפוש ב-Google, אך היא עשויה להופיע בפני המשתמש בתור "חיפוש ב-Google אחר ...". הניווטים האלה לא זהים לניווטים מסוגלים, כי המשתמש לא הקליד או ראה את כתובת היעד. מומלץ לעיין גם במאמר מילת מפתח.
'auto_toplevel'הדף צוין בשורת הפקודה או שהוא דף הפתיחה.
form_submitהמשתמש מילא ערכים בטופס והגיש אותו. חשוב לדעת שבמצבים מסוימים – למשל אם הטופס משתמש בסקריפט כדי לשלוח תוכן – שליחת טופס לא מובילה לסוג המעבר הזה.
"reload"המשתמש טען מחדש את הדף על ידי לחיצה על לחצן הטעינה מחדש או על ידי הקשה על Enter בסרגל הכתובות. שחזור סשן ופתיחה מחדש של כרטיסייה שנסגרה משתמשים גם בסוג המעבר הזה.
"מילת מפתח"כתובת ה-URL נוצרה ממילת מפתח שניתנת להחלפה, שאינה ספק החיפוש המוגדר כברירת מחדל. מידע נוסף מופיע גם בקטע keyword_generated.
'keyword_generated'תואם לביקור שנוצר עבור מילת מפתח. מומלץ לעיין גם במאמר מילת מפתח.

דוגמאות

כדי לנסות את ה-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[] אופציונלי