Vue d'ensemble du scripting

Guida inclut un environnement de scripting complet pour l’automatisation du navigateur. Les scripts interagissent avec les pages, gèrent des données et orchestrent des flux de travail via l’API g.*.

Moteurs de script

Trois moteurs sont disponibles :

• JavaScript (ClearScript V8) — compatibilité ES2024+, top-level await, Promises natives et imports de modules ES. Utilise le même moteur V8 que Chrome et Node.js.
• Lua (LuaCSharp) — API propre basée sur des tables avec la syntaxe Lua standard. Entièrement intégré aux bibliothèques de l’espace de travail via require().
• Janet (JanetSharp) — dialecte Lisp fonctionnel et expressif, avec structures de données immuables et puissant moteur PEG intégré.

Les trois moteurs partagent la même surface API g.*.

Pourquoi Janet ?

JavaScript est excellent par sa familiarité, mais Guida inclut Janet pour les utilisateurs qui préfèrent un dialecte Lisp fonctionnel très expressif. Les structures immuables et le moteur PEG intégré de Janet conviennent particulièrement bien à l’extraction et transformation de données web désordonnées.

Structure de base et top-level await

Comme les scripts d’automatisation sont fondamentalement asynchrones, Guida prend en charge top-level await pour les scripts qui n’ont pas besoin d’un return anticipé :

// Top-level await works out of the box
const tabs = g.tabs.getTabs();
g.log("Open tabs: " + tabs.length);

Pour les scripts qui doivent utiliser return tôt, placez votre code dans async function main() et ajoutez await main(); à la fin.

Appuyez sur F5 dans l’éditeur de scripts pour exécuter.

Gestion des erreurs

La gestion des erreurs dépend du moteur utilisé.

JavaScript et Janet : exceptions

En JavaScript et Janet, toutes les méthodes g.* renvoient les valeurs directement et lèvent des exceptions en cas d’erreur. En JavaScript, utilisez try/catch :

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

Lua : retours multiples

En Lua, l’API g.* utilise les retours multiples idiomatiques (nil, error) au lieu de lever des exceptions. Cela évite au débogueur Visual Studio de s’arrêter sur des exceptions « non gérées » pendant le développement.

Vérifiez toujours la première valeur de retour :

local success, err = g.nav.navigateToUrl("https://example.com")
if not success then
    g.log("Error: Navigation failed: " .. err)
else
    g.log("Page loaded successfully")
end

Méthodes asynchrones

Beaucoup d’opérations navigateur sont asynchrones. En JavaScript, utilisez await. En Lua et Janet, les appels sont automatiquement attendus par le moteur :

JavaScript :

async function main() {
  await g.nav.navigateToUrl("https://example.com");
  await g.dom.waitForDomStable();
  const html = await g.page.getDom();
  g.log("Page loaded, DOM length: " + html.length);
}

Lua :

g.nav.navigateToUrl("https://example.com")
g.dom.waitForDomStable()
local html = g.page.getDom()
g.log("Page loaded, DOM length: " .. #html)

Janet :

(g.nav.navigateToUrl "https://example.com")
(g.dom.waitForDomStable)
(def html (g.page.getDom))
(g.log (string "Page loaded, DOM length: " (length html)))

Bibliothèques partagées

Guida vous permet d’écrire des fonctions réutilisables dans des fichiers partagés.

JavaScript (modules ES)

Utilisez la syntaxe standard import/export. Le chemin est résolu par rapport au dossier du script appelant, avec repli sur la racine de l’espace de travail.

lib/helpers.js :

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");
}

myscript.js :

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

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

Lua (modules)

Utilisez la fonction standard require(). Guida cherche les modules dans le dossier lib/ de l’espace de travail ainsi que dans les dossiers lib/ et scripts/ du flux actif.

lib/utils.lua :

local M = {}
function M.hello() g.log("Hello from library!") end
return M

myscript.lua :

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

Janet (modules)

Utilisez la macro import pour charger des modules Janet depuis les dossiers lib/ et scripts/ de l’espace de travail.

lib/utils.janet :

(defn hello []
  (g.log "Hello from Janet library!"))

myscript.janet :

(import utils)
(utils/hello)

Pragma de délai

Définissez un délai d’exécution de script en millisecondes :

// @timeout 60000

async function main() {
  // This script will be cancelled after 60 seconds
}

Le délai par défaut est de 10 secondes. Placez le pragma avant tout code.

Pragma de contexte

Protégez les scripts qui dépendent de g.worker.getContext() contre une exécution hors contexte de processus :

// @require-context

async function main() {
  const ctx = g.worker.getContext();
  // This script will only run inside a queue processor or worker pool
}

Si le script est exécuté seul, via F5, MCP ou un déclencheur d’événement, il échoue immédiatement avec une erreur claire au lieu d’échouer au milieu de l’exécution. Voir Files d’attente et révision pour les détails.

Journalisation

Utilisez g.log() pour écrire dans le panneau Console :

g.log("Processing item: " + item.name);

Éditeur de scripts

L’éditeur intégré fournit :

• IntelliSense — auto-complétion de toutes les méthodes g.* et de leurs paramètres
• Aide de signature — indications de paramètres lors de la saisie de (
• Documentation au survol — informations de type au passage de la souris
• Débogage Chrome DevTools — cliquez sur Debug sur un fichier .js pour lancer une instance externe de Chrome DevTools connectée directement au moteur V8. Posez des points d’arrêt, avancez pas à pas et inspectez les variables avec l’interface Chrome standard.
• Recherche/remplacement — avec prise en charge des regex
• Correspondance des parenthèses et guides d’indentation

Navigation furtive

Certains sites détectent les navigateurs automatisés. Utilisez stealth: true pour injecter des correctifs anti-détection avant l’exécution des scripts de page :

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

Cela applique cinq correctifs : masque navigator.webdriver, injecte window.chrome.runtime, corrige Permissions.prototype.query, simule navigator.plugins et définit navigator.languages à ["en-US", "en"].

Pour un contrôle plus fin, passez un objet StealthOptions afin d’activer ou désactiver les correctifs individuellement. Vous pouvez aussi détecter les redirections basées sur JavaScript avec { detectRedirects: true }. Voir la référence API pour les détails complets.

Synthèse vocale

Guida inclut la synthèse vocale via Windows Speech Synthesis. Configurez la voix et le débit par défaut dans Settings > TTS.

Les scripts peuvent prononcer du texte et remplacer les valeurs par défaut par appel :

await g.tts.speak("Processing complete", { voice: "Microsoft David", rate: 2 });

Voir la référence API pour toutes les méthodes.

Différences Lua

Toutes les méthodes d’automatisation Guida sont disponibles via l’espace de noms global g. JavaScript et Lua partagent la même surface API, mais deux différences comptent dans l’usage :

1. Syntaxe point, sans deux-points

Contrairement à certaines intégrations C# avec Lua, l’API Guida utilise l’opérateur point (.) pour tous les appels, par exemple g.dom.click("#btn"). N’utilisez pas l’opérateur deux-points (:), comme g.dom:click, car les méthodes API sont liées directement aux services C# et n’attendent pas d’argument self.

2. Tables Lua

Lua utilise des tables pour les structures de données. Lorsqu’une méthode API renvoie un objet, comme un onglet de navigateur ou un document du stockage, il est renvoyé comme table Lua avec l’indexation standard à partir de 1 pour les tableaux.

-- Working with the document store
local doc, err = g.store.get("products", "item-1")
if doc and doc.data then
    g.log("Found product: " .. doc.data.name)
end

Différences Janet

Janet est un langage fonctionnel proche de Lisp. Sa syntaxe repose fortement sur les s-expressions, donc les parenthèses, et la notation préfixe.

1. Appels de fonction

Au lieu d’utiliser une notation point avec parenthèses externes comme g.dom.click("#btn"), vous entourez toute l’expression de parenthèses : (g.dom.click "#btn").

2. Dictionnaires et structs

Lorsqu’une méthode API renvoie un objet, comme un TabInfo ou un document du stockage, il est renvoyé comme dictionnaire Janet. Accédez aux propriétés avec get ou get-in :

# Working with the document store
(def doc (g.store.get "products" "item-1"))
(if doc
  (g.log (string "Found product: " (get (get doc "data") "name"))))

Étapes suivantes

• Référence API — liste complète des méthodes de tous les espaces de noms g.*
• Recettes — scripts pratiques fondés sur des exemples réels de l’application
• Espaces de travail — organiser scripts, données et configuration dans des dossiers d’espace de travail
• Démarrage rapide — guide pratique de 5 minutes