chrome.history

Mô tả

Dùng API chrome.history để tương tác với bản ghi của trình duyệt về các trang đã truy cập. Bạn có thể thêm, xoá và truy vấn URL trong nhật ký duyệt web của trình duyệt. Để ghi đè trang nhật ký bằng phiên bản của riêng bạn, hãy xem phần Ghi đè trang.

Quyền

history

Để tương tác với nhật ký duyệt web của người dùng, hãy sử dụng API lịch sử.

Để sử dụng API lịch sử, hãy khai báo quyền "history" trong tệp kê khai tiện ích. Ví dụ:

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

Khái niệm và cách sử dụng

Loại chuyển đổi

API lịch sử sử dụng các loại chuyển đổi để mô tả cách trình duyệt điều hướng đến một URL cụ thể vào một lượt truy cập cụ thể. Ví dụ: nếu người dùng truy cập vào một trang bằng cách nhấp vào một liên kết trên một trang khác, thì loại chuyển đổi là "link". Xem nội dung tham khảo để biết danh sách loại chuyển đổi.

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API nhật ký trong chrome-extension-samples kho lưu trữ.

Loại

HistoryItem

Đối tượng đóng gói một kết quả của một truy vấn lịch sử.

Thuộc tính

• id

  string

  Giá trị nhận dạng duy nhất của mặt hàng.

• lastVisitTime

  số không bắt buộc

  Thời điểm trang này được tải lần cuối, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.

• tiêu đề

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

  Tiêu đề của trang khi tải lần gần đây nhất.

• typedCount

  số không bắt buộc

  Số lần người dùng đã điều hướng đến trang này bằng cách nhập địa chỉ.

• url

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

  URL được người dùng chuyển đến.

• visitCount

  số không bắt buộc

  Số lần người dùng đã chuyển đến trang này.

TransitionType

Chrome 44 trở lên

Loại chuyển đổi cho lượt truy cập này từ đường liên kết giới thiệu.

Enum

"link"
Người dùng đã truy cập vào trang này bằng cách nhấp vào đường liên kết trên một trang khác.

"typed"
Người dùng đã truy cập vào trang này bằng cách nhập URL vào thanh địa chỉ. Thuộc tính này cũng dùng cho các thao tác điều hướng rõ ràng khác.

"auto_bookmark"
Người dùng truy cập vào trang này thông qua một mục đề xuất trong giao diện người dùng, chẳng hạn như thông qua một mục trong trình đơn.

"auto_subframe"
Người dùng truy cập vào trang này thông qua chế độ điều hướng khung phụ mà họ không yêu cầu, chẳng hạn như thông qua một hoạt động tải quảng cáo trong một khung trên trang trước. Các thao tác này không phải lúc nào cũng tạo ra mục điều hướng mới trong trình đơn lùi và tiến.

"manual_subframe"
Người dùng đã truy cập vào trang này bằng cách chọn một nội dung nào đó trong khung phụ.

"Tạo"
Người dùng đã truy cập vào trang này bằng cách nhập vào thanh địa chỉ và chọn một mục nhập không giống như URL, chẳng hạn như mục đề xuất của Google Tìm kiếm. Ví dụ: kết quả trùng khớp có thể có URL của một trang kết quả tìm kiếm trên Google nhưng có thể hiển thị với người dùng dưới dạng "Tìm kiếm ..." trên Google. Các URL này khác với các điều hướng đã nhập bởi vì người dùng không nhập hoặc nhìn thấy URL đích. Chúng cũng liên quan đến việc điều hướng từ khoá.

"auto_toplevel"
Trang được chỉ định trong dòng lệnh hoặc là trang chủ.

"form_submit"
Người dùng đã truy cập vào trang này bằng cách điền các giá trị vào biểu mẫu rồi gửi biểu mẫu. Không phải lượt gửi biểu mẫu nào cũng dùng cách chuyển đổi này.

"tải lại"
Người dùng đã tải lại trang bằng cách nhấp vào nút tải lại hoặc nhấn Enter trong thanh địa chỉ. Tính năng Khôi phục phiên và Mở lại thẻ đã đóng cũng sử dụng kiểu chuyển đổi này.

"keyword"
URL của trang này được tạo từ một từ khoá có thể thay thế chứ không phải nhà cung cấp dịch vụ tìm kiếm mặc định.

"keyword_Tạo"
Tương ứng với lượt truy cập được tạo cho từ khoá.

UrlDetails

Chrome 88 trở lên

Thuộc tính

• url

  string

  URL cho thao tác. Mã này phải ở định dạng như được trả về từ lệnh gọi đến history.search().

VisitItem

Đối tượng đóng gói một lượt truy cập vào một URL.

Thuộc tính

• id

  string

  Giá trị nhận dạng duy nhất của history.HistoryItem tương ứng.

• isLocal

  boolean

  Chrome 115 trở lên

  Đúng nếu lượt truy cập bắt nguồn từ thiết bị này. Sai nếu ảnh được đồng bộ hoá từ một thiết bị khác.

• referringVisitId

  string

  Mã truy cập của đường liên kết giới thiệu.

• chuyển đổi

  TransitionType

  Loại chuyển đổi cho lượt truy cập này từ đường liên kết giới thiệu.

• visitId

  string

  Giá trị nhận dạng duy nhất của lượt truy cập này.

• visitTime

  số không bắt buộc

  Thời điểm lượt truy cập này xảy ra, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.

Phương thức

addUrl()

Lời hứa

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Thêm URL vào lịch sử tại thời điểm hiện tại với loại chuyển đổi là "link".

Tham số

• chi tiết

  UrlDetails

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

deleteAll()

Lời hứa

chrome.history.deleteAll(
  callback?: function,
)

Xoá tất cả các mục khỏi nhật ký.

Tham số

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

deleteRange()

Lời hứa

chrome.history.deleteRange(
  range: object,
  callback?: function,
)

Xóa tất cả các mục trong phạm vi ngày được chỉ định khỏi lịch sử. Trang sẽ không bị xoá khỏi nhật ký trừ phi tất cả lượt truy cập đều nằm trong phạm vi này.

Tham số

• phạm vi

  đối tượng

  • endTime

    số

    Các mục được thêm vào nhật ký trước ngày này, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.

  • startTime

    số

    Các mục được thêm vào nhật ký sau ngày này, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.

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

deleteUrl()

Lời hứa

chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Xóa tất cả các lần xuất hiện của URL đã cho khỏi lịch sử.

Tham số

• chi tiết

  UrlDetails

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

getVisits()

Lời hứa

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Truy xuất thông tin về các lượt truy cập vào một URL.

Tham số

• chi tiết

  UrlDetails

• số gọi lại

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

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

  (results: VisitItem[]) => void

  • kết quả

    VisitItem[]

Giá trị trả về

• Promise&lt;VisitItem[]&gt;

  Chrome 96 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.history.search(
  query: object,
  callback?: function,
)

Tìm kiếm lịch sử cho thời gian truy cập gần đây nhất của mỗi trang khớp với truy vấn.

Tham số

• truy vấn

  đối tượng

  • endTime

    số không bắt buộc

    Giới hạn kết quả ở những lượt truy cập trước ngày này, được thể hiện bằng mili giây kể từ thời gian bắt đầu của hệ thống.

  • kết quả tối đa

    số không bắt buộc

    Số lượng kết quả tối đa cần truy xuất. Giá trị mặc định là 100.

  • startTime

    số không bắt buộc

    Giới hạn kết quả ở những lượt truy cập sau ngày này, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống. Nếu bạn không chỉ định thuộc tính, giá trị mặc định sẽ là 24 giờ.

  • văn bản

    string

    Truy vấn bằng văn bản tự do đến dịch vụ nhật ký. Hãy để trống trường này để truy xuất tất cả các trang.

• số gọi lại

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

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

  (results: HistoryItem[]) => void

  • kết quả

    HistoryItem[]

Giá trị trả về

• Promise&lt;HistoryItem[]&gt;

  Chrome 96 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

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

Được kích hoạt khi một URL được truy cập, cung cấp dữ liệu HistoryItem cho URL đó. Sự kiện này kích hoạt trước khi trang được tải.

Tham số

• số gọi lại

  hàm

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

  (result: HistoryItem) => void

  • kết quả

    HistoryItem

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

Được kích hoạt khi một hoặc nhiều URL bị xoá khỏi nhật ký. Khi mọi lượt truy cập đã bị xoá, URL sẽ bị xoá hoàn toàn khỏi nhật ký.

Tham số

• số gọi lại

  hàm

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

  (removed: object) => void

  • đã xóa

    đối tượng

    • allHistory

      boolean

      Đúng nếu toàn bộ nhật ký đã bị xoá. Nếu đúng thì url sẽ trống.

    • url

      string[] không bắt buộc