Global Shortcut Events

Overview

Shortcut events encapsulated in the global module.

Read UI

readAllUIConfig2 Read UI config (new UI)

Read UI parameter config
Configure in designer: Control Center → UI Parameters (New)
Requires EC HarmonyOS Next 1.0.0+
Note: Requires new UI config. Read order: per-device first, then global if empty.
If params contain __from_global__, the value comes from global config
@param tmplName Parameter group name
@param forceGlobal Force global config; true = ignore per-device config
@return {json} JSON data

1
function main() {
2
    var result = readAllUIConfig2("UI example", false);
3
    logd(result);
4
    logd(JSON.stringify(result));
5
}
6

7
main();

Global config return value

1
{"__from_global__":true,"Input":"Input content","MultiSelect":["Option 3"],"Dropdown":"Option 1"}

Per-device return value

1
{"Input":"Input content","MultiSelect":["Option 3"],"Dropdown":"Option 1"}

Click Functions

clickPoint Click by coordinates

Click at coordinates
Requires EC HarmonyOS Next 1.0.0+
@param x X coordinate
@param y Y coordinate
@return {boolean}

1
function main() {
2
    var result = clickPoint(100, 100);
3
    if (result) {
4
        logd("Click succeeded");
5
    } else {
6
        logd("Click failed");
7
    }
8
}
9

10
main();

longClickPoint Long click by coordinates

Long-click at coordinates
Requires EC HarmonyOS Next 1.0.0+
@param x X coordinate
@param y Y coordinate
@return {boolean}

1
function main() {
2
    var result = longClickPoint(100, 100);
3
    if (result) {
4
        logd("Click succeeded");
5
    } else {
6
        logd("Click failed");
7
    }
8
}
9

10
main();

doubleClickPoint Double-click by coordinates

Double-click at coordinates
Requires EC HarmonyOS Next 1.0.0+
@param x X coordinate
@param y Y coordinate
@return {boolean}

1
function main() {
2
    var result = doubleClickPoint(100, 100);
3
    if (result) {
4
        logd("Click succeeded");
5
    } else {
6
        logd("Click failed");
7
    }
8
}
9

10
main();

press Long-press by coordinates

Long-press event
@param x X coordinate
@param y Y coordinate
@param delay Long-press duration in milliseconds
@return {bool} true on success, false on failure

1
function main() {
2
    var result = press(100, 100, 5000);
3
    if (result) {
4
        logd("Long press succeeded");
5
    } else {
6
        logd("Long press failed");
7
    }
8
}
9

10
main();

Multi-touch

multiTouch Multi-touch

Multi-touch
Touch params: action — 0 = down, 1 = up, 2 = move,3 = pause
x: X coordinate
y: Y coordinate
pointer: finger index (1, 2, 3, … for nth finger)
delay: delay in ms before this action runs
@param touch1 First finger touch point array, e.g.: [{"action":0,"x":1,"y":1,"pointer":1,"delay":20},{"action":2,"x":1,"y":1,"pointer":1,"delay":20}]
@param touch2 Second finger touch point array
@param touch3 Third finger touch point array
@param touch4 Fourth finger touch point array
@param touch5 Fifth finger touch point array
@param timeout Multi-touch total timeout in milliseconds
@return {boolean}

1
function main() {
2
 // First style: array-based
3
 var touch1 = [
4
 {"action": 0, "x": 500, "y": 1200, "pointer": 1, "delay": 1},
5
 {"action": 2, "x": 500, "y": 1100, "pointer": 1, "delay": 20},
6
 {"action": 2, "x": 500, "y": 1000, "pointer": 1, "delay": 20},
7
 {"action": 1, "x": 1, "y": 1, "pointer": 1, "delay": 2}
8
 ]
9
 // Second style: chained calls
10
 var touch1 = MultiPoint
11
 .get()
12
 .action(0).x(500).y(1200).pointer(1).delay(100)
13
 .next()
14
 .action(2).x(500).y(1100).pointer(1).delay(100)
15
 .next()
16
 .action(2).x(500).y(1000).pointer(1).delay(100)
17
 .next()
18
 .action(2).x(500).y(900).pointer(1).delay(100)
19
 .next()
20
 .action(1).x(500).y(800).pointer(1).delay(100);
21
 var touch2 = MultiPoint
22
 .get()
23
 .action(0).x(300).y(1200).pointer(2).delay(100)
24
 .next()
25
 .action(2).x(300).y(1100).pointer(2).delay(100)
26
 .next()
27
 .action(2).x(300).y(1000).pointer(2).delay(100)
28
 .next()
29
 .action(2).x(300).y(900).pointer(2).delay(100)
30
 .next()
31
 .action(1).x(300).y(800).pointer(2).delay(100);
32
 var x = multiTouch(touch1, touch2, null, null, null, 30000);
33
 logd("xxs " + x);
34
}
35

36
main();

Swipe Functions

swipeToPoint Swipe between coordinate points

Swipe from one coordinate to another
@param startX Start X coordinate
@param startY Start Y coordinate
@param endX End X coordinate
@param endY End Y coordinate
@param speed Swipe speed; lower = slower
@return Boolean true Swipe succeeded, false Swipe failed

1
function main() {
2
 var result = swipeToPoint(10, 10, 100, 100, 200);
3
 if (result) {
4
 logd("Swipe succeeded");
5
 } else {
6
 logd("Swipe failed");
7
 }
8
}
9

10
main();

Drag Functions

drag Drag coordinates

Drag from one coordinate to another
@param startX Start X coordinate
@param startY Start Y coordinate
@param endX End X coordinate
@param endY End Y coordinate
@param speed Swipe speed; lower value = slower
@return Boolean true Drag succeeded, false Drag failed

1
function main() {
2
 var result = drag(10, 10, 100, 100, 200);
3
 if (result) {
4
 logd("Drag succeeded");
5
 } else {
6
 logd("Drag failed");
7
 }
8
}
9

10
main();

Input Data

inputText Input text

Enter text
Requires EC HarmonyOS Next 1.0.0+
Input method notes: ASCII characters can use key injection; non-ASCII content is written to the focused field via clipboard + paste. Set the device IME to the system default. Third-party IMEs (e.g. iFlytek) may only copy to clipboard when the soft keyboard is open — switch back to the system IME. With a Bluetooth HID keyboard the system often skips the soft keyboard and agent input is more stable; for reliable Chinese with a third-party IME, use Bluetooth HID input (e.g. bleEvent).
@param content Content
@return {bool} true on success, false on failure

1
function main() {
2
 var result = inputText("My content");
3
 if (result) {
4
 logd("Yes");
5
 } else {
6
 logd("No");
7
 }
8
}
9

10
main();

combineKeys Combined key input

Requires EC HarmonyOS Next 1.0.0+
See key codes
@param key1 Key 1
@param key2 Key 2; default 0
@param key3 Key 3; default 0
@return boolean | true on success, false on failure

1
function main() {
2
 var result = combineKeys(2022, 0, 0);
3
 if (result) {
4
 logd("Yes");
5
 } else {
6
 logd("No");
7
 }
8
}
9

10
main();

Screen Orientation

setOrientation Set screen orientation

Set orientation; landscape supports 90° clockwise only
Requires EC HarmonyOS Next 1.0.0+
@param orientation 1 = portrait, 2 = 90° clockwise landscape
@return {boolean}

1
function main() {
2
 let x = setOrientation(1)
3
 logd(x)
4

5
}
6

7
main();

getOrientation Get screen orientation

Get screen orientation
Requires EC HarmonyOS Next 1.0.0+
@return int | 1 = portrait, 2 = landscape (90° clockwise))

1
function main() {
2
 let x = getOrientation()
3
 logd(x)
4
}
5

6
main();

lockNode Lock current node

Lock current node; after lock, node info stays stale on UI refresh until releaseNode

1
function main() {
2
 logd("Lock node...")
3
 // Lock node; UI refresh does not change it
4
 console.time("1")
5
 lockNode()
6
 for (let i = 0; i < 10; i++) {
7
 let n = text("Settings").getOneNodeInfo(1000)
8
 logd("lock " + n)
9
 }
10
 logd("Release node lock...")
11
 // Release node lock
12
 releaseNode()
13
 logd(console.timeEnd("1"))
14

15
 console.time("1")
16
 for (var i = 0; i < 10; i++) {
17
 let n = text("Settings").getOneNodeInfo(1000)
18
 logd("unlocked " + n)
19
 }
20
 logd(console.timeEnd("1"))
21
 // Locked fetch is noticeably faster
22
}
23

24
main();

releaseNode Release node lock

Release node lock; node info updates on next UI refresh

1
function main() {
2
 logd("Lock node...")
3
 // Lock node; UI refresh does not change it
4
 console.time("1")
5
 lockNode()
6
 for (let i = 0; i < 10; i++) {
7
 let n = text("Settings").getOneNodeInfo(1000)
8
 logd("lock " + n)
9
 }
10
 logd("Release node lock...")
11
 // Release node lock
12
 releaseNode()
13
 logd(console.timeEnd("1"))
14

15
 console.time("1")
16
 for (var i = 0; i < 10; i++) {
17
 let n = text("Settings").getOneNodeInfo(1000)
18
 logd("unlocked " + n)
19
 }
20
 logd(console.timeEnd("1"))
21
 // Locked fetch is noticeably faster
22
}
23

24
main();

System Key Functions

home Go to home screen

Go to home screen
@return {null|Boolean}

1
function main() {
2
 var result = home();
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

reboot Reboot device

Reboot device
@return {null|Boolean}

1
function main() {
2
 var result = reboot();
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

lock Lock screen

Lock screen
@return {null|Boolean}

1
function main() {
2
 var result = lock();
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

unlock Unlock screen

Unlock screen; must not have password, etc.
Simulated swipe; HarmonyOS Next does not have native unlock
Requires EC HarmonyOS Next 1.0.0+
@return {null|Boolean}

1
function main() {
2
 var result = unlock();
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

openApp Open app by bundle ID

Open app by bundle ID
@param bundleId App bundle ID
@return {boolean} true on success, false on failure

1
function main() {
2
 var result = openApp("com.tencent.wechat");
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

openUrl Open URL

Open URL
@param url URL
@return {boolean} true on success, false on failure

1
function main() {
2
 var r = openUrl("http://baidu.com");
3
 logd(r)
4
}
5

6
main();

stopApp Stop app by bundle ID

Stop app by bundle ID
@param bundleId App bundle ID
@return {boolean} true on success, false on failure

1
function main() {
2
 var result = stopApp("com.tencent.wechat");
3
 if (result) {
4
 logd("Success");
5
 } else {
6
 logd("Failed");
7
 }
8
}
9

10
main();

installApp Install app by path

Install app by path
@param path HAP path on the same PC as the bridge
@return {string} “ok” = success; other string = failure

1
function main() {
2
 var result = installApp("c:/a.hap");
3
 logd("result " + result);
4
 if (result === "ok") {
5
 logd("Success");
6
 } else {
7
 logd("Failed");
8
 }
9
}
10

11
main();

uninstallApp Uninstall app by bundle ID

Uninstall app by bundle ID (automation not required)
@param bundleId App bundle ID
@return {string} “ok” = success; other string = failure

1
function main() {
2
 var result = uninstallApp("com.test.wechat");
3
 logd("result " + result);
4
 if (result === "ok") {
5
 logd("Success");
6
 } else {
7
 logd("Failed");
8
 }
9
}
10

11
main();

other Functions

reconnectUsb Reconnect USB

Flash-disconnect USB and reconnect (like unplugging cable)
@return {boolean} true on success, false on failure

1
function main() {
2
 var result = reconnectUsb();
3
 logd(result);
4
}
5

6
main();

isReleaseIec Whether script is release version

Check whether script is release version
Requires EC HarmonyOS Next 2.8.0+
@return {boolean} true = release, false = debug

1
function main() {
2
 var result = isReleaseIec();
3
 logd(result)
4
}
5

6
main();

setAgentTimeout Set agent request timeout

@param envTimeout Automation startup timeout (ms); 10000–15000
@param readTimeout other request timeout (ms); 2000–5000
@return {boolean} true on success

1
function main() {
2
 setAgentTimeout(10000, 3000);
3
}
4

5
main();

activeAppInfo Current running app bundle ID

@param Current running app bundleId
@return {string} current running app bundleId

1
function main() {
2
 let d = activeAppInfo();
3
 logd(d);
4
}
5

6
main();

getLastToast Get toast data

Get toast data
[Automation must be started]
Requires EC HarmonyOS Next 1.2.0+
@param timeout Timeout in milliseconds
@return {string} JSON string

1
function main() {
2
 let d = getLastToast(5000);
3
 logd(d);
4
}
5

6
main();

Gallery Operations

uploadInsertImage Insert image into gallery

Insert image into gallery
HarmonyOS Next gallery and files are isolated; this pushes to File Manager only
After push, File Manager opens; use a script to share image/video to Gallery
Method 1 (single): File Manager → Recent → Share → Save to Gallery
Method 2 (batch): File Manager → Browse → Download → multi-select → Share → Save to Gallery
Requires EC HarmonyOS Next 1.0.0+
@param localPath Local file path on PC
@return {boolean} true on success, false on failure

1
function main() {
2
 let d = uploadInsertImage("D:/a.jpg");
3
 logd(d);
4
}
5

6
main();

uploadInsertVideo Insert video into gallery

Insert video into gallery
HarmonyOS Next gallery and files are isolated; this pushes to File Manager only
After push, File Manager opens; use a script to share image/video to Gallery
Method 1 (single): File Manager → Recent → Share → Save to Gallery
Method 2 (batch): File Manager → Browse → Download → multi-select → Share → Save to Gallery
Requires EC HarmonyOS Next 1.0.0+
@param localPath Local file path on PC
@return {boolean} true on success, false on failure

1
function main() {
2
 let d = uploadInsertVideo("D:/a.mp4");
3
 logd(d);
4
}
5

6
main();

File Operations

pushFile Push file

Push local PC file to remote device
Requires EC HarmonyOS Next 1.0.0+
@param localPath Local file path on PC
@param remotePath Remote path on device
@return {boolean} true on success, false on failure

1
function main() {
2
 // List all files under /
3
 let d = pushFile("c:\\a.jpg", "/data/local/tmp/");
4
 logd(d);
5
}
6

7
main();

pullFile Pull file

Pull remote file to local PC
Requires EC HarmonyOS Next 1.0.0+
@param localPath Local file path on PC
@param remotePath Remote path on device
@return {boolean} true on success, false on failure

1
function main() {
2
 // Pull file to local machine
3
 let d = pullFile("/data/local/tmp/a.txt", "c:\\bb.txt");
4
 logd(d);
5

6
}
7

8
main();