chrome.bookmarks

คำอธิบาย

ใช้ chrome.bookmarks API เพื่อสร้าง จัดระเบียบ และจัดการบุ๊กมาร์ก นอกจากนี้ โปรดดูลบล้างหน้า ซึ่งคุณสามารถใช้เพื่อสร้างหน้าการจัดการบุ๊กมาร์กที่กำหนดเองได้

การคลิกดาวจะเพิ่มบุ๊กมาร์ก
การคลิกดาวจะเป็นการเพิ่มบุ๊กมาร์ก

สิทธิ์

bookmarks

คุณต้องประกาศสิทธิ์ "บุ๊กมาร์ก" ในไฟล์ Manifest ของส่วนขยายเพื่อใช้ API ของบุ๊กมาร์ก เช่น

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

แนวคิดและการใช้งาน

ออบเจ็กต์และพร็อพเพอร์ตี้

บุ๊กมาร์กจะจัดระเบียบตามแผนผัง โดยแต่ละโหนดในโครงสร้างจะเป็นบุ๊กมาร์กหรือโฟลเดอร์ (บางครั้งเรียกว่ากลุ่ม) แต่ละโหนดในโครงสร้างจะแสดงด้วยออบเจ็กต์ bookmarks.BookmarkTreeNode

ใช้พร็อพเพอร์ตี้ BookmarkTreeNode ใน API ของ chrome.bookmarks ตัวอย่างเช่น เมื่อคุณเรียกใช้ 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 นี้ ให้ติดตั้งตัวอย่าง API บุ๊กมาร์กจากที่เก็บ chrome-extension-ตัวอย่าง

ประเภท

BookmarkTreeNode

โหนด (บุ๊กมาร์กหรือโฟลเดอร์) ในแผนผังบุ๊กมาร์ก โหนดย่อยจะได้รับการเรียงลำดับในโฟลเดอร์หลัก

พร็อพเพอร์ตี้

  • เด็ก

    BookmarkTreeNode[] ไม่บังคับ

    รายการย่อยของโหนดนี้ตามลำดับ

  • dateAdded

    ตัวเลข ไม่บังคับ

    เมื่อสร้างโหนดนี้ หน่วยเป็นมิลลิวินาทีนับตั้งแต่ Epoch (new Date(dateAdded))

  • dateGroupModified

    ตัวเลข ไม่บังคับ

    เมื่อเนื้อหาของโฟลเดอร์นี้มีการเปลี่ยนแปลงครั้งล่าสุด หน่วยเป็นมิลลิวินาทีนับตั้งแต่ Epoch

  • dateLastUsed

    ตัวเลข ไม่บังคับ

    Chrome 114 ขึ้นไป

    เมื่อเปิดโหนดนี้ครั้งล่าสุด หน่วยเป็นมิลลิวินาทีนับตั้งแต่ Epoch ไม่ได้ตั้งค่าสำหรับโฟลเดอร์

  • id

    string

    ตัวระบุที่ไม่ซ้ำกันสำหรับโหนด รหัสจะไม่ซ้ำกันภายในโปรไฟล์ปัจจุบัน และยังคงใช้งานได้แม้ว่าจะรีสตาร์ทเบราว์เซอร์แล้วก็ตาม

  • ดัชนี

    ตัวเลข ไม่บังคับ

    ตำแหน่งฐาน 0 ของโหนดนี้ในโฟลเดอร์ระดับบนสุด

  • parentId

    string ไม่บังคับ

    id ของโฟลเดอร์หลัก ละเว้นสำหรับโหนดรูท

  • title

    string

    ข้อความที่แสดงสำหรับโหนด

  • ไม่สามารถแก้ไขได้

     ไม่บังคับ

    ระบุเหตุผลที่แก้ไขโหนดนี้ไม่ได้ ค่า managed บ่งชี้ว่าโหนดนี้ได้รับการกำหนดค่าโดยผู้ดูแลระบบหรือผู้ปกป้องรักษาผู้ใช้ของผู้ใช้ภายใต้การควบคุมดูแล ละเว้นในกรณีที่ผู้ใช้และส่วนขยายแก้ไขโหนดได้ (ค่าเริ่มต้น)

  • url

    string ไม่บังคับ

    URL ที่นำทางไปเมื่อผู้ใช้คลิกที่บุ๊กมาร์ก ละเว้นสำหรับโฟลเดอร์

BookmarkTreeNodeUnmodifiable

Chrome 44 ขึ้นไป

ระบุเหตุผลที่แก้ไขโหนดนี้ไม่ได้ ค่า managed บ่งบอกว่าผู้ดูแลระบบเป็นผู้กำหนดค่าโหนดนี้ ละเว้นในกรณีที่ผู้ใช้และส่วนขยายแก้ไขโหนดได้ (ค่าเริ่มต้น)

ค่า

CreateDetails

มีการส่งออบเจ็กต์ไปยังฟังก์ชัน create()

พร็อพเพอร์ตี้

  • ดัชนี

    ตัวเลข ไม่บังคับ

  • parentId

    string ไม่บังคับ

    ค่าเริ่มต้นจะเป็นโฟลเดอร์บุ๊กมาร์กอื่น

  • title

    string ไม่บังคับ

  • url

    string ไม่บังคับ

พร็อพเพอร์ตี้

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

เลิกใช้งานแล้ว

Chrome จะไม่จํากัดการเขียนบุ๊กมาร์กอีกต่อไป

ค่า

1000,000

MAX_WRITE_OPERATIONS_PER_HOUR

เลิกใช้งานแล้ว

Chrome จะไม่จํากัดการเขียนบุ๊กมาร์กอีกต่อไป

ค่า

1000,000

วิธีการ

create()

สัญญา 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

สร้างบุ๊กมาร์กหรือโฟลเดอร์ภายใต้ parentId ที่ระบุ หาก URL เป็น NULL หรือขาดหายไป URL จะเป็นโฟลเดอร์

พารามิเตอร์

  • บุ๊กมาร์ก

    CreateDetails

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (result: BookmarkTreeNode)=>void

การคืนสินค้า

  • Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

get()

สัญญา 
chrome.bookmarks.get(
  idOrIdList: string|[string,...string[]],
  callback?: function,
)

เรียก bookmarkTreeNode ที่ระบุ

พารามิเตอร์

  • idOrIdList

    สตริง|[สตริง,...สตริง[]]

    รหัสค่าสตริงเดียว หรืออาร์เรย์ของรหัสค่าสตริง

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getChildren()

สัญญา 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

เรียกข้อมูลรายการย่อยของรหัส bookmarkTreeNode ที่ระบุ

พารามิเตอร์

  • id

    string

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getRecent()

สัญญา 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

เรียกบุ๊กมาร์กที่เพิ่มล่าสุด

พารามิเตอร์

  • numberOfItems

    ตัวเลข

    จำนวนรายการสูงสุดที่จะส่งคืน

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getSubTree()

สัญญา 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

เรียกข้อมูลบางส่วนของลำดับชั้นของบุ๊กมาร์ก โดยเริ่มจากโหนดที่ระบุ

พารามิเตอร์

  • id

    string

    รหัสของรูทของแผนผังย่อยที่จะเรียกข้อมูล

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getTree()

สัญญา 
chrome.bookmarks.getTree(
  callback?: function,
)

เรียกข้อมูลลำดับชั้นบุ๊กมาร์กทั้งหมด

พารามิเตอร์

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

move()

สัญญา 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

ย้าย bookmarkTreeNode ที่ระบุไปยังตำแหน่งที่ระบุ

พารามิเตอร์

  • id

    string

  • ปลายทาง

    ออบเจ็กต์

    • ดัชนี

      ตัวเลข ไม่บังคับ

    • parentId

      string ไม่บังคับ

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (result: BookmarkTreeNode)=>void

การคืนสินค้า

  • Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

remove()

สัญญา 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

นำบุ๊กมาร์กหรือโฟลเดอร์บุ๊กมาร์กที่ว่างเปล่าออก

พารามิเตอร์

  • id

    string

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    ()=>void

การคืนสินค้า

  • Promise<void>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

removeTree()

สัญญา 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

นำโฟลเดอร์บุ๊กมาร์กออกซ้ำๆ

พารามิเตอร์

  • id

    string

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    ()=>void

การคืนสินค้า

  • Promise<void>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

สัญญา 
chrome.bookmarks.search(
  query: string|object,
  callback?: function,
)

การค้นหา bookmarkTreeNodes ที่ตรงกับข้อความค้นหาที่ระบุ การค้นหาที่ระบุด้วยออบเจ็กต์จะสร้าง CookieTreeNodes ที่ตรงกับพร็อพเพอร์ตี้ที่ระบุทั้งหมด

พารามิเตอร์

  • query

    สตริง|ออบเจ็กต์

    สตริงคําและวลีที่ยกมา ซึ่งมีการจับคู่กับ URL และชื่อบุ๊กมาร์ก หรือออบเจ็กต์ หากเป็นออบเจ็กต์ ระบบอาจระบุพร็อพเพอร์ตี้ query, url และ title และสร้างบุ๊กมาร์กที่ตรงกับพร็อพเพอร์ตี้ที่ระบุทั้งหมด

    • query

      string ไม่บังคับ

      สตริงของคำและวลีที่ยกมา ซึ่งจะจับคู่กับ URL และชื่อบุ๊กมาร์ก

    • title

      string ไม่บังคับ

      ชื่อของบุ๊กมาร์กจะตรงกันแบบคำต่อคำ

    • url

      string ไม่บังคับ

      URL ของบุ๊กมาร์ก จะตรงกันแบบคำต่อคำ โปรดทราบว่าโฟลเดอร์จะไม่มี URL

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (results: BookmarkTreeNode[])=>void

การคืนสินค้า

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

update()

สัญญา 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

อัปเดตคุณสมบัติของบุ๊กมาร์กหรือโฟลเดอร์ ระบุเฉพาะคุณสมบัติที่คุณต้องการเปลี่ยนแปลง โดยคุณสมบัติที่ไม่ได้ระบุจะไม่มีการเปลี่ยนแปลง หมายเหตุ: ปัจจุบันรองรับเฉพาะ "title" และ "url" เท่านั้น

พารามิเตอร์

  • id

    string

  • การเปลี่ยนแปลง

    ออบเจ็กต์

    • title

      string ไม่บังคับ

    • url

      string ไม่บังคับ

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (result: BookmarkTreeNode)=>void

การคืนสินค้า

  • Chrome 90 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onChanged

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

เริ่มทำงานเมื่อบุ๊กมาร์กหรือโฟลเดอร์เปลี่ยนแปลง หมายเหตุ: ปัจจุบันมีเฉพาะการเปลี่ยนแปลงชื่อและ URL ที่จะทริกเกอร์เหตุการณ์ดังกล่าว

พารามิเตอร์

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

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

    • id

      string

    • changeInfo

      ออบเจ็กต์

      • title

        string

      • url

        string ไม่บังคับ

onChildrenReordered

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

เริ่มทำงานเมื่อรายการย่อยของโฟลเดอร์เปลี่ยนลำดับเนื่องจากมีการจัดเรียงลำดับใน UI จะไม่เรียกอันเป็นผลจากการย้าย()

พารามิเตอร์

  • 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

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

      ออบเจ็กต์

      • ดัชนี

        ตัวเลข

      • oldIndex

        ตัวเลข

      • oldParentId

        string

      • parentId

        string

onRemoved

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

เริ่มทำงานเมื่อนำบุ๊กมาร์กหรือโฟลเดอร์ออก เมื่อนำโฟลเดอร์ออกซ้ำๆ จะมีการแจ้งเตือน 1 ครั้งสำหรับโฟลเดอร์นั้น โดยไม่มีการแจ้งเตือนสำหรับเนื้อหาในโฟลเดอร์

พารามิเตอร์

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

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

    • id

      string

    • removeInfo

      ออบเจ็กต์

      • ดัชนี

        ตัวเลข

      • โหนด

        BookmarkTreeNode

        Chrome 48 ขึ้นไป
      • parentId

        string