chrome.bookmarks

תיאור

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

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

הרשאות

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);
  },
);

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

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

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

    גרסה 114 ואילך של Chrome

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

  • id [מזהה]

    string

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

  • אינדקס

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

    המיקום של הצומת הזה בתיקיית ההורה, שמתחיל ב-0.

  • parentId

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

    ה-id של תיקיית ההורה. לא מצוין בצומת הבסיס.

  • title

    string

    הטקסט שמוצג לצומת.

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

    'managed'
     אופציונלי

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

  • כתובת אתר

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

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

BookmarkTreeNodeUnmodifiable

גרסה 44 ואילך של Chrome

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

ערך

"managed"

CreateDetails

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

מאפיינים

  • אינדקס

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

  • parentId

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

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

  • title

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

  • כתובת אתר

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

מאפיינים

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

הוצא משימוש

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

ערך

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

הוצא משימוש

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

ערך

1000000

Methods

create()

Promise 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

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

פרמטרים

החזרות

  • גרסה 90 ואילך של Chrome

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

get()

Promise 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

אחזור של BookmarkTreeNodes שצוינו.

פרמטרים

  • idOrIdList

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

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

    גרסה 90 ואילך של Chrome

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

getChildren()

Promise 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

    גרסה 90 ואילך של Chrome

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

getRecent()

Promise 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

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

פרמטרים

  • numberOfItems

    number

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

    גרסה 90 ואילך של Chrome

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

getSubTree()

Promise 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

    גרסה 90 ואילך של Chrome

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

getTree()

Promise 
chrome.bookmarks.getTree(
  callback?: function,
)

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

פרמטרים

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

    גרסה 90 ואילך של Chrome

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

move()

Promise 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string

  • חשבון יעד

    אובייקט

    • אינדקס

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

    • parentId

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

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

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

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

    (result: BookmarkTreeNode) => void

החזרות

  • גרסה 90 ואילך של Chrome

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

remove()

Promise 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string

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

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 90 ואילך של Chrome

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

removeTree()

Promise 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

הסרה רפלקטיבית של תיקיית סימניות.

פרמטרים

  • id [מזהה]

    string

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

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 90 ואילך של Chrome

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

Promise 
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[]>

    גרסה 90 ואילך של Chrome

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

update()

Promise 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string

  • שינויים

    אובייקט

    • title

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

    • כתובת אתר

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

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

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

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

    (result: BookmarkTreeNode) => void

החזרות

  • גרסה 90 ואילך של Chrome

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

אירועים

onChanged

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

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

פרמטרים

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

    פונקציה

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

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

    • id [מזהה]

      string

    • changeInfo

      אובייקט

      • title

        string

      • כתובת אתר

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

onChildrenReordered

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

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

פרמטרים

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

    פונקציה

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

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

    • id [מזהה]

      string

    • reorderInfo

      אובייקט

      • childIds

        string[]

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 [מזהה]

      string

    • moveInfo

      אובייקט

      • אינדקס

        number

      • oldIndex

        number

      • oldParentId

        string

      • parentId

        string

onRemoved

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

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

פרמטרים

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

    פונקציה

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

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

    • id [מזהה]

      string

    • removeInfo

      אובייקט

      • אינדקס

        number

      • צומת

        BookmarkTreeNode

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

        string