Skip to main content

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
function main() {
    var result = readAllUIConfig2("UI example", false);
    logd(result);
    logd(JSON.stringify(result));
}

main();
  • Global config return value
{"__from_global__":true,"Input":"Input content","MultiSelect":["Option 3"],"Dropdown":"Option 1"}
  • Per-device return value
{"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}
function main() {
    var result = clickPoint(100, 100);
    if (result) {
        logd("Click succeeded");
    } else {
        logd("Click failed");
    }
}

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}
function main() {
    var result = longClickPoint(100, 100);
    if (result) {
        logd("Click succeeded");
    } else {
        logd("Click failed");
    }
}

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}
function main() {
    var result = doubleClickPoint(100, 100);
    if (result) {
        logd("Click succeeded");
    } else {
        logd("Click failed");
    }
}

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
function main() {
    var result = press(100, 100, 5000);
    if (result) {
        logd("Long press succeeded");
    } else {
        logd("Long press failed");
    }
}

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}
function main() {
 // First style: array-based
 var touch1 = [
 {"action": 0, "x": 500, "y": 1200, "pointer": 1, "delay": 1},
 {"action": 2, "x": 500, "y": 1100, "pointer": 1, "delay": 20},
 {"action": 2, "x": 500, "y": 1000, "pointer": 1, "delay": 20},
 {"action": 1, "x": 1, "y": 1, "pointer": 1, "delay": 2}
 ]
 // Second style: chained calls
 var touch1 = MultiPoint
 .get()
 .action(0).x(500).y(1200).pointer(1).delay(100)
 .next()
 .action(2).x(500).y(1100).pointer(1).delay(100)
 .next()
 .action(2).x(500).y(1000).pointer(1).delay(100)
 .next()
 .action(2).x(500).y(900).pointer(1).delay(100)
 .next()
 .action(1).x(500).y(800).pointer(1).delay(100);
 var touch2 = MultiPoint
 .get()
 .action(0).x(300).y(1200).pointer(2).delay(100)
 .next()
 .action(2).x(300).y(1100).pointer(2).delay(100)
 .next()
 .action(2).x(300).y(1000).pointer(2).delay(100)
 .next()
 .action(2).x(300).y(900).pointer(2).delay(100)
 .next()
 .action(1).x(300).y(800).pointer(2).delay(100);
 var x = multiTouch(touch1, touch2, null, null, null, 30000);
 logd("xxs " + x);
}

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
function main() {
 var result = swipeToPoint(10, 10, 100, 100, 200);
 if (result) {
 logd("Swipe succeeded");
 } else {
 logd("Swipe failed");
 }
}

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
function main() {
 var result = drag(10, 10, 100, 100, 200);
 if (result) {
 logd("Drag succeeded");
 } else {
 logd("Drag failed");
 }
}

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
function main() {
 var result = inputText("My content");
 if (result) {
 logd("Yes");
 } else {
 logd("No");
 }
}

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
function main() {
 var result = combineKeys(2022, 0, 0);
 if (result) {
 logd("Yes");
 } else {
 logd("No");
 }
}

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}
function main() {
 let x = setOrientation(1)
 logd(x)

}

main();

getOrientation Get screen orientation​

  • Get screen orientation
  • Requires EC HarmonyOS Next 1.0.0+
  • @return int | 1 = portrait, 2 = landscape (90° clockwise))
function main() {
 let x = getOrientation()
 logd(x)
}

main();

lockNode Lock current node​

  • Lock current node; after lock, node info stays stale on UI refresh until releaseNode
function main() {
 logd("Lock node...")
 // Lock node; UI refresh does not change it
 console.time("1")
 lockNode()
 for (let i = 0; i < 10; i++) {
 let n = text("Settings").getOneNodeInfo(1000)
 logd("lock " + n)
 }
 logd("Release node lock...")
 // Release node lock
 releaseNode()
 logd(console.timeEnd("1"))

 console.time("1")
 for (var i = 0; i < 10; i++) {
 let n = text("Settings").getOneNodeInfo(1000)
 logd("unlocked " + n)
 }
 logd(console.timeEnd("1"))
 // Locked fetch is noticeably faster
}

main();

releaseNode Release node lock​

  • Release node lock; node info updates on next UI refresh
function main() {
 logd("Lock node...")
 // Lock node; UI refresh does not change it
 console.time("1")
 lockNode()
 for (let i = 0; i < 10; i++) {
 let n = text("Settings").getOneNodeInfo(1000)
 logd("lock " + n)
 }
 logd("Release node lock...")
 // Release node lock
 releaseNode()
 logd(console.timeEnd("1"))

 console.time("1")
 for (var i = 0; i < 10; i++) {
 let n = text("Settings").getOneNodeInfo(1000)
 logd("unlocked " + n)
 }
 logd(console.timeEnd("1"))
 // Locked fetch is noticeably faster
}

main();

System Key Functions​

home Go to home screen​

  • Go to home screen
  • @return {null|Boolean}
function main() {
 var result = home();
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

main();

reboot Reboot device​

  • Reboot device
  • @return {null|Boolean}
function main() {
 var result = reboot();
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

main();

lock Lock screen​

  • Lock screen
  • @return {null|Boolean}
function main() {
 var result = lock();
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

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}
function main() {
 var result = unlock();
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

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
function main() {
 var result = openApp("com.tencent.wechat");
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

main();

openUrl Open URL​

  • Open URL
  • @param url URL
  • @return {boolean} true on success, false on failure
function main() {
 var r = openUrl("http://baidu.com");
 logd(r)
}

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
function main() {
 var result = stopApp("com.tencent.wechat");
 if (result) {
 logd("Success");
 } else {
 logd("Failed");
 }
}

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
function main() {
 var result = installApp("c:/a.hap");
 logd("result " + result);
 if (result === "ok") {
 logd("Success");
 } else {
 logd("Failed");
 }
}

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
function main() {
 var result = uninstallApp("com.test.wechat");
 logd("result " + result);
 if (result === "ok") {
 logd("Success");
 } else {
 logd("Failed");
 }
}

main();

other Functions​

reconnectUsb Reconnect USB​

  • Flash-disconnect USB and reconnect (like unplugging cable)
  • @return {boolean} true on success, false on failure
function main() {
 var result = reconnectUsb();
 logd(result);
}

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
function main() {
 var result = isReleaseIec();
 logd(result)
}

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
function main() {
 setAgentTimeout(10000, 3000);
}

main();

activeAppInfo Current running app bundle ID​

  • @param Current running app bundleId
  • @return {string} current running app bundleId
function main() {
 let d = activeAppInfo();
 logd(d);
}

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
function main() {
 let d = getLastToast(5000);
 logd(d);
}

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
function main() {
 let d = uploadInsertImage("D:/a.jpg");
 logd(d);
}

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
function main() {
 let d = uploadInsertVideo("D:/a.mp4");
 logd(d);
}

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
function main() {
 // List all files under /
 let d = pushFile("c:\\a.jpg", "/data/local/tmp/");
 logd(d);
}

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
function main() {
 // Pull file to local machine
 let d = pullFile("/data/local/tmp/a.txt", "c:\\bb.txt");
 logd(d);

}

main();