Eventi Gestibili con le Macro di ONLYOFFICE

Scopri come automatizzare e personalizzare le funzionalità nel tuo documento

Highlights

Interazione Dinamica: Personalizzazione degli eventi come onAppReady e onCollaborativeChanges.
Automazione: Gestione degli eventi di modifica documentale (es. onDocumentModifiedChanged) e di foglio di calcolo (onWorksheetChange).
Integrazione Avanzata: Supporto per eventi specifici quali clic sui collegamenti ipertestuali e modifiche collaborative.

Introduzione

Le macro di ONLYOFFICE offrono una flessibilità straordinaria per personalizzare e automatizzare le operazioni di editing, gestione e collaborazione nei documenti e nei fogli di calcolo. Attraverso l’utilizzo del metodo attachEvent, è possibile collegare specifiche funzioni di callback agli eventi generati nel corso dell’uso dell’applicazione. Queste capacità consentono agli utenti di ottimizzare il flusso di lavoro e di rispondere dinamicamente a una varietà di situazioni, come la modifica del documento, il cambio del foglio attivo o il passaggio tra modalità di visualizzazione e modifica. Di seguito, viene illustrato un elenco approfondito degli eventi gestibili, corredato da esempi pratici e spiegazioni dettagliate.

Eventi di Documento

Gli eventi relativi al documento permettono di monitorare e rispondere alle modifiche durante la redazione o la revisione. Questi eventi sono fondamentali per implementare funzioni come il salvataggio automatico, la validazione dei contenuti e il supporto alla collaborazione in tempo reale.

Eventi Principali

onAppReady

Questo evento si attiva quando l'applicazione è completamente caricata nel browser. È l'ideale per inizializzare le macro e per impostare eventuali parametri o configurazioni necessari prima che l'utente inizi a lavorare sul documento.

onDocumentModifiedChanged / onDocumentStateChange

Questi eventi vengono richiamati quando il documento subisce delle modifiche. Possono essere usati, ad esempio, per attivare funzioni di salvataggio automatico o per evidenziare le modifiche apportate, garantendo così una nota precisione nelle versioni del documento.

onDocumentReady

Specifico per quando il documento è completamente caricato nell'editor, questo evento è utile per applicazioni che necessitano di eseguire operazioni subito dopo il caricamento, come la personalizzazione della visualizzazione o l'applicazione di temi grafici.

onCollaborativeChanges

In ambienti di lavoro collaborativi, questo evento si attiva quando un altro utente modifica il documento in tempo reale. Aiuta a sincronizzare le modifiche e a garantire che tutti gli utenti visualizzino l'ultima versione aggiornata del documento.

onError / onInfo

Gli eventi relativi agli errori e all'informazione vengono utilizzati per gestire situazioni eccezionali. Mentre l'evento onError si attiva in caso di problemi imprevisti, l'evento onInfo può essere impiegato per monitorare eventi informativi come il caricamento dei file.

onMetaChange

Questo evento si attiva quando le informazioni meta del documento vengono modificate. È particolarmente utile per mantenere aggiornati dati come titoli, descrizioni o altri metadati fondamentali per la gestione dei documenti.

Eventi di Fogli di Calcolo

I fogli di calcolo offrono possibilità mirate per monitorare le modifiche alle celle e il cambio del foglio attivo. Questi eventi sono particolarmente validi per implementare funzionalità di calcolo automatico, registrazione dei dati e gestione dinamica dei fogli.

Eventi Principali

onWorksheetChange

Indicato per gestire le modifiche nelle celle del foglio di calcolo, questo evento viene attivato ogni volta che il contenuto di una cella viene alterato. Tale evento è essenziale per applicazioni che richiedono il monitoraggio in tempo reale delle modifiche ai dati.

onActiveSheetChanged

Questo evento si attiva quando si passa da un foglio di calcolo a un altro all'interno dello stesso documento. Permette di eseguire operazioni personalizzate quando cambia il focus sul foglio attivo, come la ricarica di dati o l'applicazione di stili particolari.

Eventi di Interazione Utente

Un aspetto rilevante delle macro di ONLYOFFICE è la capacità di rispondere ad azioni specifiche dell’utente, come il clic sui collegamenti ipertestuali o la richiesta di selezione di documenti. Questi eventi possono migliorare significativamente l'interattività e l'usabilità dell'applicazione.

Eventi Specifici

onHyperlinkClick / asc_onHyperlinkClick

Questo evento viene attivato quando l'utente clicca su un hyperlink all'interno del documento. È utile per implementare logiche personalizzate, come la registrazione di clic, il reindirizzamento personalizzato o l’apertura di finestre di dialogo informative.

onEditCurrentFile / onRequestEditRights

Questi eventi monitorano il passaggio dalla modalità di visualizzazione a quella di modifica. Sono fondamentali per applicare controlli di sicurezza, registrare audit trail dei cambiamenti o gestire la transizione in modo fluido.

onRequestSelectDocument e onRequestSelectSpreadsheet

Questi eventi si attivano quando l'utente tenta di selezionare un documento o un foglio di calcolo, per esempio, per scopi di confronto o combinazione dei contenuti. Sono particolarmente rilevanti nelle edizioni Enterprise e Developer, dove la gestione avanzata dei documenti è fondamentale.

onMakeActionLink

Questo evento viene innescato quando l’utente tenta di ottenere un link per aprire il documento con un segnalibro. Permette di estendere le funzionalità di condivisione e di integrare funzionalità di commento o di tracciamento dei link.

Altri Eventi Utili

Oltre agli eventi primari, ONLYOFFICE supporta una serie di altri eventi che coprono una vasta gamma di esigenze specifiche. Questi includono eventi per il download, richieste di chiusura, gestione di versione obsoleta e l’inizializzazione di plugin.

Eventi Addizionali

onDownloadAs

Si attiva quando si utilizza il metodo "downloadAs". Questo evento è utile se si desidera intercettare e personalizzare il processo di download del documento, ad esempio, per aggiungere filigrane o notifiche di completamento.

onOutdatedVersion

Utilizzato per gestire le situazioni in cui il documento viene aperto per la modifica con una chiave obsoleta. In tal caso, l’editor può essere reinizializzato con una nuova chiave per garantire la consistenza e la sicurezza nella versione del documento.

onPluginsReady

Questo evento indica che tutti i plugin necessari sono stati caricati e sono pronti all’uso. È fondamentale per assicurarsi che tutte le estensioni e i componenti aggiuntivi funzionino correttamente quando l’utente inizia a interagire con il documento.

onRequestClose

Viene chiamato quando il sistema richiede la chiusura dell'editor. Può essere usato per salvare automaticamente il documento o per impostare notifiche all’utente prima che la sessione venga terminata.

Tabella Riassuntiva degli Eventi

Evento	Descrizione
onAppReady	Attivato quando l'applicazione è completamente caricata; utile per inizializzazioni.
onDocumentModifiedChanged / onDocumentStateChange	Richiamato quando il documento subisce modifiche; usato per salvataggi automatici e auditing.
onDocumentReady	Segnala il completamento del caricamento del documento nell'editor.
onCollaborativeChanges	Attivato durante la modifica collaborativa, per sincronizzare le versioni in tempo reale.
onHyperlinkClick / asc_onHyperlinkClick	Richiamato al clic su un collegamento ipertestuale, consentendo funzioni personalizzate.
onWorksheetChange	Attivato al cambiamento dei dati in un foglio di calcolo.
onActiveSheetChanged	Indica il cambio del foglio attivo all'interno del documento.
onRequestEditRights / onEditCurrentFile	Segnala il passaggio dalla modalità di visualizzazione a quella di modifica.
onRequestSelectDocument / onRequestSelectSpreadsheet	Attivato quando l'utente seleziona un documento/foglio, utile per confronti e fusioni.
onDownloadAs	Richiamato durante il processo di download del documento, per personalizzare l'output.
onOutdatedVersion	Gestisce i casi in cui la chiave del documento è obsoleta e necessita di aggiornamento.
onPluginsReady	Indica che tutti i plugin sono stati caricati ed è il momento di iniziare.
onRequestClose	Attivato quando l'editor deve essere chiuso, permettendo di salvare le modifiche.

Implementazione Pratica

Per sfruttare al meglio questi eventi, è essenziale utilizzare il metodo attachEvent fornito dall'API di ONLYOFFICE. Una semplice implementazione in JavaScript potrebbe essere quella di gestire il clic su un collegamento ipertestuale:

Esempio di Codice

Gestione del Clic sui Link


// Inizializzazione immediata per incapsulare il codice
(function() {
    // Collega l'evento per gestire il clic sul link
    Api.attachEvent("asc_onHyperlinkClick", function() {
        console.log("HYPERLINK!!!");
        // Inserisci qui ulteriori azioni personalizzate da eseguire
    });
})();

In modo simile, puoi implementare gestioni di altri eventi come onWorksheetChange per monitorare le modifiche dei dati o onCollaborativeChanges per sincronizzare le modifiche eseguite da altri utenti in tempo reale.

Approfondimenti e Personalizzazione

Oltre agli eventi menzionati, ONLYOFFICE fornisce una ricca interfaccia per aggiungere ulteriori eventi in base alle specifiche esigenze della tua applicazione. Ad esempio, se si desidera intervenire in fase di modifica dei metadati o gestire eventi di richiesta di creazione di nuovi documenti, è possibile configurare le macro per attivare callback dedicate:

Ulteriori Esempi di Implementazione

Gestione delle Modifiche nel Foglio di Calcolo


// Ottieni il foglio di lavoro attivo
var activeSheet = Api.GetActiveSheet();

// Attacca l'evento per monitorare le modifiche alle celle
Api.attachEvent("onWorksheetChange", function(oRange) {
    console.log("Modifica rilevata in ", oRange.GetAddress());
    // Esecuzione di ulteriori azioni, ad esempio la validazione dei dati inseriti
});

Un altro caso d'uso riguarda, ad esempio, la gestione delle transizioni tra visualizzazione e modifica: intervenendo con il corretto evento, è possibile implementare sistemi di autorizzazione e log di audit per migliorare la sicurezza e la tracciabilità delle modifiche.

Personalizzazione e Controllo

La flessibilità offerta dalle macro di ONLYOFFICE consente agli sviluppatori di creare soluzioni personalizzate che rispondono perfettamente alle esigenze aziendali o individuali. L'uso dei vari eventi, in combinazione con i metodi per attaccare funzioni di callback, permette di gestire ogni aspetto dell'interazione con il documento, garantendo una maggiore automazione e un processo di lavoro più efficiente e intuitivo.

Conclusione

Le funzionalità offerte dalle macro di ONLYOFFICE rappresentano un potente strumento per chi desidera automatizzare e personalizzare la gestione dei documenti e dei fogli di calcolo. Dall'inizializzazione dell'applicazione, passando per la gestione delle modifiche e degli eventi collaborativi, fino al monitoraggio delle richieste di selezione e modifica, l'ampia gamma di eventi disponibili consente una gestione molto granulare e precisa del flusso di lavoro. L'integrazione di questi eventi all'interno della logica delle macro permette di ottimizzare le prestazioni e di garantire che le operazioni siano eseguite in modo coerente e sicuro.

In definitiva, l'approccio modulare e reattivo delle macro di ONLYOFFICE offre agli sviluppatori la libertà di creare esperienze utente personalizzate e automaticamente aggiornate, migliorando notevolmente la produttività e la gestione dei documenti. Sfruttando i concetti illustrati, potrai implementare soluzioni che non solo reagiscono in tempo reale agli input degli utenti, ma che anticipano e gestiscono eventi critici con precisione, garantendo così un ambiente di lavoro dinamico e collaborativo.