browser.bookmarks

คำอธิบาย

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

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

สิทธิ์

bookmarks

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

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

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

วัตถุและพร็อพเพอร์ตี้

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

มีการใช้พร็อพเพอร์ตี้ BookmarkTreeNode ทั่วทั้ง browser.bookmarks API ตัวอย่างเช่น เมื่อคุณเรียกใช้ bookmarks.create คุณจะส่งผ่านโหนดหลักของโหนดใหม่ (parentId) และพร็อพเพอร์ตี้ index, title และ url ของโหนด (ไม่บังคับ) ดูข้อมูลเกี่ยวกับพร็อพเพอร์ตี้ที่โหนดมีได้ที่ bookmarks.BookmarkTreeNode

หมายเหตุ: คุณไม่สามารถใช้ API นี้เพื่อเพิ่มหรือนำรายการในโฟลเดอร์รูทออกได้ นอกจากนี้ คุณยังไม่สามารถเปลี่ยนชื่อ ย้าย หรือนำโฟลเดอร์พิเศษ "แถบบุ๊กมาร์ก" และ "บุ๊กมาร์กอื่นๆ" ออกได้

ตัวอย่าง

โค้ดต่อไปนี้จะสร้างโฟลเดอร์ที่มีชื่อว่า "Extension bookmarks" อาร์กิวเมนต์แรกของ create() จะระบุพร็อพเพอร์ตี้สำหรับโฟลเดอร์ใหม่ อาร์กิวเมนต์ที่ 2 จะกำหนดฟังก์ชันที่จะดำเนินการหลังจากสร้างโฟลเดอร์แล้ว

browser.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

ข้อมูลโค้ดถัดไปจะสร้างบุ๊กมาร์กที่ชี้ไปยังเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์สำหรับส่วนขยาย เนื่องจากจะไม่มีสิ่งใดเกิดขึ้นหากสร้างบุ๊กมาร์กไม่สำเร็จ โค้ดนี้จึงไม่จำเป็นต้องกำหนดฟังก์ชัน Callback

browser.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Bookmarks API จากที่เก็บ chrome-extension-samples

ประเภท

BookmarkTreeNode

โหนด (บุ๊กมาร์กหรือโฟลเดอร์) ในโครงสร้างบุ๊กมาร์ก โหนดบุตรหลานจะเรียงลำดับภายในโฟลเดอร์หลัก

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

• เด็ก

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

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

• dateAdded

  number ไม่บังคับ

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

• dateGroupModified

  number ไม่บังคับ

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

• dateLastUsed

  number ไม่บังคับ

  Chrome 114 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

• folderType

  FolderType ไม่บังคับ

  Chrome 134 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  หากมี โฟลเดอร์นี้เป็นโฟลเดอร์ที่เบราว์เซอร์เพิ่มเข้ามา และผู้ใช้หรือส่วนขยายจะแก้ไขไม่ได้ โหนดย่อยอาจมีการแก้ไข หากโหนดนี้ไม่ได้ตั้งค่าพร็อพเพอร์ตี้ unmodifiable ละเว้นหากผู้ใช้และส่วนขยายแก้ไขโหนดได้ (ค่าเริ่มต้น)

  โดยอาจมีโหนดของชนิดโฟลเดอร์แต่ละประเภทเป็นศูนย์ หนึ่ง หรือหลายโหนดก็ได้ เบราว์เซอร์อาจเพิ่มหรือนำโฟลเดอร์ออกได้ แต่จะดำเนินการผ่าน API ของส่วนขยายไม่ได้

• id

  สตริง

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

• ดัชนี

  number ไม่บังคับ

  ตำแหน่งที่อิงตาม 0 ของโหนดนี้ภายในโฟลเดอร์หลัก

• parentId

  สตริง ไม่บังคับ

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

• การซิงค์

  บูลีน

  Chrome 134 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  ระบุว่าเบราว์เซอร์จะซิงค์โหนดนี้กับพื้นที่เก็บข้อมูลของบัญชีระยะไกลของผู้ใช้หรือไม่ ซึ่งสามารถใช้เพื่อแยกความแตกต่างระหว่าง FolderType เดียวกันในเวอร์ชันบัญชีและเวอร์ชันในเครื่องเท่านั้น ค่าของพร็อพเพอร์ตี้นี้อาจเปลี่ยนแปลงสำหรับโหนดที่มีอยู่ เช่น เป็นผลมาจากการดำเนินการของผู้ใช้

  หมายเหตุ: ข้อมูลนี้จะแสดงว่าโหนดได้รับการบันทึกไว้ในผู้ให้บริการบัญชีในตัวของเบราว์เซอร์หรือไม่ โหนดอาจซิงค์ผ่านบุคคลที่สามได้ แม้ว่าค่านี้จะเป็นเท็จก็ตาม

  สำหรับโหนดที่มีการจัดการ (โหนดที่ตั้งค่า unmodifiable เป็น true) พร็อพเพอร์ตี้นี้จะเป็น false เสมอ

• title

  สตริง

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

• unmodifiable

  "managed"
   ไม่บังคับ

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

• URL

  สตริง ไม่บังคับ

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

BookmarkTreeNodeUnmodifiable

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

ค่า

"managed"

CreateDetails

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

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

• ดัชนี

  number ไม่บังคับ

• parentId

  สตริง ไม่บังคับ

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

• title

  สตริง ไม่บังคับ

• URL

  สตริง ไม่บังคับ

FolderType

Chrome 134 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ระบุประเภทของโฟลเดอร์

ค่าแจกแจง

"bookmarks-bar"
โฟลเดอร์ที่มีเนื้อหาแสดงอยู่ที่ด้านบนของหน้าต่างเบราว์เซอร์

"other"
บุ๊กมาร์กที่แสดงในรายการบุ๊กมาร์กทั้งหมดในทุกแพลตฟอร์ม

"mobile"
บุ๊กมาร์กที่โดยทั่วไปจะพร้อมใช้งานในอุปกรณ์เคลื่อนที่ของผู้ใช้ แต่สามารถแก้ไขได้โดยส่วนขยายหรือในเครื่องมือจัดการบุ๊กมาร์ก

"managed"
โฟลเดอร์ระดับบนสุดที่อาจปรากฏขึ้นหากผู้ดูแลระบบหรือผู้ปกครองของผู้ใช้ภายใต้การควบคุมดูแลได้กำหนดค่าบุ๊กมาร์กไว้

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

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

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

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

ค่า

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

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

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

ค่า

1000000

ROOT_NODE_ID

Chrome 145 ขึ้นไป browser.* ตั้งแต่ Chrome 148

id ที่เชื่อมโยงกับโหนดระดับราก

ค่า

"0"

เมธอด

create()

browser.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

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

พารามิเตอร์

• บุ๊กมาร์ก

  CreateDetails

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

• Promise<BookmarkTreeNode>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

get()

browser.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

ดึงข้อมูล BookmarkTreeNode ที่ระบุ

พารามิเตอร์

• idOrIdList

  string | [string, ...string[]]

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

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

getChildren()

browser.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

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

พารามิเตอร์

• id

  สตริง

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

getRecent()

browser.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

ดึงข้อมูลบุ๊กมาร์กที่เพิ่มล่าสุด

พารามิเตอร์

• numberOfItems

  ตัวเลข

  จำนวนรายการสูงสุดที่จะแสดงผล

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

getSubTree()

browser.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

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

พารามิเตอร์

• id

  สตริง

  รหัสของรูทของโครงสร้างย่อยที่จะดึงข้อมูล

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

getTree()

browser.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

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

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

move()

browser.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

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

พารามิเตอร์

• id

  สตริง

• ปลายทาง

  ออบเจ็กต์

  • ดัชนี

    number ไม่บังคับ

  • parentId

    สตริง ไม่บังคับ

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

• Promise<BookmarkTreeNode>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

remove()

browser.bookmarks.remove(
  id: string,
): Promise<void>

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

พารามิเตอร์

• id

  สตริง

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

• Promise<void>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

removeTree()

browser.bookmarks.removeTree(
  id: string,
): Promise<void>

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

พารามิเตอร์

• id

  สตริง

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

• Promise<void>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

search()

browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

พารามิเตอร์

• query

  string | object

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

  • query

    สตริง ไม่บังคับ

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

  • title

    สตริง ไม่บังคับ

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

  • URL

    สตริง ไม่บังคับ

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

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

• Promise<BookmarkTreeNode[]>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

update()

browser.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

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

พารามิเตอร์

• id

  สตริง

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

  ออบเจ็กต์

  • title

    สตริง ไม่บังคับ

  • URL

    สตริง ไม่บังคับ

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

• Promise<BookmarkTreeNode>

  Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

กิจกรรม

onChanged

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • id

    สตริง

  • changeInfo

    ออบเจ็กต์

    • title

      สตริง

    • URL

      สตริง ไม่บังคับ

onChildrenReordered

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • id

    สตริง

  • reorderInfo

    ออบเจ็กต์

    • childIds

      string[]

onCreated

browser.bookmarks.onCreated.addListener(
  callback: function,
)

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

  (id: string, bookmark: BookmarkTreeNode) => void

  • id

    สตริง

  • บุ๊กมาร์ก

    BookmarkTreeNode

onImportBegan

browser.bookmarks.onImportBegan.addListener(
  callback: function,
)

เริ่มทำงานเมื่อเริ่มเซสชันการนำเข้าบุ๊กมาร์ก Observer ที่มีค่าใช้จ่ายสูงควรละเว้นการอัปเดต onCreated จนกว่าจะมีการเริ่มทำงาน onImportEnded ผู้สังเกตการณ์ควรจัดการการแจ้งเตือนอื่นๆ ทันที

พารามิเตอร์

• callback

  ฟังก์ชัน

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

  () => void

onImportEnded

browser.bookmarks.onImportEnded.addListener(
  callback: function,
)

เริ่มทำงานเมื่อเซสชันการนำเข้าบุ๊กมาร์กสิ้นสุดลง

พารามิเตอร์

• callback

  ฟังก์ชัน

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

  () => void

onMoved

browser.bookmarks.onMoved.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการย้ายบุ๊กมาร์กหรือโฟลเดอร์ไปยังโฟลเดอร์ระดับบนสุดอื่น

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • id

    สตริง

  • moveInfo

    ออบเจ็กต์

    • ดัชนี

      ตัวเลข

    • oldIndex

      ตัวเลข

    • oldParentId

      สตริง

    • parentId

      สตริง

onRemoved

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • id

    สตริง

  • removeInfo

    ออบเจ็กต์

    • ดัชนี

      ตัวเลข

    • โหนด

      BookmarkTreeNode

      Chrome 48 ขึ้นไป browser.* ตั้งแต่ Chrome 148
    • parentId

      สตริง