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。

範例

以下程式碼會建立標題為「Extension bookmarks」的資料夾。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 存放區安裝Bookmarks API 範例。

類型

BookmarkTreeNode

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

屬性

  • 孩子

    BookmarkTreeNode[] 選填

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

  • dateAdded

    號碼 選填

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

  • dateGroupModified

    號碼 選填

    這個資料夾上次變更的時間，自紀元紀元後的毫秒數。

  • dateLastUsed

    號碼 選填

    Chrome 114 以上版本

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

  • id

    字串

    節點的專屬 ID。ID 在目前的設定檔中是唯一的，即使瀏覽器重新啟動，仍會保持有效。

  • 索引

    號碼 選填

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

  • parentId

    string 選填

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

  • title

    字串

    節點顯示的文字。

  • 無法修改

    "managed"
     選填

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

  • 網址

    string 選填

    使用者按下書籤後會導向的網址。資料夾則省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 以上版本

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

值

「managed」

CreateDetails

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

屬性

  • 索引

    號碼 選填

  • parentId

    string 選填

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

  • title

    string 選填

  • 網址

    string 選填

屬性

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 下建立書籤或資料夾。如果網址為空值或遺失，則會是資料夾。

參數

傳回

  • Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

get()

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

擷取指定的 BookmarkTreeNode。

參數

  • idOrIdList

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

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getChildren()

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

擷取指定 BookmarkTreeNode ID 的子項。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getRecent()

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

擷取最近新增的書籤。

參數

  • numberOfItems

    數字

    傳回的項目數量上限。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getSubTree()

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

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

參數

  • id

    字串

    要擷取的子樹根目錄 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getTree()

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

擷取整個書籤階層。

參數

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

move()

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

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

參數

  • id

    字串

  • 目的地

    物件

    • 索引

      號碼 選填

    • parentId

      string 選填

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: BookmarkTreeNode) => void

傳回

  • Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

remove()

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

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

參數

  • id

    字串

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

removeTree()

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

遞迴移除書籤資料夾。

參數

  • id

    字串

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

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

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

參數

  • 查詢

    字串 | 物件

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

    • 查詢

      string 選填

      字串字詞和引號詞組，用於比對書籤網址和標題。

    • title

      string 選填

      書籤的標題，完全比對。

    • 網址

      string 選填

      書籤的網址，必須與原文完全相符。請注意，資料夾沒有網址。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (results: BookmarkTreeNode[]) => void

傳回

  • Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

update()

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

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

參數

  • id

    字串

  • 變更

    物件

    • title

      string 選填

    • 網址

      string 選填

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: BookmarkTreeNode) => void

傳回

  • Chrome 90 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • id

      字串

    • changeInfo

      物件

      • title

        字串

      • 網址

        string 選填

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,
)

在書籤匯入工作階段開始時觸發。在 onImportEnded 觸發之前，高成本的觀察器應忽略 onCreated 更新。觀察器仍應立即處理其他通知。

參數

  • 回呼

    函式

    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

      物件