chrome.bookmarks

ההרשאה הזו מפעילה אזהרה.

תיאור

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

הרשאות

bookmarks

מניפסט

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

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

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

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

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

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

דוגמאות

הקוד הבא יוצר תיקייה עם הכותרת Extension bookmarks (סימניות של תוספים). הארגומנט הראשון של ‫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

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

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

• dateLastUsed

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

  ‫Chrome 114 ואילך

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

• folderType

  ‫FolderType אופציונלי

  ‫Chrome 134 ואילך

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

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

• id [מזהה]

  מחרוזת

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

• אינדקס

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

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

• parentId

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

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

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

  בוליאני

  ‫Chrome 134 ואילך

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

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

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

• title

  מחרוזת

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

• אי אפשר לשנות

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

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

• כתובת אתר

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

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

BookmarkTreeNodeUnmodifiable

‫Chrome 44 ואילך

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

ערך

‫"managed"

CreateDetails

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

מאפיינים

• אינדקס

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

• parentId

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

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

• title

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

• כתובת אתר

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

FolderType

‫Chrome 134 ואילך

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

Enum

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

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

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

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

מאפיינים

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

הוצא משימוש

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

ערך

‫1000000

MAX_WRITE_OPERATIONS_PER_HOUR

הוצא משימוש

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

ערך

‫1000000

ROOT_NODE_ID

בהמתנה

ה-id שמשויך לצומת ברמת הבסיס.

ערך

‫"0"

Methods

create()

Promise

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

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

פרמטרים

• סימנייה

  CreateDetails

• callback

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

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

  (result: BookmarkTreeNode) => void

  • תוצאה

    BookmarkTreeNode

החזרות

• Promise<BookmarkTreeNode>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

get()

Promise

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

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

פרמטרים

• idOrIdList

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

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

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getChildren()

Promise

chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

פרמטרים

• id [מזהה]

  מחרוזת

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getRecent()

Promise

chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

פרמטרים

• numberOfItems

  number

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

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getSubTree()

Promise

chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

פרמטרים

• id [מזהה]

  מחרוזת

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

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getTree()

Promise

chrome.bookmarks.getTree(
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

פרמטרים

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

move()

Promise

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

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

פרמטרים

• id [מזהה]

  מחרוזת

• destination

  אובייקט

  • אינדקס

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

  • parentId

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

• callback

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

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

  (result: BookmarkTreeNode) => void

  • תוצאה

    BookmarkTreeNode

החזרות

• Promise<BookmarkTreeNode>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

remove()

Promise

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

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

פרמטרים

• id [מזהה]

  מחרוזת

• callback

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

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

  () => void

החזרות

• Promise<void>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

removeTree()

Promise

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

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

פרמטרים

• id [מזהה]

  מחרוזת

• callback

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

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

  () => void

החזרות

• Promise<void>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

search()

Promise

chrome.bookmarks.search(
  query: string | object,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

פרמטרים

• שאילתה

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

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

  • שאילתה

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

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

  • title

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

    השם של הסימנייה. צריך להיות זהה בדיוק.

  • כתובת אתר

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

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

• callback

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

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

  (results: BookmarkTreeNode[]) => void

  • תוצאות

    BookmarkTreeNode[]

החזרות

• Promise<BookmarkTreeNode[]>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

update()

Promise

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

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

פרמטרים

• id [מזהה]

  מחרוזת

• שינויים

  אובייקט

  • title

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

  • כתובת אתר

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

• callback

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

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

  (result: BookmarkTreeNode) => void

  • תוצאה

    BookmarkTreeNode

החזרות

• Promise<BookmarkTreeNode>

  ‫Chrome 90 ואילך

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

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

  • id [מזהה]

    מחרוזת

  • סימנייה

    BookmarkTreeNode

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

      מחרוזת