Panoramica dello scripting

Guida include un ambiente di scripting completo per l’automazione del browser. Gli script interagiscono con le pagine, gestiscono dati e orchestrano flussi di lavoro tramite l’API g.*.

Motori di scripting

Sono disponibili tre motori:

• JavaScript (ClearScript V8) — compatibilità completa ES2024+, top-level await, Promise native e import di moduli ES. Usa lo stesso motore V8 di Chrome e Node.js.
• Lua (LuaCSharp) — API pulita basata su tabelle e sintassi Lua standard. Integrato pienamente con le librerie dello spazio di lavoro tramite require().
• Janet (JanetSharp) — dialetto Lisp funzionale ed espressivo, con strutture dati immutabili e un potente motore PEG (Parsing Expression Grammar) integrato.

Tutti e tre i motori condividono lo stesso insieme di API g.*.

Perché Janet?

JavaScript è eccellente per familiarità, ma Guida include Janet per chi preferisce un dialetto Lisp funzionale e molto espressivo. Le strutture dati immutabili integrate e il potente motore PEG di Janet lo rendono particolarmente adatto a estrarre e trasformare dati.

Struttura base e top-level await

Poiché gli script di automazione sono fondamentalmente asincroni, Guida supporta top-level await per gli script che non richiedono un’istruzione return anticipata:

// Top-level await funziona subito
const tabs = g.tabs.getTabs();
g.log("Schede aperte: " + tabs.length);

Per gli script che devono fare return in anticipo, racchiudi il codice in async function main() e chiama await main(); alla fine.

Premi F5 nell’editor degli script per eseguire.

Gestione degli errori

La gestione degli errori in Guida dipende dal linguaggio usato.

JavaScript e Janet: eccezioni

In JavaScript e Janet, tutti i metodi g.* restituiscono valori direttamente e generano eccezioni in caso di errore. In JavaScript, usa try/catch per gestire gli errori:

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

Lua: ritorni multipli

In Lua, l’API g.* usa i ritorni multipli idiomatici (nil, error) invece di generare eccezioni. Questo evita che il debugger di Visual Studio si fermi su eccezioni “non gestite” durante lo sviluppo.

Controlla sempre il primo valore restituito:

local success, err = g.nav.navigateToUrl("https://example.com")
if not success then
    g.log("Errore: navigazione fallita: " .. err)
else
    g.log("Pagina caricata correttamente")
end

Metodi asincroni

Molte operazioni del browser sono asincrone. In JavaScript usa await. In Lua e Janet, le chiamate vengono attese automaticamente dalla piattaforma di esecuzione:

JavaScript:

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

Lua:

g.nav.navigateToUrl("https://example.com")
g.dom.waitForDomStable()
local html = g.page.getDom()
g.log("Pagina caricata, lunghezza DOM: " .. #html)

Janet:

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

Librerie condivise

Guida permette di scrivere funzioni riutilizzabili in file condivisi.

JavaScript (moduli ES)

Usa la sintassi standard ES import/export. Il percorso viene risolto rispetto alla cartella dello script chiamante, con ripiego sul percorso principale (root) dello spazio di lavoro.

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("Statistiche dashboard: " + data);

Lua (moduli)

Usa la funzione standard require(). Guida cerca i moduli nella cartella lib/ dello spazio di lavoro e nelle cartelle lib/ e scripts/ del flusso di lavoro corrente.

lib/utils.lua:

local M = {}
function M.hello() g.log("Ciao dalla libreria!") end
return M

myscript.lua:

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

Janet (moduli)

Usa la macro import per caricare moduli Janet dalle cartelle lib/ e scripts/ dello spazio di lavoro.

lib/utils.janet:

(defn hello []
  (g.log "Ciao dalla libreria Janet!"))

myscript.janet:

(import utils)
(utils/hello)

Pragma timeout

Imposta un timeout di esecuzione dello script (in millisecondi):

// @timeout 60000

async function main() {
  // Questo script verrà annullato dopo 60 secondi
}

Il timeout predefinito è 10 secondi. Inserisci il pragma prima di qualsiasi codice.

Pragma context

Proteggi gli script che dipendono da g.worker.getContext() dall’esecuzione fuori da un contesto di processo di lavoro:

// @require-context

async function main() {
  const ctx = g.worker.getContext();
  // Questo script verrà eseguito solo dentro un processore di coda o un pool di processi di lavoro
}

Se lo script viene eseguito da solo (F5, MCP, generatore di evento), fallisce immediatamente con un errore chiaro invece di fallire a metà esecuzione. Vedi Code e revisione per i dettagli.

Log

Usa g.log() per scrivere nel pannello Console:

g.log("Elaborazione elemento: " + item.name);

Editor degli script

L’editor integrato offre:

• IntelliSense — completamenti automatici per tutti i metodi g.* e i loro parametri
• Aiuto sulle firme dei metodi — suggerimenti sui parametri mostrati mentre digiti (
• Documentazione contestuale al cursore del mouse — informazioni sui tipi al passaggio del mouse
• Analisi e correzione degli errori con Chrome DevTools — fai clic sul pulsante Debug su qualsiasi file .js per avviare un’istanza esterna di Chrome DevTools collegata direttamente al motore V8. Imposta punti di interruzione, avanza passo passo nel codice e ispeziona variabili usando l’interfaccia standard di Chrome.
• Trova/sostituisci — con supporto regex
• Corrispondenza delle parentesi e guide di indentazione

Navigazione stealth

Alcuni siti rilevano i browser automatizzati. Usa stealth: true per iniettare patch anti-rilevamento prima dell’esecuzione degli script della pagina:

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

Applica cinque patch: nasconde navigator.webdriver, inietta window.chrome.runtime, corregge Permissions.prototype.query, simula navigator.plugins e imposta navigator.languages a ["en-US", "en"].

Per un controllo granulare, passa un oggetto StealthOptions per abilitare/disabilitare singole patch. Puoi anche rilevare reindirizzamenti basati su JavaScript con { detectRedirects: true }. Vedi il Riferimento API per i dettagli completi.

Sintesi vocale

Guida include la sintesi vocale tramite Windows Speech Synthesis. Configura voce predefinita e velocità in Impostazioni > Sintesi vocale (Settings > TTS).

Gli script possono pronunciare testo e sovrascrivere i valori predefiniti per singola chiamata:

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

Vedi il Riferimento API per tutti i metodi.

Differenze Lua

Tutti i metodi di automazione di Guida sono disponibili tramite lo spazio dei nomi globale g. Anche se JavaScript e Lua condividono lo stesso insieme di API, ci sono due differenze importanti nel modo in cui vengono usati:

1. Sintassi con punto (non due punti)

A differenza di altre integrazioni Lua per C#, l’API di Guida usa l’operatore punto (.) per tutte le chiamate (per esempio g.dom.click("#btn")). Non usare l’operatore due punti (:), per esempio g.dom:click, perché i metodi API sono collegati direttamente ai servizi C# e non si aspettano un argomento self.

2. Tabelle per le schede

Lua usa tabelle per le strutture dati. Quando un metodo API restituisce un oggetto (come una scheda del browser o un documento dallo spazio di archiviazione g.store), viene restituito come tabella Lua, con indicizzazione standard da 1 per gli array.

-- Lavorare con lo spazio di archiviazione documenti
local doc, err = g.store.get("products", "item-1")
if doc and doc.data then
    g.log("Prodotto trovato: " .. doc.data.name)
end

Differenze Janet

Janet è un linguaggio funzionale simile a Lisp. La sua sintassi è fortemente basata su s-expression (parentesi) e notazione prefissa.

1. Chiamate di funzione

Invece di usare notazione con punto e parentesi esterne come g.dom.click("#btn"), racchiudi l’intera espressione tra parentesi: (g.dom.click "#btn").

2. Dizionari e struct

Quando un metodo API restituisce un oggetto (come un TabInfo o un documento dallo spazio di archiviazione g.store), viene restituito come dizionario Janet. Accedi alle proprietà con le funzioni get o get-in:

# Lavorare con lo spazio di archiviazione documenti
(def doc (g.store.get "products" "item-1"))
(if doc
  (g.log (string "Prodotto trovato: " (get (get doc "data") "name"))))

Passi successivi

• Riferimento API — elenco completo dei metodi per tutti gli spazi dei nomi g.*
• Soluzioni — script pratici basati su esempi reali dell’applicazione
• Spazi di lavoro — organizza script, dati e configurazione in cartelle di spazio di lavoro
• Avvio rapido — guida pratica di 5 minuti