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

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

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 של תיקיית ההורה. חסר עבור צומת הרמה הבסיסית (root).

  • title

    מחרוזת

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

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

    "מנוהל"
     אופציונלי

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

  • כתובת אתר

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

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

BookmarkTreeNodeUnmodifiable

Chrome 44 ואילך

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

ערך

"מנוהל"

CreateDetails

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

מאפיינים

  • index

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

  • parentId

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

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

  • title

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

  • כתובת אתר

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

מאפיינים

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

הוצא משימוש

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

ערך

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

הוצא משימוש

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

ערך

1000000

שיטות

create()

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

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

פרמטרים

החזרות

  • Promise<BookmarkTreeNode>

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

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

get()

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

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

פרמטרים

  • idOrIdList

    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

    number

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

  • קריאה חוזרת (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

החזרות

  • Promise<BookmarkTreeNode>

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

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

remove()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

removeTree()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

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

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

פרמטרים

  • שאילתה

    string | אובייקט

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

    • שאילתה

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

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

    • title

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

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

    • כתובת אתר

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

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

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

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

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

    (results: BookmarkTreeNode[]) => void

החזרות

  • Promise&lt;BookmarkTreeNode[]&gt;

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

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

update()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

  • שינויים

    אובייקט

    • title

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

    • כתובת אתר

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

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

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

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

    (result: BookmarkTreeNode) => void

החזרות

  • Promise&lt;BookmarkTreeNode&gt;

    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

        String[]

onCreated

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

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

פרמטרים

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

    פונקציה

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

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

onImportBegan

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

מופעל כשמתחיל סשן של ייבוא סימניות. צופים יקרים צריכים להתעלם מעדכונים שנוצרו עד שתתבצע 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

        number

      • oldIndex

        number

      • oldParentId

        מחרוזת

      • parentId

        מחרוזת

onRemoved

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

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

פרמטרים

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

    פונקציה

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

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

    • id [מזהה]

      מחרוזת

    • removeInfo

      אובייקט

      • index

        number

      • צומת

        BookmarkTreeNode

        Chrome 48 ואילך
      • parentId

        מחרוזת