這項權限會觸發警告。
說明
使用 chrome.bookmarks
API 建立、整理及控制書籤。此外,您也可以參閱「覆寫網頁」,以便建立自訂書籤管理員頁面。
權限
bookmarks
資訊清單
您必須在擴充功能資訊清單中宣告「書籤」權限,才能使用書籤 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 範例。
類型
BookmarkTreeNode
書籤樹狀結構中的節點 (書籤或資料夾)。子項節點會在上層資料夾中排序。
屬性
-
孩子
BookmarkTreeNode[] 選用
這個節點的子項已排序清單。
-
dateAdded
數字 選填
這個節點的建立時間,以 Epoch 紀元時間 (
new Date(dateAdded)
) 起算的毫秒為單位。 -
dateGroupModified
數字 選填
這個資料夾的內容上次變更時 (自 Epoch 紀元時間起算,以毫秒為單位)。
-
dateLastUsed
數字 選填
Chrome 114 以上版本這個節點的上次開啟時間 (以 Epoch 紀元時間起算的毫秒為單位)。未設定資料夾。
-
id
字串
節點的專屬 ID。ID 是目前設定檔中的唯一識別碼,即使瀏覽器重新啟動後,ID 也依然有效。
-
索引
數字 選填
這個節點在其上層資料夾內的位置 (從 0 開始)。
-
parentId
字串 選用
父項資料夾的
id
。如為根節點,則會省略。 -
title
字串
節點顯示的文字。
-
無法修改
選用
指出這個節點無法修改的原因。
managed
值代表這個節點是由系統管理員或受監管使用者的保管人設定。如果使用者和擴充功能可修改節點,則可省略這個欄位 (預設)。 -
網址
字串 選用
使用者點按書籤後前往的網址。如為資料夾,則不用勾選。
BookmarkTreeNodeUnmodifiable
指出這個節點無法修改的原因。managed
值表示系統管理員已設定這個節點。如果使用者和擴充功能可修改節點,則可省略這個欄位 (預設)。
值
CreateDetails
傳遞至 create() 函式的物件。
屬性
-
索引
數字 選填
-
parentId
字串 選用
預設值為「其他書籤」資料夾。
-
title
字串 選用
-
網址
字串 選用
屬性
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Chrome 不再限制書籤寫入作業。
值
1000000
MAX_WRITE_OPERATIONS_PER_HOUR
Chrome 不再限制書籤寫入作業。
值
1000000
方法
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
在指定 parentId 下建立書籤或資料夾。如果網址為 NULL 或缺少網址,就會成為資料夾。
參數
-
回呼
函式選用
callback
參數如下所示:(result: BookmarkTreeNode) => void
傳回
-
Promise<BookmarkTreeNode>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
擷取指定的 bookmarkTreeNode。
參數
-
idOrIdList
string | [string, ...string[]]
單一字串值 ID,或字串值 ID
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
擷取指定 bookmarkTreeNode ID 的子項。
參數
-
id
字串
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
擷取最近新增的書籤。
參數
-
numberOfItems
號碼
傳回的項目數量上限。
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
從指定的節點擷取部分書籤階層。
參數
-
id
字串
要擷取的子樹狀結構根層級 ID。
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
擷取整個書籤階層。
參數
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
將指定的 bookmarkTreeNode 移至提供的位置。
參數
-
id
字串
-
目的地
物件
-
索引
數字 選填
-
parentId
字串 選用
-
-
回呼
函式選用
callback
參數如下所示:(result: BookmarkTreeNode) => void
傳回
-
Promise<BookmarkTreeNode>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
移除書籤或空白書籤資料夾。
參數
-
id
字串
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
以遞迴方式移除書籤資料夾。
參數
-
id
字串
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
搜尋符合指定查詢的 bookmarkTreeNodes。以物件指定的查詢會產生符合所有指定屬性的 bookmarkTreeNodes。
參數
-
項查詢
string | object
與書籤網址和標題或物件進行比對的單字或引用詞組。如果物件可指定
query
、url
和title
屬性,則可指定與所有指定屬性相符的書籤。-
項查詢
字串 選用
會與書籤網址和標題進行比對的一組字詞和加上引號的詞組。
-
title
字串 選用
書籤的標題;系統會逐字比對。
-
網址
字串 選用
書籤的網址;系統會逐字比對。請注意,資料夾沒有網址,
-
-
回呼
函式選用
callback
參數如下所示:(results: BookmarkTreeNode[]) => void
-
結果
-
傳回
-
Promise<BookmarkTreeNode[]>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
更新書籤或資料夾的屬性。僅指定您想變更的屬性;未指定的屬性將會保持不變。注意:目前僅支援「title」和「url」。
參數
-
id
字串
-
變更
物件
-
title
字串 選用
-
網址
字串 選用
-
-
回呼
函式選用
callback
參數如下所示:(result: BookmarkTreeNode) => void
傳回
-
Promise<BookmarkTreeNode>
Chrome 90 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
書籤或資料夾變更時觸發。注意:目前只有標題和網址變更會觸發這項程序。
參數
-
回呼
功能
callback
參數如下所示:(id: string, changeInfo: object) => void
-
id
字串
-
changeInfo
物件
-
title
字串
-
網址
字串 選用
-
-
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
字串
-
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
物件
-
索引
號碼
-
Chrome 48 以上版本
-
parentId
字串
-
-