chrome.webNavigation (original) (raw)

Mô tả

Sử dụng API chrome.webNavigation để nhận thông báo về trạng thái của các yêu cầu chỉ đường đang diễn ra.

Quyền

webNavigation

Tất cả các phương thức và sự kiện chrome.webNavigation đều yêu cầu bạn khai báo quyền "webNavigation" trong tệp kê khai tiện ích. Ví dụ:

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

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

Thứ tự sự kiện

Đối với một thao tác điều hướng hoàn tất thành công, các sự kiện sẽ được kích hoạt theo thứ tự sau:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

Mọi lỗi xảy ra trong quá trình này đều dẫn đến sự kiện onErrorOccurred. Đối với một thao tác điều hướng cụ thể, sẽ không có sự kiện nào khác được kích hoạt sau onErrorOccurred.

Nếu một khung điều hướng chứa các khung phụ, thì onCommitted của khung đó sẽ được kích hoạt trước bất kỳ onBeforeNavigate nào của khung con; trong khi onCompleted được kích hoạt sau khi tất cả onCompleted của khung con được kích hoạt.

Nếu mảnh tham chiếu của một khung hình bị thay đổi, sự kiện onReferenceFragmentUpdated sẽ được kích hoạt. Sự kiện này có thể kích hoạt bất cứ lúc nào sau onDOMContentLoaded, ngay cả sau onCompleted.

Nếu history API được dùng để sửa đổi trạng thái của một khung hình (ví dụ: dùng history.pushState(), sự kiện onHistoryStateUpdated sẽ được kích hoạt. Sự kiện này có thể kích hoạt bất cứ lúc nào sau onDOMContentLoaded.

Nếu một thao tác di chuyển khôi phục trang từ Bộ nhớ đệm cho thao tác tiến/lùi, thì sự kiện onDOMContentLoaded sẽ không kích hoạt. Sự kiện này không được kích hoạt vì nội dung đã hoàn tất quá trình tải khi người dùng truy cập trang lần đầu.

Nếu một thao tác điều hướng được kích hoạt bằng Chrome Instant hoặc Instant Pages, thì một trang đã tải hoàn toàn sẽ được hoán đổi vào thẻ hiện tại. Trong trường hợp đó, sự kiện onTabReplaced sẽ được kích hoạt.

Mối quan hệ với các sự kiện webRequest

Không có thứ tự xác định giữa các sự kiện của webRequest API và các sự kiện của webNavigation API. Có thể các sự kiện webRequest vẫn được nhận cho những khung đã bắt đầu một thao tác điều hướng mới hoặc thao tác điều hướng chỉ diễn ra sau khi các tài nguyên mạng đã được tải đầy đủ.

Nhìn chung, các sự kiện webNavigation có liên quan chặt chẽ đến trạng thái điều hướng xuất hiện trong giao diện người dùng, trong khi các sự kiện webRequest tương ứng với trạng thái của ngăn xếp mạng mà người dùng thường không thấy được.

Mã nhận dạng thẻ

Không phải tất cả các thẻ điều hướng đều tương ứng với các thẻ thực tế trong giao diện người dùng của Chrome, ví dụ: thẻ đang được kết xuất trước. Bạn không thể truy cập vào các thẻ như vậy bằng API thẻ, cũng như không thể yêu cầu thông tin về các thẻ đó bằng cách gọi webNavigation.getFrame() hoặc webNavigation.getAllFrames(). Sau khi một thẻ như vậy được hoán đổi, sự kiện onTabReplaced sẽ kích hoạt và người dùng có thể truy cập vào thẻ đó thông qua các API này.

Dấu thời gian

Điều quan trọng cần lưu ý là một số điểm bất thường về kỹ thuật trong cách hệ điều hành xử lý các quy trình riêng biệt của Chrome có thể khiến đồng hồ bị lệch giữa chính trình duyệt và các quy trình của tiện ích. Điều đó có nghĩa là thuộc tính timeStamp của thuộc tính timeStamp sự kiện WebNavigation chỉ được đảm bảo nhất quán nội bộ. Việc so sánh một sự kiện với một sự kiện khác sẽ cho bạn biết độ lệch chính xác giữa hai sự kiện đó, nhưng việc so sánh các sự kiện đó với thời gian hiện tại trong tiện ích (ví dụ: sử dụng (new Date()).getTime()) có thể cho ra kết quả không mong muốn.

Mã khung

Bạn có thể xác định các khung trong một thẻ bằng mã nhận dạng khung. Mã nhận dạng khung của khung chính luôn là 0, mã nhận dạng của khung con là một số dương. Sau khi một tài liệu được tạo trong khung, mã nhận dạng khung của tài liệu đó sẽ không đổi trong suốt thời gian tồn tại của tài liệu. Kể từ Chrome 49, mã nhận dạng này cũng không đổi trong suốt thời gian tồn tại của khung (trên nhiều lần điều hướng).

Do bản chất đa quy trình của Chrome, một thẻ có thể sử dụng các quy trình khác nhau để kết xuất nguồn và đích của một trang web. Do đó, nếu một thao tác điều hướng diễn ra trong một quy trình mới, bạn có thể nhận được các sự kiện từ cả trang mới và trang cũ cho đến khi thao tác điều hướng mới được thực hiện (tức là sự kiện onCommitted được gửi cho khung chính mới). Nói cách khác, có thể có nhiều chuỗi sự kiện webNavigation đang chờ xử lý có cùng frameId. Bạn có thể phân biệt các chuỗi bằng khoá processId.

Ngoài ra, xin lưu ý rằng trong quá trình tải tạm thời, quy trình này có thể được chuyển đổi nhiều lần. Điều này xảy ra khi tải được chuyển hướng đến một trang web khác. Trong trường hợp này, bạn sẽ nhận được các sự kiện onBeforeNavigate và onErrorOccurred lặp lại cho đến khi nhận được sự kiện onCommitted cuối cùng.

Một khái niệm khác gây ra vấn đề với các tiện ích là vòng đời của khung. Khung lưu trữ một tài liệu (được liên kết với một URL đã xác nhận). Tài liệu có thể thay đổi (ví dụ: bằng cách điều hướng) nhưng frameId sẽ không thay đổi. Do đó, rất khó để liên kết một sự kiện xảy ra trong một tài liệu cụ thể chỉ với frameId. Chúng tôi đang giới thiệu khái niệm về documentId. Đây là giá trị nhận dạng riêng biệt cho mỗi tài liệu. Nếu một khung được điều hướng và mở một tài liệu mới, thì giá trị nhận dạng sẽ thay đổi. Trường này rất hữu ích để xác định thời điểm các trang thay đổi trạng thái vòng đời (giữa trạng thái kết xuất trước/đang hoạt động/được lưu vào bộ nhớ đệm) vì trường này vẫn giữ nguyên.

Các loại và bộ hạn định chuyển đổi

Sự kiện webNavigation onCommitted có một transitionType và một thuộc tính transitionQualifiers. Loại chuyển đổi giống như loại được dùng trong history API, mô tả cách trình duyệt chuyển đến URL cụ thể này. Ngoài ra, một số trạng từ chuyển đổi có thể được trả về để xác định thêm thao tác điều hướng.

Các tiêu chí đủ điều kiện chuyển đổi sau đây tồn tại:

Bộ hạn định chuyển đổi Mô tả
"client_redirect" Đã xảy ra một hoặc nhiều lượt chuyển hướng do JavaScript hoặc thẻ làm mới meta trên trang trong quá trình điều hướng.
"server_redirect" Đã xảy ra một hoặc nhiều lượt chuyển hướng do tiêu đề HTTP được gửi từ máy chủ trong quá trình điều hướng.
"forward_back" Người dùng đã sử dụng nút Tiến hoặc nút Quay lại để bắt đầu thao tác điều hướng.
"from_address_bar" Người dùng bắt đầu thao tác điều hướng từ thanh địa chỉ (còn gọi là Omnibox).

Ví dụ

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

Loại

TransitionQualifier

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Nguyên nhân của hoạt động điều hướng. Các loại chuyển đổi giống như được xác định trong history API sẽ được sử dụng. Đây là các loại chuyển đổi giống như được xác định trong history API, ngoại trừ "start_page" thay cho "auto_toplevel" (để đảm bảo khả năng tương thích ngược).

Enum

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Phương thức

getAllFrames()

chrome.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

Truy xuất thông tin về tất cả các khung của một thẻ nhất định.

Thông số

Giá trị trả về

getFrame()

chrome.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

Truy xuất thông tin về khung hình đã cho. Khung đề cập đến hoặc của một trang web và được xác định bằng mã nhận dạng thẻ và mã nhận dạng khung.

Thông số

Giá trị trả về

Sự kiện

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một thao tác điều hướng sắp xảy ra.

Thông số

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một thao tác điều hướng được thực hiện. Tài liệu (và các tài nguyên mà tài liệu đó tham chiếu đến, chẳng hạn như hình ảnh và khung phụ) có thể vẫn đang tải xuống, nhưng ít nhất một phần của tài liệu đã được nhận từ máy chủ và trình duyệt đã quyết định chuyển sang tài liệu mới.

Thông số

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một tài liệu (bao gồm cả tài nguyên mà tài liệu đó đề cập đến) được tải và khởi tạo hoàn toàn.

Thông số

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một cửa sổ mới hoặc một thẻ mới trong cửa sổ hiện có được tạo để lưu trữ một thao tác điều hướng.

Thông số

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi DOM của trang được tạo hoàn toàn, nhưng các tài nguyên được tham chiếu có thể chưa tải xong.

Thông số

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi xảy ra lỗi và quá trình điều hướng bị huỷ. Điều này có thể xảy ra nếu xảy ra lỗi mạng hoặc người dùng huỷ thao tác điều hướng.

Thông số

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi nhật ký của khung được cập nhật thành một URL mới. Tất cả các sự kiện trong tương lai cho khung đó sẽ sử dụng URL mới.

Thông số

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi mảnh tham chiếu của một khung hình được cập nhật. Tất cả các sự kiện trong tương lai cho khung đó sẽ sử dụng URL mới.

Thông số

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

Sự kiện này xảy ra khi nội dung của thẻ được thay thế bằng một thẻ khác (thường là thẻ đã được kết xuất trước).

Thông số