chrome.history

Nội dung mô tả

Sử dụng API chrome.history để tương tác với bản ghi về các trang đã truy cập của trình duyệt. Bạn có thể thêm, xoá và truy vấn các 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ệp kê khai

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

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

Loại chuyển đổi

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

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

Loại chuyển đổiNội dung mô tả
"đã 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ỉ. Thuộc tính này cũng được dùng cho các thao tác điều hướng rõ ràng khác. Xem thêm giá trị đã tạo, dùng cho các trường hợp mà người dùng đã chọn một lựa chọn không hề giống một URL.
"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 (ví dụ: 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ự động tải trong khung không phải cấp cao nhất. Ví dụ: nếu một trang bao gồm nhiều khung chứa quảng cáo, thì những URL quảng cáo đó có loại chuyển đổi này. Người dùng có thể thậm chí không nhận ra nội dung trên các trang này là một khung riêng biệt, 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ể sẽ quan tâm đến việc khung được yêu cầu đã được tải.
"đã 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 không giống URL. Ví dụ: kết quả phù hợp có thể có URL của một trang kết quả tìm kiếm trên Google, nhưng người dùng có thể nhìn thấy "Tìm kiếm trên Google ...". Các kết quả này không giống với điều hướng được nhập vì người dùng không nhập hoặc nhìn thấy URL đích. Xem thêm từ khoá.
"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. Xin 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 sẽ 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 vào 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 chuyển đổi này.
"từ khóa"URL đượ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. Hãy xem thêm keyword_generated.
"keyword_generated"Tương ứng với lượt truy cập được tạo cho từ khoá. Xem thêm từ khoá.

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API nhật ký 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

    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 gần đây nhất, biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.

  • title

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

    Tiêu đề của trang khi trang được 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 mà người dùng đã điều hướng đến.

  • visitCount

    số không bắt buộc

    Số lần người dùng đã điều hướng đến trang này.

TransitionType

Chrome 44 trở lên

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

Liệt kê

"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ỉ. API 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 mục đề xuất trong giao diện người dùng, ví dụ 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 tính năng điều hướng khung phụ mà họ không yêu cầu, chẳng hạn như thông qua việc 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 các mục điều hướng mới trong trình đơn tiến và lùi.

"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 trong khung phụ.

"generated"
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 không giống như URL, chẳng hạn như đề xuất của Google Tìm kiếm. Ví dụ: kết quả phù hợp có thể chứa URL của một trang kết quả tìm kiếm trên Google, nhưng người dùng có thể nhìn thấy URL này là "Tìm kiếm trên Google ...". Các kết quả này khác với các điều hướng đã nhập vì người dùng không nhập hoặc xem 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 một 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 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 Enter vào thanh địa chỉ. 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ừ khoá"
URL cho trang này được tạo từ từ khoá có thể thay thế ngoà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

Chrome 88 trở lên

Thuộc tính

  • url

    string

    URL cho toán tử. Giá trị 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

    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 trên thiết bị này. Sai nếu đồ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ừ liên kết giới thiệu của nó.

  • 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 diễn ra lượt truy cập này, đượ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()

Cam kết 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Thêm một URL vào nhật ký tại thời điểm hiện tại bằng loại chuyển đổi "đường liên kết".

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ề

  • Promise<void>

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

Cam kết 
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ề

  • Promise<void>

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

Cam kết 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

Tham số

  • phạm vi

    đối tượng

    • endTime

      number

      Các mục được thêm vào nhật ký 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.

    • startTime

      number

      Các mục được thêm vào nhật ký sau 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.

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

  • Promise<void>

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

Cam kết 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Xoá 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ề

  • Promise<void>

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

Cam kết 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Truy xuất thông tin về lượt truy cập vào 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

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.

Cam kết 
chrome.history.search(
  query: object,
  callback?: function,
)

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

Tham số

  • query

    đối tượng

    • endTime

      số không bắt buộc

      Giới hạn kết quả ở 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

      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

      Chỉ hiện kết quả cho những người được 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, thời gian mặc định sẽ là 24 giờ.

    • văn bản

      string

      Truy vấn dạ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

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 sẽ 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

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 tất cả các 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 tất cả nhật ký đã bị xoá. Nếu đúng thì URL sẽ trống.

      • urls

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