คำอธิบาย
ใช้ chrome.bookmarks
API เพื่อสร้าง จัดระเบียบ และดำเนินการกับบุ๊กมาร์ก โปรดดูหน้าการลบล้างด้วย ซึ่งคุณใช้สร้างหน้าการจัดการบุ๊กมาร์กที่กำหนดเองได้
สิทธิ์
bookmarks
คุณต้องประกาศสิทธิ์ "บุ๊กมาร์ก" ในไฟล์ Manifest ของเวิร์กชีตจึงจะใช้ Bookmarks API ได้ เช่น
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
แนวคิดและการใช้งาน
วัตถุและพร็อพเพอร์ตี้
บุ๊กมาร์กจะจัดระเบียบเป็นโครงสร้างต้นไม้ โดยแต่ละโหนดในต้นไม้จะเป็นบุ๊กมาร์กหรือโฟลเดอร์ (บางครั้งเรียกว่ากลุ่ม) แต่ละโหนดในต้นไม้จะแสดงด้วยออบเจ็กต์ bookmarks.BookmarkTreeNode
ระบบจะใช้พร็อพเพอร์ตี้ BookmarkTreeNode
ทั่วทั้ง chrome.bookmarks
API เช่น เมื่อเรียกใช้ bookmarks.create คุณต้องส่งค่าให้กับพร็อพเพอร์ตี้หลัก (parentId
) ของโหนดใหม่ และพร็อพเพอร์ตี้ index
, title
และ url
ของโหนด (ไม่บังคับ) ดูข้อมูลเกี่ยวกับพร็อพเพอร์ตี้ที่โหนดมีได้ที่ bookmarks.BookmarkTreeNode
ตัวอย่าง
โค้ดต่อไปนี้จะสร้างโฟลเดอร์ที่มีชื่อว่า "บุ๊กมาร์กส่วนขยาย" อาร์กิวเมนต์แรกสำหรับ create()
จะระบุพร็อพเพอร์ตี้สําหรับโฟลเดอร์ใหม่ อาร์กิวเมนต์ที่ 2 จะกำหนดฟังก์ชันที่จะดำเนินการหลังจากสร้างโฟลเดอร์แล้ว
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
สตริง
ตัวระบุที่ไม่ซ้ำกันสำหรับโหนด รหัสจะไม่ซ้ำกันในโปรไฟล์ปัจจุบันและจะยังคงใช้งานได้แม้ว่าจะรีสตาร์ทเบราว์เซอร์แล้วก็ตาม
-
ดัชนี
ตัวเลข ไม่บังคับ
ตำแหน่งฐาน 0 ของโหนดนี้ภายในโฟลเดอร์ระดับบน
-
parentId
สตริง ไม่บังคับ
id
ของโฟลเดอร์หลัก ละเว้นสำหรับโหนดรูท -
title
สตริง
ข้อความที่แสดงสําหรับโหนด
-
แก้ไขไม่ได้
"managed"
ไม่บังคับระบุสาเหตุที่ไม่สามารถแก้ไขโหนดนี้ได้ ค่า
managed
บ่งชี้ว่าผู้ดูแลระบบหรือผู้ดูแลผู้ใช้ภายใต้การควบคุมดูแลเป็นผู้กำหนดค่าโหนดนี้ ละเว้นหากผู้ใช้และส่วนขยายแก้ไขโหนดได้ (ค่าเริ่มต้น) -
URL
สตริง ไม่บังคับ
URL ที่ไปยังเมื่อผู้ใช้คลิกบุ๊กมาร์ก ละเว้นสำหรับโฟลเดอร์
BookmarkTreeNodeUnmodifiable
ระบุสาเหตุที่ไม่สามารถแก้ไขโหนดนี้ได้ ค่า managed
บ่งชี้ว่าผู้ดูแลระบบเป็นผู้กําหนดค่าโหนดนี้ ละเว้นหากผู้ใช้และส่วนขยายแก้ไขโหนดได้ (ค่าเริ่มต้น)
ค่า
"managed"
CreateDetails
ออบเจ็กต์ที่ส่งไปยังฟังก์ชัน create()
พร็อพเพอร์ตี้
-
ดัชนี
ตัวเลข ไม่บังคับ
-
parentId
สตริง ไม่บังคับ
ค่าเริ่มต้นคือโฟลเดอร์บุ๊กมาร์กอื่นๆ
-
title
สตริง ไม่บังคับ
-
URL
สตริง ไม่บังคับ
พร็อพเพอร์ตี้
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 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
เรียกข้อมูล BookmarkTreeNode ที่ระบุ
พารามิเตอร์
-
idOrIdList
string | [string, ...string[]]
รหัสที่มีค่าสตริงรายการเดียวหรืออาร์เรย์ของรหัสที่มีค่าสตริง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
ดึงข้อมูลรายการย่อยของรหัส BookmarkTreeNode ที่ระบุ
พารามิเตอร์
-
id
สตริง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
เรียกข้อมูลบุ๊กมาร์กที่เพิ่มล่าสุด
พารามิเตอร์
-
numberOfItems
ตัวเลข
จำนวนรายการสูงสุดที่จะแสดง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
ดึงข้อมูลส่วนหนึ่งของลําดับชั้นบุ๊กมาร์กโดยเริ่มจากโหนดที่ระบุ
พารามิเตอร์
-
id
สตริง
รหัสของรูทของโครงสร้างย่อยที่จะดึงข้อมูล
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
ดึงข้อมูลลําดับชั้นของบุ๊กมาร์กทั้งหมด
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
ย้าย BookmarkTreeNode ที่ระบุไปยังตำแหน่งที่ระบุ
พารามิเตอร์
-
id
สตริง
-
ปลายทาง
ออบเจ็กต์
-
ดัชนี
ตัวเลข ไม่บังคับ
-
parentId
สตริง ไม่บังคับ
-
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(result: BookmarkTreeNode) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
นำบุ๊กมาร์กหรือโฟลเดอร์บุ๊กมาร์กว่างออก
พารามิเตอร์
-
id
สตริง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
นำโฟลเดอร์บุ๊กมาร์กออกแบบตามลำดับชั้น
พารามิเตอร์
-
id
สตริง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
ค้นหา BookmarkTreeNode ที่ตรงกับข้อความค้นหาที่ระบุ การค้นหาที่ระบุด้วยออบเจ็กต์จะสร้าง BookmarkTreeNode ที่ตรงกับพร็อพเพอร์ตี้ที่ระบุทั้งหมด
พารามิเตอร์
-
query
สตริง | ออบเจ็กต์
สตริงคำและวลีที่ยกมาซึ่งจะจับคู่กับ URL และชื่อบุ๊กมาร์ก หรือออบเจ็กต์ หากออบเจ็กต์ คุณสามารถระบุพร็อพเพอร์ตี้
query
,url
และtitle
แล้วระบบจะสร้างบุ๊กมาร์กที่ตรงกับพร็อพเพอร์ตี้ที่ระบุทั้งหมด-
query
สตริง ไม่บังคับ
สตริงคำและวลีที่ยกมาซึ่งจะจับคู่กับ URL และชื่อของบุ๊กมาร์ก
-
title
สตริง ไม่บังคับ
ชื่อของบุ๊กมาร์ก ซึ่งจะตรงกันทุกประการ
-
URL
สตริง ไม่บังคับ
URL ของบุ๊กมาร์ก ซึ่งจะจับคู่แบบตรงทั้งหมด โปรดทราบว่าโฟลเดอร์ไม่มี URL
-
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(results: BookmarkTreeNode[]) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode[]>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
อัปเดตพร็อพเพอร์ตี้ของบุ๊กมาร์กหรือโฟลเดอร์ โปรดระบุเฉพาะพร็อพเพอร์ตี้ที่ต้องการเปลี่ยน โดยระบบจะไม่เปลี่ยนแปลงพร็อพเพอร์ตี้ที่ไม่ได้ระบุ หมายเหตุ: ปัจจุบันระบบรองรับเฉพาะ "title" และ "url" เท่านั้น
พารามิเตอร์
-
id
สตริง
-
การเปลี่ยนแปลง
ออบเจ็กต์
-
title
สตริง ไม่บังคับ
-
URL
สตริง ไม่บังคับ
-
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(result: BookmarkTreeNode) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<BookmarkTreeNode>
Chrome 90 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
กิจกรรม
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
เรียกใช้เมื่อมีการเปลี่ยนแปลงบุ๊กมาร์กหรือโฟลเดอร์ หมายเหตุ: ปัจจุบันมีเพียงการเปลี่ยนแปลงชื่อและ URL เท่านั้นที่ทริกเกอร์การดำเนินการนี้
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
จะมีลักษณะดังนี้(id: string, changeInfo: object) => void
-
id
สตริง
-
changeInfo
ออบเจ็กต์
-
title
สตริง
-
URL
สตริง ไม่บังคับ
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
เรียกใช้เมื่อรายการย่อยของโฟลเดอร์มีการเปลี่ยนแปลงลําดับเนื่องจากมีการจัดเรียงลําดับใน UI การดำเนินการนี้ไม่ได้เรียกใช้เนื่องจาก 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
สตริง
-
บุ๊กมาร์ก
-
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
ออบเจ็กต์
-
ดัชนี
ตัวเลข
-
oldIndex
ตัวเลข
-
oldParentId
สตริง
-
parentId
สตริง
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
เรียกใช้เมื่อนำบุ๊กมาร์กหรือโฟลเดอร์ออก เมื่อนำโฟลเดอร์ออกแบบซ้ำซ้อน ระบบจะแสดงการแจ้งเตือน 1 ครั้งสำหรับโฟลเดอร์นั้น และไม่แสดงการแจ้งเตือนสำหรับเนื้อหาในโฟลเดอร์
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
จะมีลักษณะดังนี้(id: string, removeInfo: object) => void
-
id
สตริง
-
removeInfo
ออบเจ็กต์
-
ดัชนี
ตัวเลข
-
โหนดChrome 48 ขึ้นไป
-
parentId
สตริง
-
-