auto([mode])

• mode {string} Mode

Checks whether the Accessibility service is enabled. If not, throws an exception and navigates to the Accessibility enable screen; also sets the Accessibility mode to mode. Available values:

• fast Fast mode. Enables widget caching so selectors can retrieve widgets faster. Useful for scripts that require high-speed widget operations.
• normal Normal mode (default).

If mode is omitted, normal mode is used.

Prefer auto.waitFor() and auto.setMode() over this function: if Accessibility is not running, auto() stops the script, while auto.waitFor() will continue after Accessibility is enabled.

Example:

auto("fast");

Example 2:

auto();

auto.waitFor()

Checks whether the Accessibility service is enabled. If not, navigates to the Accessibility enable screen and waits until it starts; once enabled, the script continues.

Because this function blocks, you generally cannot call it in UI mode unless coroutine support is available. In UI mode, prefer auto().

auto.setMode(mode)

• mode {string} Mode

Set the Accessibility mode to mode. Available values:

• fast Fast mode. Enables widget caching so selectors can retrieve widgets faster. Useful for scripts that require high-speed viewing/operations.
• normal Normal mode (default).

auto.setFlags(flags)

[Added in v4.1.0]

• flags {string} | {Array} Flags for enabling/disabling certain features, including:
  • findOnUiThread Run selector searching on the main thread. Intended to mitigate follow-up issues caused by thread-safety problems (though current known issues may not be thread-safety related).
  • useUsageStats Use Usage Stats results to detect the currently running app package name (requires Usage Access permission). If currentPackage() feels inaccurate, try this.
  • useShell Use shell commands to get the current app package/activity name (requires root).

Enable some automator-related features. For example:

auto.setFlags(["findOnUiThread", "useShell"]);

auto.service

[Added in v4.1.0]

• {AccessibilityService}

Get the Accessibility service. Returns null if the service is not running.

See AccessibilityService.

auto.windows

[Added in v4.1.0]

• {Array}

An array of all current windows (AccessibilityWindowInfo), which may include the status bar, IME, current app window, popups, floating windows, split-screen app windows, etc. You can inspect each window’s layout separately.

Requires Android 5.0+.

auto.root

[Added in v4.1.0]

• {UiObject}

The layout root element of the current window. Returns null if Accessibility is not running or if WindowFilter returns false for all windows.

If windowFilter is not set, the “current window” is the active window (focused / being touched). If windowFilter is set, it returns the first window that matches the filter.

On Android < 5.0, it always returns the root element of the active window.

auto.rootInActiveWindow

[Added in v4.1.0]

• {UiObject}

The layout root element of the active window (focused / being touched). null if Accessibility is not running.

auto.setWindowFilter(filter)

[Added in v4.1.0]

• filter {Function} A function that takes a window (AccessibilityWindowInfo) and returns a boolean.

Set a window filter. This filter decides which windows are target windows and affects selector searching. For example, to search in all windows (including status bar / IME), use:

auto.setWindowFilter(function (window) {
  // Always return true: search in this window
  return true;
});

Another example: in split-screen mode with Auto.js and QQ, if you only want to search within the QQ window:

auto.setWindowFilter(function (window) {
  // For app windows, the `title` is the app name, so we can use it to identify the app.
  return window.title == "QQ";
});

By default, selectors only search in the current active window, not in floating windows or the status bar. WindowFilter lets you control which windows are searched.

Note: if WindowFilter returns false for all windows, selector results will be empty.

Also, setWindowFilter() affects auto.windowRoots.

Effective on Android 5.0+.

auto.windowRoots

[Added in v4.1.0]

• {Array}

Returns an array of layout root elements of the windows filtered by WindowFilter.

On Android < 5.0, it always returns an array containing the active window root element.

automator

The automator module provides helper functions to simulate simple actions, such as clicking text or simulating key presses. Some of these functions are also available as globals.

click(text[, i])

• text {string} Text to click
• i {number} If the same text appears multiple times, i indicates which one to click (0-based).

Returns whether the click succeeded. Returns false if the text is not found or its containing region is not clickable; otherwise true.

This function can click most text-containing buttons. It is often used with while to keep trying until it succeeds. Example:

while (!click("Scan"));

If i is omitted, it tries to click all occurrences of text and returns whether all clicks succeeded.

i is 0-based. For example, click("foo", 0) clicks the first "foo", and click("foo", 1) clicks the second.

“Text-containing region” means walking up from the text node to its parent views until a clickable widget is found.

click(left, top, bottom, right)

• left {number} Pixel distance from the rectangle’s left edge to the screen’s left edge
• top {number} Pixel distance from the rectangle’s top edge to the screen’s top edge
• bottom {number} Pixel distance from the rectangle’s bottom edge to the screen’s bottom edge
• right {number} Pixel distance from the rectangle’s right edge to the screen’s right edge

Note: this function is mainly for recorded scripts. In hand-written code, you should generally avoid using it.

Clicks the widget in the specified region. Returns false if no strictly matching region exists on screen or the region is not clickable; otherwise true.

Some buttons/widgets are icons rather than text. In that case you can’t use click(text, i); instead, describe the icon’s region and click it. left/bottom/top/right describe the clickable region.

To locate the region, you can use the layout inspector in the floating window and check the widget’s bounds.

Recorded scripts generated via Accessibility will produce this statement.

longClick(text[, i])

• text {string} Text to long-press
• i {number} If the same text appears multiple times, i indicates which one to long-press (0-based).

Returns whether the long-press succeeded. Returns false if the text is not found or its containing region is not clickable; otherwise true.

If i is omitted, it tries to long-press all occurrences of text and returns whether all operations succeeded.

scrollUp([i])

• i {number} Index of the scrollable widget

Scroll up or swipe left on the ((i+1))-th scrollable widget. Returns whether it succeeded. Returns false if there is no scrollable widget on screen.

If i is omitted, scrollUp() finds the largest scrollable widget and scrolls up / swipes left (e.g. a chat message list).

If i is provided, it scrolls the ((i+1))-th scrollable widget. For example, scrollUp(0) scrolls the first one.

scrollDown([i])

• i {number} Index of the scrollable widget

Scroll down or swipe right on the ((i+1))-th scrollable widget. Returns whether it succeeded. Returns false if there is no scrollable widget on screen.

If i is omitted, it finds the largest scrollable widget and scrolls down / swipes right.

If i is provided, it scrolls the ((i+1))-th scrollable widget. For example, scrollDown(0) scrolls the first one.

setText([i, ]text)

• i {number} The ((i+1))-th input field to fill
• text {string} Text to set

Returns whether the input succeeded. Returns false if the input field is not found.

If i is omitted, it sets all input fields’ text to text. Example: setText("test").

Here, “input” means replacing the field’s text with text, not appending.

input([i, ]text)

• i {number} The ((i+1))-th input field to type into
• text {string} Text to input

Returns whether the input succeeded. Returns false if the input field is not found.

If i is omitted, it appends text to all input fields. Example: input("test").

automator.takeScreenshot()

[Added in Pro 8.8.0]

• Returns {Image}

Take a screenshot using Accessibility permission and return an Image object.

Compared with taking screenshots via the images module (which requires screen-capture permission), this function needs no extra permission, but has the following limitations:

• Screenshot frequency limit: the system allows at most one screenshot per second; otherwise an exception is thrown.
• Requires Android 11+.

$auto.waitFor();
let capture = $automator.takeScreenshot();
$images.save(capture, "../capture.png");

automator.switchToInputMethod(packageName)

[Added in Pro 8.8.0]

• packageName {string} IME package name
• Returns {boolean}

Switch to the specified input method and return whether it succeeded. Possible failure causes:

• The IME for the specified package name does not exist or is not enabled.
• The system reports failure when switching IME.

Requires Android 11+.

// Switch to Sogou IME
$automator.switchToInputMethod("com.sohu.inputmethod.sogou");

automator.headsetHook()

[Added in Pro 8.8.0]

• Returns {boolean}

Simulate the headset hook key. Returns whether it succeeded. Can be used to hang up / answer calls, and play/pause music.

auto.clearCache()

[Added in v9.0.14]

Clear Accessibility cache. If a widget is visible on screen but selectors still cannot find it, the cache may be stale; call auto.clearCache() to clear the widget cache. Starting from v9.0, functions like findOne() may also clear the cache automatically after failing for a long time.

Rect

The object returned by UiObject.bounds() and UiObject.boundsInParent(). Represents a rectangle (region).

Rect.left

• {number}

X coordinate of the rectangle’s left edge.

Rect.right

• {number}

X coordinate of the rectangle’s right edge.

Rect.top

• {number}

Y coordinate of the rectangle’s top edge.

Rect.bottom

• {number}

Y coordinate of the rectangle’s bottom edge.

Rect.centerX()

• Returns {number}

X coordinate of the rectangle center.

Rect.centerY()

• Returns {number}

Y coordinate of the rectangle center.

Rect.width()

• Returns {number}

Rectangle width. Often used as a widget width.

Rect.height()

• Returns {number}

Rectangle height. Often used as a widget height.

Rect.contains(r)

• r {Rect}

Returns whether it contains another rectangle r. “Contains” means r lies inside this rectangle (including overlapping boundaries).

Rect.intersect(r)

• r {Rect}

Returns whether it intersects with another rectangle r.