chrome.bookmarks

คำอธิบาย

ใช้ 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

Chrome 44 ขึ้นไป

ระบุสาเหตุที่ไม่สามารถแก้ไขโหนดนี้ได้ ค่า 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

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

  • 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

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

  • 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 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

สัญญา
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

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

  • 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

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

        สตริง