chrome.bookmarks

說明

使用 chrome.bookmarks API 建立、整理及操作書籤。另請參閱覆寫頁面，瞭解如何建立自訂書籤管理工具頁面。

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

權限

bookmarks

如要使用書籤 API，必須在擴充功能資訊清單中聲明「bookmarks」權限。 例如：

{
  "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 存放區安裝 Bookmarks API 範例。

類型

BookmarkTreeNode

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

屬性

  • 孩子

    BookmarkTreeNode[] 選用

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

  • dateAdded

    號碼 選填

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

  • dateGroupModified

    號碼 選填

    這個資料夾的內容上次變更時間，以自記錄週期後的毫秒數表示。

  • dateLastUsed

    號碼 選填

    Chrome 114 以上版本

    上次開啟這個節點的時間，以從 Epoch 紀元時間算起的毫秒數表示。無法為資料夾設定。

  • folderType

    FolderType 選填

    Chrome 134 以上版本

    如果有的話，這個資料夾是由瀏覽器新增，使用者或擴充功能都無法修改。如果這個節點未設定 unmodifiable 屬性，子節點可能會遭到修改。如果節點可由使用者和擴充功能修改 (預設)，則會省略這項屬性。

    每個資料夾類型可能會有零個、一個或多個節點。資料夾可能會由瀏覽器新增或移除，但無法透過擴充功能 API 新增或移除。

  • id

    字串

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

  • 索引

    號碼 選填

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

  • parentId

    字串 選填

    上層資料夾的 id。根節點會省略這項資訊。

  • 同步處理中

    布林值

    Chrome 134 以上版本

    這個節點是否由瀏覽器與使用者的遠端帳戶儲存空間同步。這項功能可用於區分相同 FolderType 的帳戶和僅限本機版本。現有節點的這項屬性值可能會變更，例如使用者動作造成的結果。

    注意：這會反映節點是否已儲存至瀏覽器的內建帳戶供應商。即使這個值為 false，節點仍可能透過第三方同步處理。

    如果是受管理節點 (unmodifiable 設為 true 的節點)，這個屬性一律為 false。

  • title

    字串

    節點顯示的文字。

  • 無法修改

    「managed」
     選用

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

  • 網址

    字串 選填

    使用者點選書籤後前往的網址。資料夾則不適用。

BookmarkTreeNodeUnmodifiable

Chrome 44 以上版本

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

值

「managed」

CreateDetails

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

屬性

  • 索引

    號碼 選填

  • parentId

    字串 選填

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

  • title

    字串 選填

  • 網址

    字串 選填

FolderType

Chrome 134 以上版本

指出資料夾類型。

列舉

「bookmarks-bar」
內容顯示在瀏覽器視窗頂端的資料夾。

「其他」
：在所有平台上的完整書籤清單中顯示的書籤。

「mobile」
使用者行動裝置上通常會顯示書籤，但可透過擴充功能或書籤管理工具修改。

「已管理」
如果系統管理員或受監護使用者的監護人已設定書籤，則可能會顯示這個頂層資料夾。

屬性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

已淘汰

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

值

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

已淘汰

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

值

1000000

方法

create()

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

在指定 parentId 下建立書籤或資料夾。如果網址為 NULL 或遺失，則為資料夾。

參數

傳回

get()

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

擷取指定的 BookmarkTreeNode。

參數

  • idOrIdList

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

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

傳回

getChildren()

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

擷取指定 BookmarkTreeNode ID 的子項。

參數

  • id

    字串

傳回

getRecent()

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

擷取最近新增的書籤。

參數

  • numberOfItems

    數字

    傳回的項目數量上限。

傳回

getSubTree()

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

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

參數

  • id

    字串

    要擷取子樹狀結構根節點的 ID。

傳回

getTree()

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

擷取整個書籤階層。

傳回

move()

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

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

參數

  • id

    字串

  • 目的地

    物件

    • 索引

      號碼 選填

    • parentId

      字串 選填

傳回

remove()

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

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

參數

  • id

    字串

傳回

  • Promise<void>

    Chrome 90 以上版本

removeTree()

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

遞迴移除書籤資料夾。

參數

  • id

    字串

傳回

  • Promise<void>

    Chrome 90 以上版本 
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

參數

  • 查詢

    字串 | 物件

    可以是與書籤網址和標題相符的字串和引號括住的詞組，也可以是物件。如果是物件，則可指定 query、url 和 title 屬性，並產生與所有指定屬性相符的書籤。

    • 查詢

      字串 選填

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

    • title

      字串 選填

      書籤的標題，必須完全一致。

    • 網址

      字串 選填

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

傳回

update()

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

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

參數

  • id

    字串

  • 變更

    物件

    • title

      字串 選填

    • 網址

      字串 選填

傳回

事件

onChanged

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

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • id

      字串

    • changeInfo

      物件

      • title

        字串

      • 網址

        字串 選填

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

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

參數

onImportBegan

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

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

參數

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

移除書籤或資料夾時觸發。遞迴移除資料夾時，系統只會針對該資料夾觸發單一通知，不會針對其內容觸發通知。

參數

  • callback

    函式

    callback 參數如下： 

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

    • id

      字串

    • removeInfo

      物件