chrome.bookmarks

這項權限會觸發警告。

說明

使用 chrome.bookmarks API 建立、整理或控制書籤。另請參閱覆寫網頁，瞭解如何建立自訂書籤管理員頁面。

權限

bookmarks

按一下星號圖示

資訊清單

您必須宣告「書籤」擴充功能資訊清單中所列的權限，即可使用 bookmark 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 範例 Cloud Storage 也提供目錄同步處理功能

類型

BookmarkTreeNode

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

屬性

  • 孩子

    BookmarkTreeNode[] 選用

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

  • dateAdded

    編號 選填

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

  • dateGroupModified

    編號 選填

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

  • dateLastUsed

    編號 選填

    Chrome 114 以上版本

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

  • id

    字串

    節點的專屬 ID。ID 在目前設定檔中不能重複，即使重新啟動瀏覽器後仍然有效。

  • 索引

    編號 選填

    這個節點在上層資料夾中的 0 位置。

  • parentId

    string optional

    父項資料夾的 id。根節點省略。

  • title

    字串

    顯示的節點文字。

  • 無法修改

    "managed"
     選用

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

  • 網址

    string optional

    使用者點選書籤後前往的網址。如無資料夾，則省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 以上版本

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

值

"managed"

CreateDetails

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

屬性

  • 索引

    編號 選填

  • parentId

    string optional

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

  • title

    string optional

  • 網址

    string optional

屬性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

已淘汰

Chrome 不再支援書籤寫入作業。

值

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

已淘汰

Chrome 不再支援書籤寫入作業。

值

1000000

方法

create()

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

在指定父項 ID 下建立書籤或資料夾。如果網址為 NULL 或缺少網址，表示這是資料夾。

參數

傳回

  • Promise<BookmarkTreeNode>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

get()

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

擷取指定的 bookmarkTreeNode。

參數

  • idOrIdList

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

    單一字串值 ID，或字串值 ID 的陣列

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getChildren()

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

擷取指定 bookmarkTreeNode ID 的子項。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getRecent()

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

擷取最近新增的書籤。

參數

  • numberOfItems

    數字

    傳回的項目數量上限。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getSubTree()

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

擷取部分書籤階層 (從指定的節點開始)。

參數

  • id

    字串

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getTree()

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

擷取整個書籤階層。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

move()

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

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

參數

  • id

    字串

  • 目的地

    物件

    • 索引

      編號 選填

    • parentId

      string optional

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (result: BookmarkTreeNode) => void

傳回

  • Promise<BookmarkTreeNode>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

remove()

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

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

參數

  • id

    字串

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

removeTree()

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

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

參數

  • id

    字串

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

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

搜尋符合指定查詢的 bookmarkTreeNode。使用物件指定的查詢會產生符合所有指定屬性的 bookmarkTreeNode。

參數

  • 查詢

    string |物體

    可能是與書籤網址和標題相符的字串及加引號的詞組，或是特定物件。如果物件為物件，系統可能會指定 query、url 和 title 屬性，產生與所有指定屬性相符的書籤。

    • 查詢

      string optional

      與書籤網址和標題比對的字詞字串及加引號的詞組。

    • title

      string optional

      書籤的標題；會完全相符

    • 網址

      string optional

      書籤的網址；會完全相符請注意，資料夾則沒有網址。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

update()

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

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

參數

  • id

    字串

  • 變更

    物件

    • title

      string optional

    • 網址

      string optional

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (result: BookmarkTreeNode) => void

傳回

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • id

      字串

    • changeInfo

      物件

      • title

        字串

      • 網址

        string optional

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

      物件