תיאור
אפשר להשתמש ב-API של chrome.bookmarks
כדי ליצור סימניות, לארגן אותן ולבצע בהן פעולות אחרות. במאמר שינוי דפים אפשר גם ליצור דף מותאם אישית של ניהול הסימניות.
![לחיצה על סמל הכוכב מוסיפה סימניה](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/bookmarks.png?authuser=5&hl=he)
הרשאות
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
string
המזהה הייחודי של הצומת. המזהים הם ייחודיים בפרופיל הנוכחי, והם נשארים בתוקף גם לאחר הפעלת הדפדפן מחדש.
-
index
מספר אופציונלי
המיקום המבוסס על 0 של הצומת הזה בתיקיית ההורה שלו.
-
parentId
מחרוזת אופציונלי
id
של תיקיית ההורה. מוסר עבור צומת השורש. -
title
string
הטקסט המוצג עבור הצומת.
-
לא ניתן לשינוי
אופציונלי
מציין את הסיבה לכך שאי אפשר לשנות את הצומת. הערך
managed
מציין שהצומת הזה הוגדר על ידי מנהל המערכת או על ידי הנאמן של משתמש בפיקוח. היא תוסר אם המשתמש והתוסף יכולים לשנות את הצומת (ברירת מחדל). -
כתובת אתר
מחרוזת אופציונלי
כתובת ה-URL עברה כשמשתמש לוחץ על הסימנייה. מושמט בתיקיות.
BookmarkTreeNodeUnmodifiable
מציין את הסיבה לכך שאי אפשר לשנות את הצומת. הערך 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 או חסרה, זו תהיה תיקייה.
פרמטרים
-
להוסיף לסימניות
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: BookmarkTreeNode) => void
-
תוצאה אחת
-
החזרות
-
Promise<BookmarkTreeNode>
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
string
-
קריאה חוזרת (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
string
המזהה של השורש של עץ המשנה שיש לאחזר.
-
קריאה חוזרת (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
string
-
חשבון יעד
אובייקט
-
index
מספר אופציונלי
-
parentId
מחרוזת אופציונלי
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: BookmarkTreeNode) => void
-
תוצאה אחת
-
החזרות
-
Promise<BookmarkTreeNode>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
מסיר סימנייה או תיקיית סימניות ריקה.
פרמטרים
-
id
string
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
מסיר תיקיית סימניות באופן חזרתי.
פרמטרים
-
id
string
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
search()
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
string
-
שינויים
אובייקט
-
title
מחרוזת אופציונלי
-
כתובת אתר
מחרוזת אופציונלי
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: BookmarkTreeNode) => void
-
תוצאה אחת
-
החזרות
-
Promise<BookmarkTreeNode>
Chrome 90 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (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
מחרוזת[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
מופעל בעת יצירת סימנייה או תיקייה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(id: string, bookmark: BookmarkTreeNode) => void
-
id
string
-
להוסיף לסימניות
-
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
אובייקט
-
index
number
-
oldIndex
number
-
oldParentId
string
-
parentId
string
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
מופעל כאשר סימניה או תיקייה מוסרות. כאשר מסירים תיקייה באופן רקורסיבי, מופעלת התראה יחידה עבור התיקייה, ואין עבור התוכן שלה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(id: string, removeInfo: object) => void
-
id
string
-
removeInfo
אובייקט
-
index
number
-
צומת (Node)Chrome מגרסה 48 ואילך
-
parentId
string
-
-