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

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

  • folderType

    FolderType אופציונלי

    בהמתנה

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

    יכול להיות אפס, צומת אחד או כמה צמתים מכל סוג תיקייה. הדפדפן יכול להוסיף או להסיר תיקייה, אבל לא דרך Extensions API.

  • id [מזהה]

    מחרוזת

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

  • אינדקס

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

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

  • parentId

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

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

  • מתבצע סנכרון

    בוליאני

    בהמתנה

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

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

    בצמתים מנוהלים (צמתים שבהם unmodifiable מוגדר כ-true), הערך של המאפיין הזה יהיה תמיד false.

  • title

    מחרוזת

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

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

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

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

  • כתובת אתר

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

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

BookmarkTreeNodeUnmodifiable

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

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

ערך

"managed"

CreateDetails

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

מאפיינים

  • אינדקס

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

  • parentId

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

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

  • title

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

  • כתובת אתר

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

FolderType

בהמתנה

מציין את סוג התיקייה.

Enum

"bookmarks-bar"
התיקייה שהתוכן שלה מוצג בחלק העליון של חלון הדפדפן.

'אחר'
סימניות שמוצגות ברשימת הסימניות המלאה בכל הפלטפורמות.

'mobile'
סימניות שזמינות בדרך כלל במכשירים הניידים של המשתמש, אבל אפשר לשנות אותן באמצעות תוסף או במנהל הסימניות.

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

מאפיינים

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) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

get()

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

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

פרמטרים

  • idOrIdList

    string | [string, ...string[]]

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

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

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

getChildren()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

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

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-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) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

getSubTree()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

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

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

getTree()

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

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

פרמטרים

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

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

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

move()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

  • חשבון יעד

    אובייקט

    • אינדקס

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

    • parentId

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

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

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

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

    (result: BookmarkTreeNode) => void

החזרות

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

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

remove()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

removeTree()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

Promise 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

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

פרמטרים

  • שאילתה

    string | object

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

    • שאילתה

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

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

    • title

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

      שם הסימנייה. ההתאמה היא מילה במילה.

    • כתובת אתר

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

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise<BookmarkTreeNode[]>

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

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

update()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

  • שינויים

    אובייקט

    • title

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

    • כתובת אתר

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

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

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

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

    (result: BookmarkTreeNode) => void

החזרות

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

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-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

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

      מחרוזת

    • moveInfo

      אובייקט

      • אינדקס

        number

      • oldIndex

        number

      • oldParentId

        מחרוזת

      • parentId

        מחרוזת

onRemoved

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

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

פרמטרים

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

    פונקציה

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

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

    • id [מזהה]

      מחרוזת

    • removeInfo

      אובייקט

      • אינדקס

        number

      • צומת

        BookmarkTreeNode

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

        מחרוזת