webNavigation.getFrame()

Syntax

let gettingFrame = browser.webNavigation.getFrame(
  details                // object
)

Parameters

details

object. Information about the frame to retrieve. Must include either documentId, or tabId and frameId.

tabId Optional

integer. The ID of the tab in which the frame is. Required if documentId is not specified.

processId Optional

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 Optional

integer. The ID of the frame in the given tab. Required if documentId is not specified.

documentId Optional

string. The UUID of the frame's document. If tabId and frameId are 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 by frameId existed at one point in the tab identified by tabId. The fact that a URL is associated with a given frameId does 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