Trang này được dịch bởi Cloud Translation API.

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<VisitItem[]>

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 bả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<HistoryItem[]>

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 quả
  
  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