webNavigation.getFrame()
Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested <iframe>, and is uniquely identified by a tab ID and a frame ID.
Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested <iframe>, and is uniquely identified by a tab ID and a frame ID.
This is an asynchronous function that returns a Promise.
Syntax
let gettingFrame = browser.webNavigation.getFrame(
details // object
)
Parameters
details- :
object. Information about the frame to retrieve. Must include eitherdocumentId, ortabIdandframeId.tabId- :
integer. The ID of the tab in which the frame is. Required ifdocumentIdis not specified. processId- :
integer. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab. frameId- :
integer. The ID of the frame in the given tab. Required ifdocumentIdis not specified. documentId- :
string. The UUID of the frame's document. IftabIdandframeIdare also specified, the frame is only returned if all properties match. See the Work with documentId article for more information.
Return value
A Promise that is fulfilled with an object containing these properties:
errorOccurred- :
boolean. True if the last navigation in this frame was interrupted by an error, i.e., the onErrorOccurred event fired. url- :
string. The URL associated with this frame, if the frame identified byframeIdexisted at one point in the tab identified bytabId. The fact that a URL is associated with a givenframeIddoes not imply that the corresponding frame still exists. frameType- :
string. The type of frame. Returns the values"outermost_frame","fenced_frame", or"sub_frame". parentFrameId- :
integer. ID of this frame's parent. This is -1 if there is no parent frame: that is, if this frame is the top-level browsing context in the tab. documentId- :
string. A UUID of the frame's document. See the Work with documentId article for more information. parentDocumentId- :
string. A UUID of the parent document owning the frame. Not set if there is no parent. See the Work with documentId article for more information. documentLifecycle- :
string. The lifecycle the document is in. Returns the values"prerender","active","cached", or"pending_deletion".
If the tab is discarded, the promise will instead resolve with a null value. If the specified tab or frame ID could not be found, or some other error occurs, the promise will be rejected with an error message.
Examples
function onGot(frameInfo) {
console.log(frameInfo);
}
function onError(error) {
console.log(`Error: ${error}`);
}
let gettingFrame = browser.webNavigation.getFrame({
tabId: 19,
frameId: 1537,
});
// Edge specific - processId is required not optional, must be integer not null
// let gettingFrame = browser.webNavigation.getFrame({ tabId: 19, processId: 0, frameId: 1537 });
gettingFrame.then(onGot, onError);
Browser compatibility
[!NOTE] This API is based on Chromium's
chrome.webNavigationAPI. This documentation is derived fromweb_navigation.jsonin the Chromium code.