Nội dung mô tả
Sử dụng API chrome.bookmarks
để tạo, sắp xếp và chỉnh sửa dấu trang. Ngoài ra, hãy xem bài viết Ghi đè các trang mà bạn có thể sử dụng để tạo một trang Trình quản lý dấu trang tuỳ chỉnh.
![Thao tác nhấp vào dấu sao sẽ thêm dấu trang](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/bookmarks.png?authuser=5&hl=vi)
Quyền
bookmarks
Bạn phải khai báo quyền "dấu trang" trong tệp kê khai tiện ích để sử dụng API dấu trang. Ví dụ:
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
Khái niệm và cách sử dụng
Đối tượng và thuộc tính
Dấu trang được sắp xếp theo cây, trong đó mỗi nút trong cây là một dấu trang hoặc một thư mục (đôi khi gọi là một nhóm). Mỗi nút trong cây được biểu thị bằng một đối tượng bookmarks.BookmarkTreeNode.
Các thuộc tính BookmarkTreeNode
được dùng trên toàn bộ API chrome.bookmarks
. Ví dụ: khi gọi bookmarks.create, bạn sẽ truyền vào mẹ của nút mới (parentId
) cũng như các thuộc tính index
, title
và url
của nút (không bắt buộc). Vui lòng truy cập vào bookmarks.BookmarkTreeNode để biết thông tin về các thuộc tính mà một nút có thể có.
Ví dụ
Mã sau đây sẽ tạo một thư mục có tiêu đề "Dấu trang của phần mở rộng". Đối số đầu tiên của create()
chỉ định các thuộc tính cho thư mục mới. Đối số thứ hai xác định một hàm sẽ được thực thi sau khi tạo thư mục.
chrome.bookmarks.create(
{'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
},
);
Đoạn mã tiếp theo sẽ tạo một dấu trang trỏ đến tài liệu dành cho nhà phát triển về tiện ích. Vì không có gì xấu xảy ra nếu việc tạo dấu trang không thành công, mã này không bận tâm đến việc xác định hàm callback.
chrome.bookmarks.create({
'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'https://developer.chrome.com/docs/extensions',
});
Để dùng thử API này, hãy cài đặt Ví dụ về API Dấu trang trong kho lưu trữ chrome-extension-samples.
Loại
BookmarkTreeNode
Nút (dấu trang hoặc thư mục) trong cây dấu trang. Các nút con được sắp xếp theo thứ tự trong thư mục mẹ.
Thuộc tính
-
trẻ em
BookmarkTreeNode[] không bắt buộc
Danh sách các nút con cháu của nút này theo thứ tự.
-
dateAdded
số không bắt buộc
Thời điểm tạo nút này tính bằng mili giây kể từ thời gian bắt đầu của hệ thống (
new Date(dateAdded)
). -
dateGroupModified
số không bắt buộc
Thời điểm thay đổi nội dung của thư mục này lần gần đây nhất, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.
-
dateLastUsed
số không bắt buộc
Chrome 114 trở lênThời điểm nút này được mở lần gần đây nhất, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống. Chưa đặt cho thư mục.
-
id
string
Giá trị nhận dạng duy nhất của nút. Các mã nhận dạng là duy nhất trong hồ sơ hiện tại và vẫn hợp lệ ngay cả sau khi trình duyệt khởi động lại.
-
index
số không bắt buộc
Vị trí dựa trên 0 của nút này trong thư mục mẹ của nút.
-
parentId
chuỗi không bắt buộc
id
của thư mục mẹ. Đã bỏ qua đối với nút gốc. -
title
string
Văn bản hiển thị cho nút.
-
không thể sửa đổi
không bắt buộc
Cho biết lý do tại sao không thể sửa đổi nút này. Giá trị
managed
cho biết nút này đã được quản trị viên hệ thống hoặc người giám sát của người dùng được giám sát định cấu hình. Được bỏ qua nếu người dùng và tiện ích có thể sửa đổi nút (mặc định). -
url
chuỗi không bắt buộc
URL được điều hướng đến khi người dùng nhấp vào dấu trang. Đã bỏ qua đối với thư mục.
BookmarkTreeNodeUnmodifiable
Cho biết lý do tại sao không thể sửa đổi nút này. Giá trị managed
cho biết nút này đã được quản trị viên hệ thống định cấu hình. Được bỏ qua nếu người dùng và tiện ích có thể sửa đổi nút (mặc định).
Giá trị
CreateDetails
Đối tượng được truyền đến hàm create().
Thuộc tính
-
index
số không bắt buộc
-
parentId
chuỗi không bắt buộc
Giá trị mặc định là thư mục Dấu trang khác.
-
title
chuỗi không bắt buộc
-
url
chuỗi không bắt buộc
Thuộc tính
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Chrome không còn giới hạn các thao tác ghi dấu trang.
Giá trị
1000000
MAX_WRITE_OPERATIONS_PER_HOUR
Chrome không còn giới hạn các thao tác ghi dấu trang.
Giá trị
1000000
Phương thức
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
Tạo dấu trang hoặc thư mục theo mã nhận dạng mẹ đã chỉ định. Nếu url là giá trị NULL hoặc bị thiếu, thì URL đó sẽ là một thư mục.
Tham số
-
dấu trang
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: BookmarkTreeNode) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
Truy xuất(các) BookmarkTreeNode đã chỉ định.
Tham số
-
idOrIdList
chuỗi | [chuỗi, ...chuỗi[]]
Mã có giá trị chuỗi đơn hoặc một mảng mã nhận dạng có giá trị theo chuỗi
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
Truy xuất các phần tử con của mã BookmarkTreeNode đã chỉ định.
Tham số
-
id
string
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
Truy xuất dấu trang đã thêm gần đây.
Tham số
-
numberOfItems
number
Số lượng mục tối đa cần trả lại.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
Truy xuất một phần của Hệ phân cấp dấu trang, bắt đầu từ nút đã chỉ định.
Tham số
-
id
string
Mã gốc của cây con cần truy xuất.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
Truy xuất toàn bộ hệ phân cấp Dấu trang.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
Di chuyển BookmarkTreeNode được chỉ định đến vị trí được cung cấp.
Tham số
-
id
string
-
tài khoản đích
đối tượng
-
index
số không bắt buộc
-
parentId
chuỗi không bắt buộc
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: BookmarkTreeNode) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
Xoá dấu trang hoặc thư mục dấu trang trống.
Tham số
-
id
string
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
Xoá thư mục dấu trang theo quy tắc đệ quy.
Tham số
-
id
string
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
Tìm kiếm BookmarkTreeNodes khớp với truy vấn đã cho. Các truy vấn được chỉ định với một đối tượng sẽ tạo PagingTreeNodes phù hợp với tất cả các thuộc tính được chỉ định.
Tham số
-
query
chuỗi | đối tượng
Một chuỗi từ và cụm từ được trích dẫn được so khớp với URL và tiêu đề dấu trang hoặc một đối tượng. Nếu là một đối tượng, thì các thuộc tính
query
,url
vàtitle
có thể được chỉ định và dấu trang phù hợp với tất cả thuộc tính đã chỉ định sẽ được tạo.-
query
chuỗi không bắt buộc
Một chuỗi từ và cụm từ được trích dẫn được so khớp với tiêu đề và URL dấu trang.
-
title
chuỗi không bắt buộc
Tiêu đề của dấu trang; khớp nguyên văn.
-
url
chuỗi không bắt buộc
URL của dấu trang; khớp nguyên văn. Xin lưu ý rằng thư mục không có URL.
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: BookmarkTreeNode[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
Cập nhật các thuộc tính của dấu trang hoặc thư mục. Chỉ chỉ định các thuộc tính mà bạn muốn thay đổi; các thuộc tính chưa chỉ định sẽ được giữ nguyên. Lưu ý: Hiện tại, chỉ hỗ trợ "title" (tiêu đề) và "url".
Tham số
-
id
string
-
các thay đổi
đối tượng
-
title
chuỗi không bắt buộc
-
url
chuỗi không bắt buộc
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: BookmarkTreeNode) => void
-
kết quả
-
Giá trị trả về
-
Promise<BookmarkTreeNode>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
Sự kiện
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
Được kích hoạt khi dấu trang hoặc thư mục thay đổi. Lưu ý: Hiện tại, chỉ các thay đổi về tiêu đề và URL mới kích hoạt điều này.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(id: string, changeInfo: object) => void
-
id
string
-
changeInfo
đối tượng
-
title
string
-
url
chuỗi không bắt buộc
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
Được kích hoạt khi các phần tử con của một thư mục thay đổi thứ tự do thứ tự được sắp xếp trong giao diện người dùng. Thao tác này không được gọi là kết quả của lệnh Move().
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(id: string, reorderInfo: object) => void
-
id
string
-
reorderInfo
đối tượng
-
childIds
chuỗi[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
Được kích hoạt khi dấu trang hoặc thư mục được tạo.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(id: string, bookmark: BookmarkTreeNode) => void
-
id
string
-
dấu trang
-
onImportBegan
chrome.bookmarks.onImportBegan.addListener(
callback: function,
)
Được kích hoạt khi phiên nhập dấu trang bắt đầu. Trình quan sát tốn nhiều tài nguyên nên bỏ qua các bản cập nhật onCreated cho đến khi onImportConnection được kích hoạt. Đối tượng tiếp nhận dữ liệu vẫn sẽ xử lý các thông báo khác ngay lập tức.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onImportEnded
chrome.bookmarks.onImportEnded.addListener(
callback: function,
)
Được kích hoạt khi phiên nhập dấu trang kết thúc.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onMoved
chrome.bookmarks.onMoved.addListener(
callback: function,
)
Được kích hoạt khi dấu trang hoặc thư mục được di chuyển đến một thư mục mẹ khác.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(id: string, moveInfo: object) => void
-
id
string
-
moveInfo
đối tượng
-
index
number
-
oldIndex
number
-
oldParentId
string
-
parentId
string
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
Được kích hoạt khi dấu trang hoặc thư mục bị xóa. Khi một thư mục bị xoá theo quy tắc đệ quy, một thông báo duy nhất được kích hoạt cho thư mục và không có thông báo nào cho nội dung của thư mục.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(id: string, removeInfo: object) => void
-
id
string
-
removeInfo
đối tượng
-
index
number
-
nútChrome 48 trở lên
-
parentId
string
-
-