chrome.bookmarks

Mô tả

Dùng API chrome.bookmarks để tạo, sắp xếp và thao tác với dấu trang. Ngoài ra, hãy xem phần Ghi đè trang mà bạn có thể sử dụng để tạo trang Trình quản lý dấu trang tuỳ chỉnh.

Nhấp vào dấu sao sẽ thêm dấu trang.

Quyền

bookmarks

Bạn phải khai báo "dấu trang" quyền 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 đượ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 trên toàn bộ API chrome.bookmarks. Ví dụ: khi bạn gọi bookmarks.create, bạn sẽ chuyển vào phần tử mẹ của nút mới (parentId) và nếu muố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á "Thanh dấu trang" đặc biệt và "Dấu trang khác" thư mục.

Ví dụ

Đoạn mã sau đây sẽ tạo một thư mục có tiêu đề "Dấu trang của 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 cần đượ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ề các tiện ích. Từ sẽ không có gì 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 chrome-extension-samples kho lưu trữ.

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 phần tử con được sắp xếp theo thứ tự của nút này.

• dateAdded

  số không bắt buộc

  Thời điểm nút này được tạo, 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 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ê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. Chưa được đặt cho thư mục.

• id

  string

  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ẹ của nút này.

• parentId

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

  id của thư mục mẹ. Được bỏ qua cho nút gốc.

• tiêu đề

  string

  Văn bản được 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 tại sao nút này không thể sửa đổi. Giá trị managed cho biết rằng nút này do quản trị viên hệ thống hoặc người giám hộ của một 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 này (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 tại sao nút này không thể sửa đổi. 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 này (mặc định).

Giá trị

"được 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

  Giá trị 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

Thuộc tính

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Không dùng nữa

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

Không dùng nữa

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

Lời hứa

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

Tạo một dấu trang hoặc thư mục theo mã nhận dạng chính (parentId) đã chỉ định. Nếu url bị thiếu hoặc có giá trị NULL, thì đó sẽ là một thư mục.

Tham số

• dấu trang

  CreateDetails

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

    BookmarkTreeNode

Giá trị trả về

• Promise<BookmarkTreeNode>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

get()

Lời hứa

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

Truy xuất(các) BookmarktreeNode được chỉ định.

Tham số

• idOrIdList

  string | [chuỗi, ...chuỗi[]]

  Một mã nhận dạng có giá trị bằng một chuỗi hoặc một mảng mã nhận dạng có giá trị dạng 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ả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getChildren()

Lời hứa

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

Truy xuất các phần tử con của mã BookmarkTreeNode được 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ả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getRecent()

Lời hứa

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

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

Tham số

• numberOfItems

  số

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

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

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getSubTree()

Lời hứa

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 được 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ả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getTree()

Lời hứa

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ả

    BookmarkTreeNode[]

Giá trị trả về

• Promise<BookmarkTreeNode[]>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

move()

Lời hứa

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

Di chuyển BookmarkTreeNode được chỉ định đến vị trí đã 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ả

    BookmarkTreeNode

Giá trị trả về

• Promise<BookmarkTreeNode>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

remove()

Lời hứa

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ề

• Lời hứa<vô hiệu>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

removeTree()

Lời hứa

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

Xoá thư mục dấu trang theo định kỳ.

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ề

• Lời hứa<vô hiệu>

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

search()

Lời hứa

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

Các lượt tìm kiếm BookmarkTreeNodes phù hợ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 ra BookmarkTreeNodes phù hợp với tất cả các thuộc tính đã chỉ định.

Tham số

• truy vấn

  string | đối tượng

  Một chuỗi từ và cụm từ trong dấu ngoặc kép 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, các thuộc tính query, url và title có thể được chỉ định và 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ó dấu ngoặc kép 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 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. 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ả

    BookmarkTreeNode[]

Giá trị trả về

• Promise&lt;BookmarkTreeNode[]&gt;

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

update()

Lời hứa

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ỉ xác định những thuộc tính mà bạn muốn thay đổi; các thuộc tính chưa xác định sẽ không thay đổi. Lưu ý: Hiện tại, chỉ có "title" và "url" được hỗ trợ.

Tham số

• id

  string

• 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

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

    BookmarkTreeNode

Giá trị trả về

• Promise&lt;BookmarkTreeNode&gt;

  Chrome 90 trở lên

  Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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ỉ những thay đổi đối với tiêu đề và URL mới kích hoạt việc 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

    • tiêu đề

      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 thành phần 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. Lệnh này không được gọi do di chuyển().

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

    BookmarkTreeNode

onImportBegan

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

Được kích hoạt khi phiên nhập dấu trang bắt đầu. 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 onImportKết thúc được kích hoạt. Đối tượng tiếp nhận dữ liệu vẫn cần 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 sang 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

      số

    • oldIndex

      số

    • 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 bạn xoá một thư mục theo quy tắc đệ quy, một thông báo sẽ được kích hoạt cho thư mục đó nhưng không có thông báo nào cho nội dung trong 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

      số

    • nút

      BookmarkTreeNode

      Chrome 48 trở lên
    • parentId

      string