addon.tab

Available in userscripts✔️
Available in popup scripts
Required manifest permissionsNone

Description

Allows addon userscripts to get information about the tab they’re currently running on.

Examples

Using addon.tab.waitForElement

We can use addon.tab.waitForElement with {"markAsSeen": true} inside a while(true) loop to store the IDs of all comments in the page.
Using addon.tab.waitForElement, we don’t need to have code that waits until comments have loaded. This way, we also store the IDs of newly posted comments and new loaded comments when the user clicks “load more comments”.

const commentIds = [];
while (true) {
  const comment = await addon.tab.waitForElement("div.comment", {
      markAsSeen: true,
  });
  commentIds.push(comment.id);
}

Using addon.tab.displayNoneWhileDisabled (dynamicDisable)

We use addon.tab.displayNoneWhileDisabled to hide an image when the addon gets disabled.
We create a button to hide the image when clicked, and the image succesfully gets hidden, even if the addon is enabled.
We also set the display CSS property of the image to flex when visible, even though that is not the default value for images.

  /* userscript.js */
  const img = document.createElement("img");
  img.classList.add("sa-example-img");
  addon.tab.displayNoneWhileDisabled(img, { display: "flex" });
  const btn = document.createElement("btn");
  btn.onclick = () => {
    // We want to hide the image
    // We cannot do `img.style.display = "none"` because we
    // used displayNoneWhileDisabled with the same element
    img.classList.add("sa-example-img-hide");
  };
/* userstyle.css */
.sa-example-img {
  display: flex;
}
.sa-example-img-hide {
  /* We want to hide the image if the button was clicked, 
  even if the addon is enabled */
  display: none !important;
}

Reacting to URL dynamically changed

addon.tab.addEventListener("urlChange", function(event) {
  console.log(`URL changed! It was previously ${event.detail.oldUrl}, it's now ${event.detail.newUrl}`);
});

Sub-APIs

addon.tab.traps

Allows addons to get direct references to objects, which are particularly useful for enhancing the editor, like the Scratch VM or the Blockly instance.

addon.tab.redux

Allows addons to get and modify Redux state, which is useful for addons that modify scratch-www pages and the editor.

Properties

addon.tab.clientVersion

Value"scratch-www" | "scratchr2"
NullableYes

The Scratch client for the current tab (scratch-www or scratchr2).
The Scratch community website has 2 working clients used throughout the site.
scratch-www is React/Redux based and client side rendered. This client is the one used in the homepage.
scratchr2 is Django/jQuery/Backbone.js based and mostly server side rendered. This client is the one used in profile pages.

addon.tab.editorMode

Value"projectpage" | "editor" | "fullscreen" | "embed"
NullableYes

The current viewing mode for the project (projectpage, editor, fullscreen or embed).
Will be null if the current tab is not a project.

addon.tab.direction

Value"ltr" | "rtl"
NullableNo

The writing direction for the language of the Scratch website.

Methods

addon.tab.waitForElement

ParameterTypeRequiredDescription
selectorStringYesOne or more selectors to match. Same parameter as document.querySelector.
optionsObjectNo
PropertyTypeRequiredDefaultDescription
markAsSeenBooleanNofalseWhether it should mark resolved elements to be skipped next time or not.
conditionFunctionNo() => trueA function that returns whether to resolve the selector or not. No arguments are passed.
reduxConditionFunctionNo() => trueA function that returns whether to resolve the selector or not. addon.tab.redux is passed as an argument.
reduxEventsString[]No[]An array of Redux events that must be dispatched before resolving the selector.
Return valuePromise<HTMLElement>

Waits until an element exists, then returns the element.
Internally, a MutationObserver that reacts to any DOM tree change is used. This observer does not react to attribute-only DOM updates.
Option markAsSeen should be set to true if you’re using this method inside a while(true) loop.
Options condition, reduxCondition and reduxEvents should be used as optimizations, in order to avoid multiple calls to document.querySelector when it’s guaranteed the element will not exist yet.

addon.tab.displayNoneWhileDisabled

ParameterTypeRequiredDescription
elementHTMLElementYesElement to hide
optionsObjectNo
PropertyTypeRequiredDefaultDescription
displayStringNo""The display CSS value to use when the addon is enabled.

Hides the given element with display: none when the addon is disabled, until it is reenabled.
If the intended display CSS property value for the provided element when visible is not the default value for the type of provided element (for example, block for divs and inline for spans), you should provide that value inside the options parameter.
If you want to manually hide the element in situations where the addon is enabled, you should use a dedicated class name for that, instead of manually setting el.style.display = "none";. Use a class name selector in a userstyle to set display: none !important; on the element.

addon.tab.copyImage

Required manifest permissionsclipboardWrite
ParameterTypeRequiredDescription
dataURLStringYesData URL of a PNG image.
Return valuePromise<void>
Promise rejects ifImage could not be copied.

Copies a PNG image to the clipboard.
Only run this in response of the user explicitly pressing Ctrl+C.
Internally uses browser.clipboard.setImageData in Firefox and navigator.clipboard.write in Chrome and Edge.

addon.tab.scratchClass

ParameterTypeRequiredDescription
unhashedClassNameStringMin 1One or many unhashed Scratch stylesheet class names, as one argument each.
optsObjectNo
PropertyTypeRequiredDescription
othersString | String[]YesNon-Scratch class(es) to merge
Return valueString

Gets the hashed class name for a Scratch stylesheet class name.

addon.tab.scratchMessage

ParameterTypeRequiredDescription
keyStringYesThe Scratch translation key.
Return valueString | ""

Gets Scratch translation from the current Scratch tab.
Note that these are Scratch locales, not Scratch Addons locales.
If the message isn’t found, "" is returned and a warning is logged in the console.
Internally uses window.django.gettext or window._messages.

addon.tab.appendToSharedSpace

See addon.tab.appendToSharedSpace.

addon.tab.createModal

ParameterTypeRequiredDescription
titlestringYesThe title of the modal.
optionsobjectNo
ParameterTypeDefaultDescription
isOpenBooleanfalseWhether to open the modal by default.
useEditorClassesBooleanfalseIf in the editor, whether to apply the editor styles instead of the scratch-www ones.
useSizesClassBooleanfalseIf on scratch-www, whether to add the modal-sizes class.
Return valueObject

Returns a blank modal using Scratch’s styles. The modal’s properties are listed below.

PropertyTypeDescription
containerHTMLElementThe container element.
contentHTMLElementWhere the content should be appended.
backdropHTMLElementThe modal overlay.
closeButtonHTMLElementThe close (X) button on the header.
openFunctionOpens the modal.
closeFunctionCloses the modal.
removeFunctionRemoves the modal, making it no longer usable.

addon.tab.confirm

ParameterTypeRequiredDescription
titlestringYesThe title of the modal.
messagestringYesThe message displayed in the modal.
optionsobjectNo
ParameterTypeDefaultDescription
useEditorClassesBooleanfalseIf in the editor, whether to apply the editor styles instead of the scratch-www ones.
okButtonLabelstring"OK"The label of the button for approving the confirmation.
cancelButtonLabelstring"Cancel"The label of the button for rejecting the confirmation.
Return valuePromise<Boolean>

Similar to window.confirm, except it’s asynchronous and uses Scratch’s styles.

addon.tab.prompt

ParameterTypeRequiredDescription
titlestringYesThe title of the modal.
messagestringYesThe message displayed in the modal.
defaultValuestringNoThe initial value of the text box.
optionsobjectNo
ParameterTypeDefaultDescription
useEditorClassesBooleanfalseIf in the editor, whether to apply the editor styles instead of the scratch-www ones.
Return valuePromise<string | null>

Similar to window.prompt, except it’s asynchronous and uses Scratch’s styles.

addon.tab.createBlockContextMenu

ParameterTypeRequiredDescription
blockContextMenuCallbackFunctionYesReturns new menu items.
ParameterTypeDescription
itemsObject[]The items added by vanilla code or other addons.
PropertyTypeDescription
enabledBooleanWhether the item is enabled or not.
textStringThe context menu item label.
callbackFunctionThe function that is called when the item is clicked.
separatorBooleanWhether to add a separator above the item or not.
blockObjectThe targeted block, if any.
conditionsObjectNoShow the context menu item in various locations.
PropertyTypeRequiredDefaultDescription
workspaceBooleanNofalseThe workspace context menu.
blocksBooleanNofalseThe block context menu outside the flyout.
flyoutBooleanNofalseThe block context menu inside the flyout.
commentsBooleanNofalseThe context menu on comments.

Adds a context menu item for any of the context menus in the code editor.

addon.tab.createEditorContextMenu

Documentation for this is a WIP. Not all possible types are listed for some settings.

ParameterTypeRequiredDescription
callbackFunctionYesThe function that is executed when the item is clicked.
ParameterTypeDescription
contextObjectThe context for the action.
PropertyTypeDescription
typeStringThe type of the context menu. Possible values: "sprite", "costume", "sound"
menuItemHTMLElementThe item element.
targetHTMLElementThe element that this context menu is selecting.
indexNumberThe index, if applicable.
optionsObjectNo (but then it must be returned in `callback`)
PropertyTypeRequiredDefaultDescription
classNameStringYesThe class name to add to the item.
typesString[]NoAll possible valuesWhich types of context menu the item should be added to. Possible values: "sprite", "costume", "sound"
positionStringYesThe shared space inside of the context menu that the item should be added to. Uses `addon.tab.appendToSharedSpace` internally. Possible values: "assetContextMenuAfterExport", "assetContextMenuAfterDelete", "monitor"
orderNumberYesThe order of the item within its shared space in relation to other items.
labelStringYesThe label for the item.
borderBooleanNofalseWhether to add a border to the top of the item or not.
dangerousBooleanNofalseWhether to display the item as "dangerous" (orange-colored) or not.
conditionFunctionNotrueA function that determines if the item should be shown.
ParameterTypeDescription
contextObjectThe context for the action.
PropertyTypeDescription
typeStringThe type of the context menu. Possible values: "sprite", "costume", "sound"
menuItemHTMLElementThe item element.
targetHTMLElementThe element that this context menu is selecting.
indexNumberThe index, if applicable.

Adds a context menu item for any of the non-Blockly context menus, such as the context menu for the sprites list.

addon.tab.addBlock

Do not use this unless you are adding blocks to the debugger addon.

ParameterTypeRequiredDescription
proccodeStringYesThe name that will be used to refer to the block internally. Must specify inputs on the block (if any) using %s (string), %n (number-only), and %b (boolean).
blockDataObjectYes
PropertyTypeRequiredDefaultDescription
argsString[]YesA list of names that will be used to refer to the block's inputs in the callback. If there are no inputs, use an empty array.
displayNameStringnoThe value of `proccode`The name that will be displayed on the block to the user. Must also include block input syntax.
callbackFunctionYesThe function that will execute when the block runs.
ParameterDescription
argsAn object containing the values that are entered into the block inputs. The keys correpond to the `args` property specified earlier.
threadA reference to the thread that this block is running in.
hiddenBooleanNofalseWhether the block should appear in the flyout or not. This does not affect the workspace.

Adds a new block to the Debugger category in the block palette.

addon.tab.removeBlock

ParameterTypeRequiredDescription
proccodeStringYesThe `proccode` value of the block to remove

Removes a block that was previously added to the Debugger category in the block palette.

addon.tab.loadScript

In most cases, you should use the userscripts property of the addon manifest instead.

ParameterTypeRequiredDescription
pathStringYesThe path pointing to the script.
Return valuePromise

Runs the specified script file.

addon.tab.loadWorker

ParameterTypeRequiredDescription
pathStringYesThe path pointing to the worker.
Return valuePromise<Worker>

Loads the specified Web Worker.

Events

urlChange

Event detail propertyTypeDescription
oldUrlStringThe URL before it was dynamically changed
newUrlStringThe new current URL value

Fires when Scratch dynamically changes the URL of the page.
This happens when going inside/outside the editor, or switching tabs in scratch-www studio pages.
This will not fire if location.hash changed.


Section Pages