chrome.bookmarks

說明

使用 chrome.bookmarks API 建立、整理及控制書籤。此外，您也可以參閱「覆寫網頁」，以便建立自訂書籤管理員頁面。

按一下星號即可新增書籤
按一下星號即可加入書籤。

權限

bookmarks

您必須在擴充功能資訊清單中宣告「書籤」權限，才能使用書籤 API。 例如：

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

概念和用法

物件和屬性

書籤會以樹狀結構加以分類，而樹狀結構中的每個節點都是書籤或資料夾 (有時稱為「群組」)。樹狀結構中的每個節點都由 bookmarks.BookmarkTreeNode 物件表示

BookmarkTreeNode 屬性用於整個 chrome.bookmarks API。舉例來說，呼叫 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，請從 chrome-extension-samples 存放區安裝 bookmark API 範例。

類型

BookmarkTreeNode

書籤樹狀結構中的節點 (書籤或資料夾)。子項節點會在上層資料夾中排序。

屬性

  • 孩子

    BookmarkTreeNode[] 選用

    這個節點的子項已排序清單。

  • dateAdded

    數字 選填

    這個節點的建立時間，以 Epoch 紀元時間 (new Date(dateAdded)) 起算的毫秒為單位。

  • dateGroupModified

    數字 選填

    這個資料夾的內容上次變更時 (自 Epoch 紀元時間起算，以毫秒為單位)。

  • dateLastUsed

    數字 選填

    Chrome 114 以上版本

    這個節點的上次開啟時間 (以 Epoch 紀元時間起算的毫秒為單位)。未設定資料夾。

  • id

    字串

    節點的專屬 ID。ID 是目前設定檔中的唯一識別碼，即使瀏覽器重新啟動後，ID 也依然有效。

  • 索引

    數字 選填

    這個節點在其上層資料夾內的位置 (從 0 開始)。

  • parentId

    字串 選用

    父項資料夾的 id。如為根節點，則會省略。

  • title

    字串

    節點顯示的文字。

  • 無法修改

     選用

    指出這個節點無法修改的原因。managed 值代表這個節點是由系統管理員或受監管使用者的保管人設定。如果使用者和擴充功能可修改節點，則可省略這個欄位 (預設)。

  • url

    字串 選用

    使用者點按書籤後前往的網址。如為資料夾，則不用勾選。

BookmarkTreeNodeUnmodifiable

Chrome 44 以上版本

指出這個節點無法修改的原因。managed 值表示系統管理員已設定這個節點。如果使用者和擴充功能可修改節點，則可省略這個欄位 (預設)。

值

CreateDetails

傳遞至 create() 函式的物件。

屬性

  • 索引

    數字 選填

  • parentId

    字串 選用

    預設值為「其他書籤」資料夾。

  • title

    字串 選用

  • url

    字串 選用

屬性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

已淘汰

Chrome 不再限制書籤寫入作業。

值

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

已淘汰

Chrome 不再限制書籤寫入作業。

值

1000000

方法

create()

Promise 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

在指定 parentId 下建立書籤或資料夾。如果網址為 NULL 或缺少網址，就會成為資料夾。

參數

傳回

  • Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

get()

Promise 
chrome.bookmarks.get(
  idOrIdList: string|[string,...string[]],
  callback?: function,
)

擷取指定的 bookmarkTreeNode。

參數

  • idOrIdList

    string|[字串,...字串 []]

    單一字串值 ID，或字串值 ID

  • 回呼

    函式選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[])=>void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getChildren()

Promise 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

擷取指定 bookmarkTreeNode ID 的子項。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getRecent()

Promise 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

擷取最近新增的書籤。

參數

  • numberOfItems

    號碼

    傳回的項目數量上限。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[])=>void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getSubTree()

Promise 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

從指定的節點擷取部分書籤階層。

參數

  • id

    字串

    要擷取的子樹狀結構根層級 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[])=>void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getTree()

Promise 
chrome.bookmarks.getTree(
  callback?: function,
)

擷取整個書籤階層。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

move()

Promise 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

將指定的 bookmarkTreeNode 移至提供的位置。

參數

  • id

    字串

  • 目的地

    物件

    • 索引

      數字 選填

    • parentId

      字串 選用

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: BookmarkTreeNode)=>void

傳回

  • Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

remove()

Promise 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

移除書籤或空白書籤資料夾。

參數

  • id

    字串

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeTree()

Promise 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

以遞迴方式移除書籤資料夾。

參數

  • id

    字串

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

Promise 
chrome.bookmarks.search(
  query: string|object,
  callback?: function,
)

搜尋符合指定查詢的 bookmarkTreeNodes。以物件指定的查詢會產生符合所有指定屬性的 bookmarkTreeNodes。

參數

  • 項查詢

    string|object

    與書籤網址和標題或物件進行比對的單字或引用詞組。如果物件可指定 query、url 和 title 屬性，則可指定與所有指定屬性相符的書籤。

    • 項查詢

      字串 選用

      會與書籤網址和標題進行比對的一組字詞和加上引號的詞組。

    • title

      字串 選用

      書籤的標題；系統會逐字比對。

    • url

      字串 選用

      書籤的網址；系統會逐字比對。請注意，資料夾沒有網址，

  • 回呼

    函式選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[])=>void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

Promise 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

更新書籤或資料夾的屬性。僅指定您想變更的屬性；未指定的屬性將會保持不變。注意：目前僅支援「title」和「url」。

參數

  • id

    字串

  • 變更

    物件

    • title

      字串 選用

    • url

      字串 選用

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: BookmarkTreeNode)=>void

傳回

  • Chrome 90 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onChanged

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

書籤或資料夾變更時觸發。注意：目前只有標題和網址變更會觸發這項程序。

參數

  • 回呼

    功能

    callback 參數如下所示： 

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

    • id

      字串

    • changeInfo

      物件

      • title

        字串

      • url

        字串 選用

onChildrenReordered

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

當資料夾的子項因 UI 中的排序而變更順序時觸發。這個動作不會因 move() 的結果而呼叫。

參數

  • 回呼

    功能

    callback 參數如下所示： 

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

    • id

      字串

    • reorderInfo

      物件

      • childIds

        string[]

onCreated

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

建立書籤或資料夾時觸發。

參數

onImportBegan

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

書籤匯入工作階段開始時觸發。昂貴的觀察器應忽略 onCreated 更新，直到觸發 onImportEnded。觀察者仍應立即處理其他通知。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void

onImportEnded

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

書籤匯入工作階段結束時會觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void

onMoved

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

將書籤或資料夾移至其他上層資料夾時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

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

    • id

      字串

    • moveInfo

      物件

      • 索引

        號碼

      • oldIndex

        號碼

      • oldParentId

        字串

      • parentId

        字串

onRemoved

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

移除書籤或資料夾時觸發。以遞迴方式移除資料夾時，系統會觸發資料夾一次通知，但對於其內容不會觸發任何通知。

參數

  • 回呼

    功能

    callback 參數如下所示： 

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

    • id

      字串

    • removeInfo

      物件