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.

Nhấp vào dấu sao để thêm dấu trang
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à các thuộc tính index, title và url của nút (không bắt buộc). 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ó.

Ví dụ

Mã sau đây sẽ 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.

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

  • 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

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.

Tham số

Giá trị trả về

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

Tham số

  • idOrIdList

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

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

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.

Tham 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

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.

Tham 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

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 đã chỉ định.

Tham 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

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.

Tham số

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.

Tham 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

Giá trị trả về

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

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

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

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.

Tham 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

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

Tham 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

Giá trị trả về

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

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

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

Tham số

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.

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

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

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

Tham 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