browser.bookmarks

說明

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

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

權限

bookmarks

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

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

概念和用途

物件和屬性

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

BookmarkTreeNode 屬性會用於整個 browser.bookmarks API。舉例來說，呼叫 bookmarks.create 時，您會傳入新節點的父項 (parentId)，以及節點的 index、title 和 url 屬性 (選用)。如要瞭解節點可具備的屬性，請參閱 bookmarks.BookmarkTreeNode。

範例

下列程式碼會建立名為「Extension bookmarks」的資料夾。create() 的第一個引數會指定新資料夾的屬性。第二個引數定義了建立資料夾後要執行的函式。

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

下一個程式碼片段會建立書籤，指向擴充功能的開發人員說明文件。由於建立書籤失敗不會造成任何不良影響，因此這段程式碼不會定義回呼函式。

browser.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

    數字 選填

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

  • dateLastUsed

    數字 選填

    Chrome 114 以上版本 Chrome 148 以上版本為 browser.*

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

  • folderType

    FolderType 選填

    Chrome 134 以上版本 Chrome 148 起為 browser.*

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

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

  • id

    字串

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

  • 索引

    數字 選填

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

  • parentId

    字串 選填

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

  • 同步處理

    布林值

    Chrome 134 以上版本 Chrome 148 起為 browser.*

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

    注意：這反映了節點是否儲存到瀏覽器的內建帳戶提供者。即使這個值為 false，節點仍可能透過第三方同步。

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

  • title

    字串

    節點顯示的文字。

  • 無法修改

    "managed"
     選填

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

  • 網址

    字串 選填

    使用者點選書籤後前往的網址。資料夾會省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

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

值

"managed"

CreateDetails

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

屬性

  • 索引

    數字 選填

  • parentId

    字串 選填

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

  • title

    字串 選填

  • 網址

    字串 選填

FolderType

Chrome 134 以上版本 Chrome 148 起為 browser.*

表示資料夾類型。

列舉

"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 以上版本 Chrome 148 以上版本：browser.*

與根層級節點相關聯的 id。

值

"0"

方法

create()

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

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

參數

傳回

  • Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

get()

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

擷取指定的 BookmarkTreeNode。

參數

  • idOrIdList

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

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

傳回

  • <Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

getChildren()

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

擷取指定 BookmarkTreeNode ID 的子項。

參數

  • id

    字串

傳回

  • <Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

getRecent()

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

擷取最近新增的書籤。

參數

  • numberOfItems

    數字

    要傳回的項目數量上限。

傳回

  • <BookmarkTreeNode[]> 的 Promise

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

getSubTree()

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

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

參數

  • id

    字串

    要擷取的子樹根 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

    字串

  • 目的地

    物件

    • 索引

      數字 選填

    • parentId

      字串 選填

傳回

  • Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

remove()

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

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

參數

  • id

    字串

傳回

  • 承諾<void>

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

removeTree()

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

遞迴移除書籤資料夾。

參數

  • id

    字串

傳回

  • 承諾<void>

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起) 
browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

參數

  • 查詢

    string | object

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

    • 查詢

      字串 選填

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

    • title

      字串 選填

      書籤標題，必須完全相符。

    • 網址

      字串 選填

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

傳回

  • <Promise<BookmarkTreeNode[]>

    Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

update()

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

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

參數

  • id

    字串

  • 變更

    物件

    • title

      字串 選填

    • 網址

      字串 選填

傳回

  • Chrome 90 以上版本 瀏覽器 (自 Chrome 148 起)

事件

onChanged

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

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • id

      字串

    • changeInfo

      物件

      • title

        字串

      • 網址

        字串 選填

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

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

參數

onImportBegan

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

在書籤匯入工作階段開始時觸發。高成本觀察器應忽略 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

      物件

      • 索引

        數字

      • Chrome 48+ 瀏覽器。* 自 Chrome 148 起
      • parentId

        字串