chrome.bookmarks

Mô tả

Sử dụng API chrome.bookmarks để tạo, sắp xếp và thao tác với các dấu trang. Ngoài ra, hãy xem phần Ghi đè trang để tạo 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 một dấu trang.

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

Các dấu trang được sắp xếp theo dạng 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 được gọi là 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 sử dụng trong toàn bộ API chrome.bookmarks. Ví dụ: khi gọi bookmarks.create, bạn sẽ truyền vào phần tử mẹ của nút mới (parentId) và tuỳ ý truyền các thuộc tính index, title và url của nút. Hãy xem bookmarks.BookmarkTreeNode để biết thông tin về các thuộc tính mà một nút có thể có.

Lưu ý: Bạn không thể sử dụng API này để thêm hoặc xoá các mục trong thư mục gốc. Bạn cũng không thể đổi tên, di chuyển hoặc xoá các thư mục đặc biệt "Bookmarks Bar" (Thanh dấu trang) và "Other Bookmarks" (Dấu trang khác).

Ví dụ

Mã sau đây tạo một thư mục có tiêu đề "Dấu trang tiện ích". Đối số đầu tiên cho 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 thư mục được tạo.

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ề các tiện ích. Vì không có điều gì xảy ra nếu không tạo được dấu trang, nên mã này không cần xác định hàm gọi lại.

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 Đánh dấu từ kho lưu trữ chrome-extension-samples.

Loại

BookmarkTreeNode

Một 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 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 theo thứ tự của nút này.

• 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 nội dung của thư mục này thay đổi 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ên

  Lần gần đây nhất nút này được mở, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống. Không được đặt cho thư mục.

• folderType

  FolderType không bắt buộc

  Đang chờ xử lý

  Nếu có, đây là thư mục do trình duyệt thêm và người dùng hoặc tiện ích không thể sửa đổi thư mục này. Bạn có thể sửa đổi các nút con nếu nút này không có thuộc tính unmodifiable. Bỏ qua nếu người dùng và tiện ích có thể sửa đổi nút (mặc định).

  Có thể không có, một hoặc nhiều nút của mỗi loại thư mục. Trình duyệt có thể thêm hoặc xoá thư mục, nhưng không thể thực hiện việc này thông qua API tiện ích.

• id

  chuỗi

  Giá trị nhận dạng duy nhất của nút. 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 khởi động lại trình duyệt.

• 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ẹ.

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

• đang đồng bộ hoá

  boolean

  Đang chờ xử lý

  Liệu trình duyệt có đồng bộ hoá nút này với bộ nhớ tài khoản từ xa của người dùng hay không. Bạn có thể dùng thuộc tính này để phân biệt giữa phiên bản tài khoản và phiên bản chỉ dành cho máy tính của cùng một FolderType. Giá trị của thuộc tính này có thể thay đổi đối với một nút hiện có, chẳng hạn như do hành động của người dùng.

  Lưu ý: giá trị này cho biết liệu nút có được lưu vào nhà cung cấp tài khoản tích hợp sẵn của trình duyệt hay không. Có thể một nút có thể được đồng bộ hoá thông qua bên thứ ba, ngay cả khi giá trị này là sai.

  Đối với các nút được quản lý (nút mà unmodifiable được đặt thành true), thuộc tính này sẽ luôn là false.

• tiêu đề

  chuỗi

  Văn bản hiển thị cho nút.

• không thể sửa đổi

  "được quản lý"
   không bắt buộc

  Cho biết lý do khiến nút này không thể sửa đổi. Giá trị managed cho biết nút này do quản trị viên hệ thống hoặc người giám hộ của người dùng được giám sát thiết lập. 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 chuyển đến khi người dùng nhấp vào dấu trang. Bỏ qua đối với thư mục.

BookmarkTreeNodeUnmodifiable

Chrome 44 trở lên

Cho biết lý do khiến nút này không thể sửa đổi. Giá trị managed cho biết nút này do quản trị viên hệ thống định cấu hình. Bỏ qua nếu người dùng và tiện ích có thể sửa đổi nút (mặc định).

Giá trị

"đã quản lý"

CreateDetails

Đối tượng được truyền vào hàm create().

Thuộc tính

• index

  số không bắt buộc

• parentId

  chuỗi không bắt buộc

  Theo mặc định là thư mục Dấu trang khác.

• tiêu đề

  chuỗi không bắt buộc

• url

  chuỗi không bắt buộc

FolderType

Đang chờ xử lý

Cho biết loại thư mục.

Enum

"bookmarks-bar"
Thư mục có nội dung hiển thị ở đầu cửa sổ trình duyệt.

"other" (Khác)
Dấu trang xuất hiện trong danh sách đầy đủ các dấu trang trên tất cả nền tảng.

"mobile"
Dấu trang thường có trên thiết bị di động của người dùng, nhưng có thể sửa đổi bằng tiện ích hoặc trong trình quản lý dấu trang.

"được quản lý"
Một thư mục cấp cao nhất có thể xuất hiện nếu quản trị viên hệ thống hoặc người giám hộ của người dùng được giám sát đã định cấu hình dấu trang.

Thuộc tính

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Không dùng nữa

Các thao tác ghi dấu trang không còn bị Chrome giới hạn.

Giá trị

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Không dùng nữa

Các thao tác ghi dấu trang không còn bị Chrome giới hạn.

Giá trị

1000000

Phương thức

create()

Promise

chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Tạo một dấu trang hoặc thư mục trong parentId đã chỉ định. Nếu url là NULL hoặc bị thiếu, thì đó sẽ là một thư mục.

Thông số

• dấu trang

  CreateDetails

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (result: BookmarkTreeNode) => void

  • kết quả

    BookmarkTreeNode

Giá trị trả về

• Promise<BookmarkTreeNode>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

get()

Promise

chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

Truy xuất(các) BookmarkTreeNode đã chỉ định.

Thông số

• idOrIdList

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

  Một mã nhận dạng có giá trị chuỗi hoặc một mảng mã nhận dạng có giá trị chuỗi

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getChildren()

Promise

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

Truy xuất các phần tử con của mã BookmarkTreeNode đã chỉ định.

Thông số

• id

  chuỗi

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getRecent()

Promise

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

Truy xuất các dấu trang được thêm gần đây.

Thông số

• numberOfItems

  số

  Số lượng mục tối đa cần trả về.

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getSubTree()

Promise

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

Truy xuất một phần của hệ phân cấp Đánh dấu, bắt đầu từ nút được chỉ định.

Thông số

• id

  chuỗi

  Mã nhận dạng của gốc của cây con cần truy xuất.

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getTree()

Promise

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

Truy xuất toàn bộ hệ phân cấp Dấu trang.

Thông số

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

move()

Promise

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

Di chuyển BookmarkTreeNode đã chỉ định đến vị trí đã cung cấp.

Thông số

• id

  chuỗi

• 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

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (result: BookmarkTreeNode) => void

  • kết quả

    BookmarkTreeNode

Giá trị trả về

• Promise<BookmarkTreeNode>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

remove()

Promise

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

Xoá một dấu trang hoặc thư mục dấu trang trống.

Thông số

• id

  chuỗi

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  () => void

Giá trị trả về

• Promise<void>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

removeTree()

Promise

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

Xoá thư mục dấu trang theo đệ quy.

Thông số

• id

  chuỗi

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  () => void

Giá trị trả về

• Promise<void>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

search()

Promise

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 bằng một đối tượng sẽ tạo ra BookmarkTreeNodes khớp với tất cả các thuộc tính được chỉ định.

Thông số

• truy vấn

  chuỗi | đối tượng

  Một chuỗi từ và cụm từ trích dẫn được so khớp với URL và tiêu đề của dấu trang hoặc một đối tượng. Nếu là đối tượng, bạn có thể chỉ định các thuộc tính query, url và title và các dấu trang khớp với tất cả thuộc tính đã chỉ định sẽ được tạo.

  • truy vấn

    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 URL và tiêu đề của dấu trang.

  • tiêu đề

    chuỗi không bắt buộc

    Tiêu đề của dấu trang; khớp chính xác.

  • url

    chuỗi không bắt buộc

    URL của dấu trang; khớp chính xác. Xin lưu ý rằng thư mục không có URL.

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (results: BookmarkTreeNode[]) => void

  • kết quả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

update()

Promise

chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Cập nhật các thuộc tính của một dấu trang hoặc thư mục. Chỉ chỉ định những thuộc tính mà bạn muốn thay đổi; các thuộc tính không được chỉ định sẽ không thay đổi. Lưu ý: Hiện tại, chúng tôi chỉ hỗ trợ "tiêu đề" và "url".

Thông số

• id

  chuỗi

• các thay đổi

  đối tượng

  • tiêu đề

    chuỗi không bắt buộc

  • url

    chuỗi không bắt buộc

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (result: BookmarkTreeNode) => void

  • kết quả

    BookmarkTreeNode

Giá trị trả về

• Promise<BookmarkTreeNode>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ 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 một dấu trang hoặc thư mục thay đổi. Lưu ý: Hiện tại, chỉ những thay đổi về tiêu đề và URL mới kích hoạt việc này.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

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

  • id

    chuỗi

  • changeInfo

    đối tượng

    • tiêu đề

      chuỗi

    • url

      chuỗi không bắt buộc

onChildrenReordered

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

Được kích hoạt khi các thư mục 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. Phương thức này không được gọi do một move().

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

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

  • id

    chuỗi

  • reorderInfo

    đối tượng

    • childIds

      string[]

onCreated

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

Được kích hoạt khi tạo một dấu trang hoặc thư mục.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

  (id: string, bookmark: BookmarkTreeNode) => void

  • id

    chuỗi

  • dấu trang

    BookmarkTreeNode

onImportBegan

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

Được kích hoạt khi bắt đầu một phiên nhập dấu trang. Các trình quan sát tốn kém nên bỏ qua các bản cập nhật onCreated cho đến khi onImportEnded được kích hoạt. Trình quan sát vẫn phải xử lý ngay các thông báo khác.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback 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.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

  () => void

onMoved

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

Được kích hoạt khi một dấu trang hoặc thư mục được di chuyển sang một thư mục mẹ khác.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

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

  • id

    chuỗi

  • moveInfo

    đối tượng

    • index

      số

    • oldIndex

      số

    • oldParentId

      chuỗi

    • parentId

      chuỗi

onRemoved

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

Được kích hoạt khi một dấu trang hoặc thư mục bị xoá. Khi một thư mục bị xoá đệ quy, một thông báo sẽ đượ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.

Thông số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

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

  • id

    chuỗi

  • removeInfo

    đối tượng

    • index

      số

    • nút

      BookmarkTreeNode

      Chrome 48 trở lên
    • parentId

      chuỗi