本頁面由 Cloud Translation API 翻譯而成。

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

參數

書籤

CreateDetails
回呼

函式選填

callback 參數如下所示：
```
(result: BookmarkTreeNode) => void
```
- 結果
  
  BookmarkTreeNode

傳回

Promise<BookmarkTreeNode>

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
```
- 結果
  
  BookmarkTreeNode[]

傳回

Promise<BookmarkTreeNode[]>

Chrome 90 以上版本

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

getChildren()

Promise

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

擷取指定 BookmarkTreeNode ID 的子項。

參數

id

字串
回呼

函式選填

callback 參數如下所示：
```
(results: BookmarkTreeNode[]) => void
```
- 結果
  
  BookmarkTreeNode[]

傳回

Promise<BookmarkTreeNode[]>

Chrome 90 以上版本

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

getRecent()

Promise

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

擷取最近新增的書籤。

參數

numberOfItems

數字

傳回的項目數量上限。
回呼

函式選填

callback 參數如下所示：
```
(results: BookmarkTreeNode[]) => void
```
- 結果
  
  BookmarkTreeNode[]

傳回

Promise<BookmarkTreeNode[]>

Chrome 90 以上版本

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

getSubTree()

Promise

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

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

參數

id

字串

要擷取的子樹根目錄 ID。
回呼

函式選填

callback 參數如下所示：
```
(results: BookmarkTreeNode[]) => void
```
- 結果
  
  BookmarkTreeNode[]

傳回

Promise<BookmarkTreeNode[]>

Chrome 90 以上版本

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

getTree()

Promise

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

擷取整個書籤階層。

參數

回呼

函式選填

callback 參數如下所示：
```
(results: BookmarkTreeNode[]) => void
```
- 結果
  
  BookmarkTreeNode[]

傳回

Promise<BookmarkTreeNode[]>

Chrome 90 以上版本

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

move()

Promise

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

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

參數

id

字串
目的地

物件
- 索引
  
  號碼選填
- parentId
  
  string 選填
回呼

函式選填

callback 參數如下所示：
```
(result: BookmarkTreeNode) => void
```
- 結果
  
  BookmarkTreeNode

傳回

Promise<BookmarkTreeNode>

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

search()

Promise

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

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

參數

查詢

字串 | 物件

字串字詞和引號詞組，可與書籤網址和標題比對，或是一個物件。如果是物件，則可指定 query、url 和 title 屬性，系統會產生與所有指定屬性相符的書籤。
- 查詢
  
  string 選填
  
  字串字詞和引號詞組，用於比對書籤網址和標題。
- title
  
  string 選填
  
  書籤的標題，完全比對。
- 網址
  
  string 選填
  
  書籤的網址，必須與原文完全相符。請注意，資料夾沒有網址。
回呼

函式選填

callback 參數如下所示：
```
(results: BookmarkTreeNode[]) => void
```
- 結果
  
  BookmarkTreeNode[]

傳回

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
```
- 結果
  
  BookmarkTreeNode

傳回

Promise<BookmarkTreeNode>

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

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

參數

回呼

函式

callback 參數如下所示：
```
(id: string, bookmark: BookmarkTreeNode) => void
```
- id
  
  字串
- 書籤
  
  BookmarkTreeNode

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
  
  物件
  - 索引
    
    數字
  - 節點
    
    BookmarkTreeNode
    
    Chrome 48 以上版本
  - parentId
    
    字串