Scripting-Überblick

Guida enthält eine vollständige Scripting-Umgebung für Browserautomatisierung. Skripte interagieren mit Seiten, verwalten Daten und orchestrieren Workflows über die g.*-API.

Skript-Engines

Drei Engines stehen zur Verfügung:

JavaScript (ClearScript V8) - ES2024+, Top-Level-await, native Promises und ES-Modul-Imports über dieselbe V8-Engine wie Chrome und Node.js.
Lua (LuaCSharp) - eine klare, tabellenbasierte API mit normaler Lua-Syntax und Arbeitsbereichsbibliotheken über require().
Janet (JanetSharp) - ein funktionaler Lisp-Dialekt mit unveränderlichen Datenstrukturen und integrierter PEG-Engine.

Alle drei Engines verwenden dieselbe g.*-API-Oberfläche.

Grundstruktur und Top-Level-await

Viele Automatisierungsaufgaben sind asynchron. Guida unterstützt Top-Level-await für Skripte, die kein frühes return brauchen:

const tabs = g.tabs.getTabs();
g.log("Offene Tabs: " + tabs.length);

Wenn ein Skript früh abbrechen oder return nutzen soll, kapseln Sie den Code in async function main() und rufen am Ende await main(); auf.

Mit F5 wird das Skript im Editor ausgeführt.

Fehlerbehandlung

In JavaScript und Janet geben g.*-Methoden Werte direkt zurück und werfen bei Fehlern Ausnahmen:

try {
  await g.dom.click("#submit");
} catch (e) {
  g.log("Klick fehlgeschlagen: " + e.message);
  return;
}

Lua nutzt idiomatische Mehrfachrückgaben (nil, error), damit der Visual-Studio-Debugger bei der Entwicklung nicht auf “unbehandelte” Ausnahmen stoppt:

local success, err = g.nav.navigateToUrl("https://example.com")
if not success then
    g.log("Fehler: Navigation fehlgeschlagen: " .. err)
else
    g.log("Seite erfolgreich geladen")
end

Asynchrone Methoden

In JavaScript verwenden Sie await. In Lua und Janet werden Aufrufe durch die Engine automatisch erwartet.

async function main() {
  await g.nav.navigateToUrl("https://example.com");
  await g.dom.waitForDomStable();
  const html = await g.page.getDom();
  g.log("Seite geladen, DOM-Länge: " + html.length);
}

g.nav.navigateToUrl("https://example.com")
g.dom.waitForDomStable()
local html = g.page.getDom()
g.log("Seite geladen, DOM-Länge: " .. #html)

(g.nav.navigateToUrl "https://example.com")
(g.dom.waitForDomStable)
(def html (g.page.getDom))
(g.log (string "Seite geladen, DOM-Länge: " (length html)))

Gemeinsame Bibliotheken

Guida erlaubt wiederverwendbare Funktionen in gemeinsamen Dateien.

JavaScript

Nutzen Sie normale ES-import/export-Syntax. Pfade werden relativ zum aufrufenden Skript aufgelöst, mit Fallback auf den Arbeitsbereich.

export async function loginToApp(username, password) {
  await g.nav.navigateToUrl("https://example.com/login");
  await g.dom.enterText("#user", username);
  await g.dom.enterText("#pass", password);
  await g.dom.click("#submit");
}

import { loginToApp } from "./lib/helpers.js";

await loginToApp("admin", "secure123");
const data = await g.dom.extractContent(".stats");
g.log("Dashboard-Daten: " + data);

Lua

Lua verwendet require(). Guida sucht Module im lib/-Ordner des Arbeitsbereichs sowie in lib/ und scripts/ des aktuellen Workflows.

local utils = require("utils")
utils.hello()

Janet

Janet lädt Module mit import aus den lib/- und scripts/-Ordnern.

(import utils)
(utils/hello)

Pragmas

Mit // @timeout 60000 setzen Sie ein Skript-Timeout in Millisekunden. Der Standardwert ist 10 Sekunden.

Mit // @require-context markieren Sie Skripte, die nur in einem Worker-Kontext laufen dürfen, weil sie g.worker.getContext() benötigen. Wird ein solches Skript standalone ausgeführt, schlägt es sofort mit einer klaren Fehlermeldung fehl. Details stehen unter Warteschlangen und Prüfung.

Logging und Editor

g.log() schreibt in das Console-Panel:

g.log("Verarbeite Element: " + item.name);

Der integrierte Editor bietet IntelliSense, Signaturhilfe, Hover-Dokumentation, Suchen/Ersetzen, Klammerabgleich, Einrückungshilfen und Chrome-DevTools-Debugging für .js-Dateien. Mit Debug starten Sie eine externe Chrome-DevTools-Instanz, die direkt mit der V8-Engine verbunden ist.

Einige Websites erkennen automatisierte Browser. Nutzen Sie stealth: true, um vor dem Laden von Seitenskripten Anti-Erkennungs-Patches einzuschleusen:

await g.nav.navigateToUrl("https://example.com", { stealth: true });

Für feinere Kontrolle können einzelne StealthOptions aktiviert oder deaktiviert werden. JavaScript-basierte Weiterleitungen lassen sich mit { detectRedirects: true } erkennen. Die Details stehen in der API-Referenz.

Lua- und Janet-Unterschiede

Lua verwendet den Punktoperator für alle g.*-Aufrufe, zum Beispiel g.dom.click("#btn"). Verwenden Sie nicht den Doppelpunktoperator g.dom:click, weil die Methoden direkt an C#-Dienste gebunden sind und kein self-Argument erwarten.

Janet verwendet S-Expressions: statt g.dom.click("#btn") schreiben Sie (g.dom.click "#btn"). Objekte aus API-Aufrufen kommen als Dictionary zurück und werden mit get oder get-in gelesen.

Nächste Schritte

API-Referenz - vollständige Methodenliste für alle g.*-Namespaces
Rezepte - praktische Skripte aus echten Beispielen
Arbeitsbereiche - Skripte, Daten und Konfiguration in Arbeitsbereichsordnern organisieren
Schnellstart - praktische Fünf-Minuten-Einführung