ACtl.captureTab

Takes a screenshot of one or more tabs. The tab's containing window may be overlapped or offscreen entirely, but not minimized. The captured area corresponds to the visible part of the page (a.k.a. the viewport), not the whole page.

ACtl.captureTab([tabSpec,][returnType]) tabSpec Type: TabSpec Default: undefined One or more tabs to capture. It can be either a tab ID, a filter object, a tab-selection name or an array combining all that. Full details at Tab Specifier. If omitted, it defaults to the tab the script is running in. returnType Type: string Default: 'dataUri' How to return the images:

'binary'	Return as a binary string
'dataUri'	Return as a data URI string
'objectUrl'	Return as a object URL string
'base64'	Return as a Base64 string
'blob'	Return as a Blob object
'image'	Return as a HTMLImageElement object
'canvas'	Return as a HTMLCanvasElement object

All return types are in PNG format, with the exception of 'canvas' which doesn't need an encoding format. Returns Type: Promise Resolves to: Object Returns immediately. The Promise will resolve with an object of [tabID, returnType] pairs containing the captured images.

For example, if returnType is 'dataUri', the content of the object will look like this:


						{
							23: 'data:image/png;base64,...',
							51: 'data:image/png;base64,...',
							105: 'data:image/png;base64,...',
						}

This object is iterable, so it can be destructured like an array. See the examples below.

If a tab cannot be captured, it will not be added to the returned object. Reasons for this include:

The given tab ID doesn't exist
The tab contains a protected page
The tab's containing window is minimized
The browser is not rendering the tab due to it being discarded, unloaded or some other reason.

Throws Type: string Error description if any of the following happens:

tabSpec is not a valid Tab Specifier.
returnType is not any of the supported return types.
The function is called from a background script with no tabSpec argument.

Limitations

This function can capture tabs in any window as long as the window is not minimized. The window can be overlapped or even offscreen entirely. Also, for a tab to be captured, it must be the active tab in its window. If the tab is not active, the function will activate it so it can be captured.

If the tabSpec argument speficies multiple tabs, they will be activated one at a time. The speed at which this occurs depends on how fast your computer is (usually a small fraction of a second per tab). The function will not unminimize a window or change its visibility state in any way. It will only change the active state of the given tabs.

Due to security reasons enforced by the browser, this function cannot capture protected pages.

Examples

Capture the tab the script is running in and open the captured image in a new tab.


	//Capture the tab as a data-URI image
	//We can destructure the returned object as if an array of [key,value] pairs
	let [[, pngDataUri]] = await ACtl.captureTab() ;
	//Open the data URI in a new tab to the right of the current tab
	ACtl.openURL(pngDataUri, {rightOf: '#currentTab'}) ;

Capture the tab the script is running in and then insert the captured image into the same page.


	//Capture the tab as an <img> element
	let [[, imageElem]] = await ACtl.captureTab( ACtl.TAB_ID, 'image' ) ;
	//Add some CSS styles to the image
	imageElem.style.cssText = 'position: fixed; top: 10px; left: 10px; width: 50%' ;
	//Insert the image into the page
	document.body.appendChild( imageElem ) ;

Capture all tabs in the current window and save the images to PNG files.


	//Get the tab captures as BLOBs
	let tabImages = await ACtl.captureTab('#currWinTabs', 'blob') ;
	//For each captured image
	for( let [tabId, imageBlob] of tabImages ){
		//Save the image to a folder in the desktop
		ACtl.saveFile(`<desktop>/Tab Captures/Tab ID ${tabId}.png`, imageBlob) ;
	}

Capture the current tab, add a text label to the image and then save it to a file.


	//Capture the current tab as a canvas object
	let [[, canvas]] = await ACtl.captureTab('#currentTab', 'canvas') ;
	let ctx = canvas.getContext('2d') ;
	//Set text style
	ctx.font = 'bold 20px arial' ;
	ctx.fillStyle = 'blue' ;
	ctx.textBaseline = 'top' ;
	//Draw the text in the canvas at coordinates [5,5]
	ctx.fillText('Hello, world!', 5, 5) ;
	//Save the canvas to a PNG file in the desktop
	ACtl.saveFile('<desktop>/tab-capture.png', canvas) ;

Scripting API Script Isolation Asynchronicity Backgrnd Scripts GUI vs API ACtl.include ACtl.import ACtl.getFile ACtl.saveFile ACtl.saveURL ACtl.openURL ACtl.closeTab ACtl.runInTab ACtl.runInFrames ACtl.runInPageCtx ACtl.getTabInfo ACtl.getTabIds ACtl.TAB_ID ACtl.setTabState ACtl.captureTab ACtl.execAction ACtl.runCommand ACtl.getClipboard ACtl.setClipboard ACtl.expand ACtl.switchState ACtl.var ACtl.pubVar ACtl.on ACtl.off ACtl.sleep ACtl.STOP_CHAIN ACtl.STOP_FULL_SEQ