chrome.bookmarks

תיאור

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

לחיצה על סמל הכוכב מוסיפה סימניה
לחיצה על סמל הכוכב מוסיפה סימניה.

הרשאות

bookmarks

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

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

מושגים ושימוש

אובייקטים ומאפיינים

הסימניות מאורגנות בעץ, כאשר כל צומת בעץ הוא סימנייה או תיקייה (שלפעמים נקראת קבוצה). כל צומת בעץ מיוצג על ידי אובייקט bookmarks.BookmarkTreeNode.

נעשה שימוש בנכסי BookmarkTreeNode בכל ה-API של chrome.bookmarks. לדוגמה, כשקוראים ל-bookmarks.create, מעבירים את ההורה של הצומת החדש (parentId), ואפשר להעביר את המאפיינים index, title ו-url של הצומת. מידע נוסף על המאפיינים שיכולים להיות לצומת זמין בכתובת bookmarks.BookmarkTreeNode.

דוגמאות

הקוד הבא יוצר תיקייה עם הכותרת 'סימניות תוספים'. הארגומנט הראשון של create() מציין מאפיינים של התיקייה החדשה. הארגומנט השני מגדיר פונקציה שצריך לבצע אחרי יצירת התיקייה.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

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

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

כדי לנסות את ה-API הזה, התקינו את הדוגמה של Bookmarks API מהמאגר chrome-extension-samples.

סוגים

BookmarkTreeNode

צומת (סימנייה או תיקייה) בעץ הסימניות. צמתים של צאצאים מסודרים בתוך תיקיית ההורה שלהם.

תכונות

  • ילדים

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

    רשימה ממוינת של צאצאים של הצומת הזה.

  • dateAdded

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

    כשהצומת הזה נוצר, באלפיות השנייה מאז תחילת התקופה (new Date(dateAdded)).

  • dateGroupModified

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

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

  • dateLastUsed

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

    Chrome 114 ומעלה

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

  • id

    מחרוזת

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

  • index

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

    המיקום המבוסס על 0 של הצומת הזה בתיקיית ההורה שלו.

  • parentId

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

    id של תיקיית ההורה. מוסר עבור צומת השורש.

  • title

    מחרוזת

    הטקסט המוצג עבור הצומת.

  • לא ניתן לשינוי

     אופציונלי

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

  • כתובת אתר

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

    כתובת ה-URL עברה כשמשתמש לוחץ על הסימנייה. מושמט בתיקיות.

BookmarkTreeNodeUnmodifiable

Chrome 44 ואילך

מציין את הסיבה לכך שאי אפשר לשנות את הצומת. הערך managed מציין שהצומת הזה הוגדר על ידי מנהל המערכת. היא תוסר אם המשתמש והתוסף יכולים לשנות את הצומת (ברירת מחדל).

Value

CreateDetails

האובייקט מועבר לפונקציה create() .

תכונות

  • index

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

  • parentId

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

    ברירת המחדל היא התיקייה 'סימניות אחרות'.

  • title

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

  • כתובת אתר

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

תכונות

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

הוצא משימוש

פעולות כתיבת הסימניות לא מוגבלות יותר על ידי Chrome.

Value

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

הוצא משימוש

פעולות כתיבת הסימניות לא מוגבלות יותר על ידי Chrome.

Value

1000000

שיטות

create()

הבטחה 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

יצירת סימנייה או תיקייה עם מזהה ההורה שצוין. אם כתובת ה-URL היא NULL או חסרה, זו תהיה תיקייה.

פרמטרים

החזרות

  • Chrome 90 ומעלה

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

get()

הבטחה 
chrome.bookmarks.get(
  idOrIdList: string|[string,...string[]],
  callback?: function,
)

מאחזר את ה-BookmarkTreeNode(s) שצוין.

פרמטרים

  • idOrIdList

    מחרוזת|[string,...string[]]

    מזהה בעל ערך מחרוזת יחיד, או מערך של מזהים בעלי ערך מחרוזת

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

getChildren()

הבטחה 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

מאחזר את הצאצאים של מזהה BookmarkTreeNode שצוין.

פרמטרים

  • id

    מחרוזת

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

getRecent()

הבטחה 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

מאחזר את הסימניות שנוספו לאחרונה.

פרמטרים

  • numberOfItems

    מספר

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

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

getSubTree()

הבטחה 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

מאחזר חלק מהיררכיית הסימניות, החל מהצומת שצוין.

פרמטרים

  • id

    מחרוזת

    המזהה של השורש של עץ המשנה שיש לאחזר.

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

getTree()

הבטחה 
chrome.bookmarks.getTree(
  callback?: function,
)

מאחזר את כל היררכיית הסימניות.

פרמטרים

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

move()

הבטחה 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

מעביר את BookmarkTreeNode שצוין למיקום שצוין.

פרמטרים

  • id

    מחרוזת

  • חשבון יעד

    אובייקט

    • index

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

    • parentId

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

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

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

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

    (result: BookmarkTreeNode)=>void

החזרות

  • Chrome 90 ומעלה

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

remove()

הבטחה 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

מסיר סימנייה או תיקיית סימניות ריקה.

פרמטרים

  • id

    מחרוזת

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 90 ומעלה

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

removeTree()

הבטחה 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

מסיר תיקיית סימניות באופן חזרתי.

פרמטרים

  • id

    מחרוזת

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 90 ומעלה

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

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

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

פרמטרים

  • שאילתה

    מחרוזת|אובייקט

    מחרוזת של מילים וביטויים מצוטטים שתואמים לכתובות URL ולכותרות של סימניות או אובייקט. אם אובייקט מסוים, ניתן לציין את המאפיינים query, url ו-title, ויופקו סימניות שתואמות לכל המאפיינים שצוינו.

    • שאילתה

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

      מחרוזת של מילים וביטויים מצוטטים שמותאמים לכתובות URL וכותרות של סימניות.

    • title

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

      כותרת הסימנייה; תואמת, מילה במילה.

    • כתובת אתר

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

      כתובת ה-URL של הסימנייה. תואמת, מילה במילה. שימו לב שלתיקיות אין כתובת URL.

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

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

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

    (results: BookmarkTreeNode[])=>void

החזרות

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ומעלה

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

update()

הבטחה 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

עדכון המאפיינים של סימנייה או תיקייה. מציינים רק את המאפיינים שרוצים לשנות. מאפיינים שלא צוינו לא ישתנו. הערה: בשלב הזה יש תמיכה רק בשדות 'title' [שם פריט] ו-'url' [כתובת URL].

פרמטרים

  • id

    מחרוזת

  • שינויים

    אובייקט

    • title

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

    • כתובת אתר

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

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

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

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

    (result: BookmarkTreeNode)=>void

החזרות

  • Chrome 90 ומעלה

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

אירועים

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

מופעל כשסימנייה או תיקייה משתנה. הערה: בשלב הזה, רק שינויים של כותרת וכתובת URL גורמים לכך.

פרמטרים

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

    פונקציה

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

    (id: string,changeInfo: object)=>void

    • id

      מחרוזת

    • changeInfo

      אובייקט

      • title

        מחרוזת

      • כתובת אתר

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

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

מופעל כשצאצאים של תיקייה שינו את הסדר שלהם עקב מיון הסדר בממשק המשתמש. פעולה זו לא נקראת כתוצאה מ-Move().

פרמטרים

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

    פונקציה

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

    (id: string,reorderInfo: object)=>void

    • id

      מחרוזת

    • reorderInfo

      אובייקט

      • childIds

        מחרוזת[]

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

מופעל בעת יצירת סימנייה או תיקייה.

פרמטרים

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

    פונקציה

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

    (id: string,bookmark: BookmarkTreeNode)=>void

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    ()=>void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

מופעל כשמסתיים סשן של ייבוא סימניות.

פרמטרים

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

    פונקציה

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

    ()=>void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (id: string,moveInfo: object)=>void

    • id

      מחרוזת

    • moveInfo

      אובייקט

      • index

        מספר

      • oldIndex

        מספר

      • oldParentId

        מחרוזת

      • parentId

        מחרוזת

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (id: string,removeInfo: object)=>void

    • id

      מחרוזת

    • removeInfo

      אובייקט

      • index

        מספר

      • צומת (Node)

        BookmarkTreeNode

        Chrome מגרסה 48 ואילך
      • parentId

        מחרוזת