Mô tả
Sử dụng API chrome.history để tương tác với bản ghi các trang đã truy cập của trình duyệt. Bạn có thể thêm, xoá và truy vấn URL trong nhật ký 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ý trình duyệt của người dùng, hãy sử dụng API nhật ký.
Để sử dụng History API, 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
History API sử dụng các loại chuyển đổi để mô tả cách trình duyệt chuyển đến một URL cụ thể trong 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 đường liên kết trên một trang khác, thì loại chuyển đổi là "đường liên kết". Hãy xem nội dung tham khảo để biết danh sách các loại hiệu ứng chuyển đổi.
Ví dụ
Để dùng thử API này, hãy cài đặt ví dụ về history API trong kho lưu trữ chrome-extension-samples.
Loại
HistoryItem
Một đối tượng đóng gói một kết quả của truy vấn nhật ký.
Thuộc tính
-
id
chuỗi
Giá trị nhận dạng duy nhất của mặt hàng.
-
lastVisitTime
number không bắt buộc
Thời điểm trang này được tả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.
-
tiêu đề
chuỗi không bắt buộc
Tiêu đề của trang khi được tải lần gần đây nhất.
-
typedCount
number không bắt buộc
Số lần người dùng đã chuyển đến trang này bằng cách nhập địa chỉ.
-
url
chuỗi không bắt buộc
URL mà người dùng truy cập.
-
visitCount
number không bắt buộc
Số lần người dùng chuyển đến trang này.
Enum
"đường liên kết"
Người dùng truy cập vào trang này bằng cách nhấp vào một đường liên kết trên một trang khác.
"đã nhập"
Người dùng truy cập vào trang này bằng cách nhập URL vào thanh địa chỉ. Thao tác này cũng được 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 đề 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 thao tác điều hướng khung phụ mà họ không yêu cầu, chẳng hạn như thông qua một quảng cáo đang tải trong một khung trên trang trước. Những thao tác này không phải lúc nào cũng tạo ra các mục mới trong trình đơn quay lại và chuyển tiếp.
"manual_subframe"
Người dùng truy cập vào trang này bằng cách chọn một mục trong khung phụ.
"được 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ột đề xuất của Google Tìm kiếm. Ví dụ: một kết quả trùng khớp có thể có URL của một trang kết quả trên Google Tìm kiếm, nhưng có thể xuất hiện với người dùng dưới dạng "Tìm kiếm ... trên Google". Những kết quả này khác với các thao tác điều hướng được nhập 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 các thao tác điều hướng bằng từ khoá.
"auto_toplevel"
Trang được chỉ định trong dòng lệnh hoặc là trang bắt đầu.
"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 một biểu mẫu rồi gửi biểu mẫu đó. Không phải tất cả các lượt gửi biểu mẫu đều sử dụng loại chuyển đổi này.
"reload"
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 phím 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 loại hiệu ứng chuyển đổi này.
"từ khoá"
URL của trang này được tạo từ một từ khoá có thể thay thế, không phải nhà cung cấp dịch vụ tìm kiếm mặc định.
"keyword_generated"
Tương ứng với một lượt truy cập được tạo cho một từ khoá.
UrlDetails
Thuộc tính
-
url
chuỗi
URL cho thao tác. Tham số này phải ở định dạng được trả về từ lệnh gọi đến
history.search().
VisitItem
Một đối tượng đóng gói một lượt truy cập vào một URL.
Thuộc tính
-
id
chuỗi
Giá trị nhận dạng riêng biệt của
history.HistoryItemtươ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. False nếu được đồng bộ hoá từ một thiết bị khác.
-
referringVisitId
chuỗi
Mã lượt truy cập của đơn vị giới thiệu.
-
chuyển cảnh
Loại chuyển đổi cho lượt truy cập này từ đơn vị giới thiệu.
-
visitId
chuỗi
Giá trị nhận dạng riêng biệt của lượt truy cập này.
-
visitTime
number không bắt buộc
Thời điểm diễn ra lượt truy cập này, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.
Phương thức
addUrl()
chrome.history.addUrl(
details: UrlDetails,
): Promise<void>
Thêm một URL vào nhật ký tại thời điểm hiện tại với loại chuyển đổi là "link".
Thông số
-
chi tiết
Giá trị trả về
-
Promise<void>
Chrome 96 trở lên
deleteAll()
chrome.history.deleteAll(): Promise<void>
Xoá tất cả các mục khỏi nhật ký.
Giá trị trả về
-
Promise<void>
Chrome 96 trở lên
deleteRange()
chrome.history.deleteRange(
range: object,
): Promise<void>
Xoá tất cả các mục trong phạm vi ngày được chỉ định khỏi nhật ký. Các 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.
Thông 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.
-
Giá trị trả về
-
Promise<void>
Chrome 96 trở lên
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
): Promise<void>
Xoá tất cả các lần xuất hiện của URL đã cho khỏi nhật ký.
Thông số
-
chi tiết
Giá trị trả về
-
Promise<void>
Chrome 96 trở lên
getVisits()
chrome.history.getVisits(
details: UrlDetails,
): Promise<VisitItem[]>
Truy xuất thông tin về lượt truy cập vào một URL.
Thông số
-
chi tiết
Giá trị trả về
-
Promise<VisitItem[]>
Chrome 96 trở lên
search()
chrome.history.search(
query: object,
): Promise<HistoryItem[]>
Tìm kiếm trong nhật ký thời gian truy cập gần đây nhất của mỗi trang khớp với cụm từ tìm kiếm.
Thông số
-
truy vấn
đối tượng
-
endTime
number không bắt buộc
Giới hạn kết quả trong những kết quả đã được truy cập 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.
-
maxResults
number 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
number không bắt buộc
Giới hạn kết quả cho những địa điểm được ghé thăm sau ngày này, tính bằng mili giây kể từ thời gian bắt đầu hệ thống. Nếu bạn không chỉ định thuộc tính này, giá trị mặc định sẽ là 24 giờ.
-
văn bản
chuỗi
Một truy vấn bằng văn bản tự do đến dịch vụ nhật ký. Để trống trường này để truy xuất tất cả các trang.
-
Giá trị trả về
-
Promise<HistoryItem[]>
Chrome 96 trở lên
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.
Thông số
-
callback
hàm
Tham số
callbackcó dạng như sau:(result: HistoryItem) => void
-
kết quả
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
Kích hoạt khi một hoặc nhiều URL bị xoá khỏi nhật ký. Khi tất cả lượt truy cập đã bị xoá, URL sẽ bị xoá khỏi nhật ký.
Thông số
-
callback
hàm
Tham số
callbackcó dạng như sau:(removed: object) => void
-
đã xóa
đối tượng
-
allHistory
boolean
Đúng nếu tất cả nhật ký đã bị xoá. Nếu đúng, thì URL sẽ trống.
-
url
string[] không bắt buộc
-
-