Gear add-on engine is a new high-performance mobile Userscript engine that is compatible with Tampermonkey and Greasemonkey Userscript.
The basic Userscript demo
// ==UserScript==
// @name {{name}}
// @version 0.1
// @description New Userscript
// @author You
// @match *
// @run-at document-end
// @grant none
// ==/UserScript==
(function() {
'use strict';
// Your code here...
})();
Userscript headers
-
@name
The name of the Userscript.
-
@namespace
The namespace of the Userscript.
-
@version
The version of Userscript. This number should be increased to indicate the script had changed, so Gear will decide whether an update or not according to this value.
-
@author
The author is the name of the Userscript. It will appear on the script's detail view.
-
@description
The description of the Userscript. It will appear from the add-on list.
-
@homepage
The script homepage URL for the user to visit.
-
@icon
The icon of the Userscript. It will appear from the add-on list.
-
@icon64
The high-quality icon of the Userscript. Gear will prefer using this value to display the icon if set.
-
@updateURL
The URL for updating the script. Gear will prefer using this value for checking the new version.
-
@downloadURL
The URL for downloading the script. Gear will use this value for checking the new version if @updateURL is not set. If this value is also null, Gear will choose the first-time install URL as the update URL for updating.
-
@supportURL
The support link for the user to contact.
-
@run-at
Defines when the script is injected.
-
document-start
The script will be injected as fast as possible.
-
document-body
The script will be injected if the body element exists.
-
document-end
The script will be injected when or after the DOMContentLoaded event was dispatched.
-
document-idle
The script will be injected after the DOMContentLoaded event was dispatched. This is the default value if no @run-at tag is given.
-
context-menu
The script will be injected if it is clicked at the browser context menu.
-
-
@include
The URL matching patterns that the script will run. Gear will prefer using this value for matching.
Matches any URL that uses the http scheme
// @include http://*/*
Will match: http://foo.bar/ http://example.org/foo/bar.html
Matches any URL that uses the HTTP scheme, on any host, as long as the path starts with /foo.
// @include http://*/foo*
Will match: http://example.com/foo/bar.html http://abc.com/foo
Matches any URL that starts with http or https for foo.bar.
// @include *://foo.bar/
Will match: http://foo.bar/ https://foo.bar
-
@match
Like the same as @include. Gear will use this value if @include is not set.
-
@exclude
The URL matching patterns that the script should not run. The pattern rule is the same as @include.
-
@require
The JavaScript file will be loaded and executed before the script starts running.
// @require https://code.jquery.com/jquery-2.1.4.min.js // @require https://foo.bar/your_packing.js
-
@connect
The allowed domain for GM_xmlHttpRequest.
-
@grant
The allowlist for GM_* and GM.* functions and APIs. Please read the following grant list for more details.
// @grant GM_setValue // @grant GM_getValue // @grant GM_setClipboard // @grant unsafeWindow
Grant List
unsafeWindow
The shadow window object for full access to the page's JavaScript functions and variables.
Storage
Set value to the storage.
GM_setValue(name, value) : void
GM.setValue(name, value) : Promise
Get value from the storage. You can provide a default value if nothing is found from the storage.
GM_getValue(name, defaultValue) : any
GM.getValue(name, defaultValue) : Promise
Delete a value from the storage.
GM_deleteValue(name) : void
GM.deleteValue(name) : Promise
List all values from the storage.
GM_listValues() : array
GM.listValues() : Promise
Add a value listener to detect value change, and return the listenerId that you can remove it by calling GM_removeValueChangeListener(listenerId)
.
GM_addValueChangeListener(name, function(name, oldValue, newValue, isRemote)) : string
Remove the value listener by listenerId.
GM_removeValueChangeListener(listenerId)
Insert a new CSS style to head element.
GM_addStyle(style) : void
GM.addStyle(style) : void
Insert a new element to the document or parent node, and returns the element itself.
GM_addElement(parentNode, tagName, attributes) : node
GM_addElement(tagName, attributes) : node
GM_addElement('script', {
src: 'https://abc.com/script.js',
type: 'text/javascript'
});
GM_addElement(
document.head,
'script',
{
src: 'https://abc.com/script.js',
type: 'text/javascript'
}
);
Output log message to the console.
GM_log(message) : void
GM.log(message) : void
Get the raw content predefined from @resource.
GM_getResourceText(name) : String
Get the base64 encoded URI predefined from @resource.
GM_getResourceURL(name) : any
GM.getResourceUrl(name) : Promise
Register a menu command that can access from the running add-on menu.
GM_registerMenuCommand(name, fn, accessKey) : int
GM.registerMenuCommand(name, fn, accessKey) : int
Unregister the menu command by its id.
GM_unregisterMenuCommand(id) : void
GM.unregisterMenuCommand(id) : void
Open a new tab with options.
GM_openInTab(url, options) : TabObject
GM_openInTab(url, loadInBackground) : TabObject
TabObject = {'closed': Bool, 'onclose': Function, 'close': Function}
Create a new xmlHttpRequest.
GM_xmlHttpRequest(options) : void
GM.xmlHttpRequest(options) : void
Create a new download task.
GM_download(options), GM_download(url, name) : void
Set value to the clipboard.
GM_setClipboard(data, info = 'text|html') : void
GM.setClipboard(data, info = 'text|html') : void
Get the tab object.
// This function is unsupported.
GM_getTab
Save the tab object.
// This function is unsupported.
GM_saveTab
Send notification.
// This function is unsupported.
GM_notification
Get script information.
console.log(GM_info)
[
"script": [
"uuid": string,
"name": string,
"author": string,
"description": string,
"namespace": string,
"homepage": string,
"version": string,
"icon": string,
"icon64": string,
"excludes": array,
"includes": array,
"matches": array,
"requires": array,
"resources": object,
"run-at": string,
"updateURL": string,
"downloadURL": string,
"supportURL": string,
],
"downloadMode": string = native,
"scriptMetaStr": string,
"scriptSource": string,
"scriptUpdateURL": string,
"scriptHandler": string = Tampermonkey,
"isIncognito": bool,
"version": string
]
Compatibility Issues for iOS
- WKWebView RegExp engine didn't support group lookahead and group lookbehind, like positive lookahead
(?:)
, negative lookahead(?!)
, positive lookbehind(?<=)
and negative lookbehind(?<!)
. You may need to change the RegExp pattern with those. - Check the list of different APIs between Chrome and Safari https://caniuse.com/?compare=chrome+101,safari+15.4&compareCats=HTML5,JS,JS%20API.