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ệp kê khai

Bạn phải khai báo "nhật ký" quyền trong tệp kê khai tiện ích để sử dụng API lịch sử. Ví dụ:

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

Loại chuyển đổi

API lịch sử sử dụng một loại chuyển đổi để mô tả cách trình duyệt chuyển đế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".

Bảng sau đây mô tả từng loại chuyển đổi.

Loại chuyển đổi	Mô tả
"link"	Người dùng được chuyển đến 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 đã xem được trang này bằng cách nhập URL vào thanh địa chỉ. Cũng được dùng cho các thao tác điều hướng rõ ràng khác. Hãy xem thêm mục đã tạo, dùng cho trường hợp người dùng đã chọn một lựa chọn có vẻ không giống một URL.
"auto_bookmark" (tự động đánh dấu trang)	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, ví dụ: thông qua một mục trong trình đơn.
"auto_subframe"	Điều hướng khung phụ. Đây là bất kỳ nội dung nào được tải tự động trong một khung không phải cấp cao nhất. Ví dụ: nếu một trang bao gồm một số khung chứa quảng cáo, thì các URL quảng cáo đó sẽ có loại chuyển đổi này. Người dùng thậm chí có thể không nhận ra nội dung trên các trang này là một khung riêng biệt và do đó có thể không quan tâm đến URL (xem thêm manual_subframe).
"manual_subframe"	Đối với các thao tác điều hướng khung phụ được người dùng yêu cầu rõ ràng và tạo các mục điều hướng mới trong danh sách tiến/lùi. Khung được yêu cầu rõ ràng có thể quan trọng hơn khung được tải tự động vì người dùng có thể quan tâm đến thực tế là khung được yêu cầu đã được tải.
"đã tạo"	Người dùng được chuyển đến trang này bằng cách nhập vào thanh địa chỉ rồi chọn một mục nhập không giống một URL. Ví dụ: kết quả trùng khớp có thể có URL của trang kết quả tìm kiếm của Google 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. Các điều hướng này không giống như điều hướng đã nhập vì người dùng không nhập hoặc nhìn thấy URL đích. Xem thêm từ khóa.
"auto_toplevel"	Trang được chỉ định trong dòng lệnh hoặc là trang chủ.
"form_submit"	Người dùng điền các giá trị vào biểu mẫu rồi gửi đi. Lưu ý rằng trong một số trường hợp (chẳng hạn như khi biểu mẫu sử dụng tập lệnh để gửi nội dung), thì việc gửi biểu mẫu không dẫn đến loại 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ỉ. Việc khôi phục phiên và Mở lại thẻ đã đóng cũng sử dụng loại chuyển đổi này.
"từ khóa"	URL này được tạo từ từ khoá có thể thay thế không phải là nhà cung cấp dịch vụ tìm kiếm mặc định. Hãy xem thêm mục keyword_generated.
"từ_khoá_đã_tạo"	Tương ứng với lượt truy cập được tạo cho từ khoá. Xem thêm từ khóa.

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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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