Novità nell’API di ONLYOFFICE 9.4: guida per sviluppatori agli ultimi aggiornamenti

La versione 9.4 di ONLYOFFICE introduce importanti miglioramenti dell’API per integrazioni, plugin personalizzati e automazione dei fogli di calcolo. Questo articolo evidenzia gli aggiornamenti principali dell’API ONLYOFFICE Docs, dell’API Plugins e Macros, e dell’Office JavaScript API, e spiega cosa significano per gli sviluppatori.

ONLYOFFICE Docs API 9.4

Supporto per la lingua croata

Il croato (hr) è stato aggiunto alla lista delle lingue di interfaccia supportate. Se stai costruendo applicazioni localizzate per utenti di lingua croata, puoi includerlo nella tua configurazione della lingua senza dover ricorrere a soluzioni alternative.

Dati su ruolo e utente nell’evento onStartFilling

L’evento onStartFilling ora include un parametro roles che trasmette informazioni su ruoli e utenti. Questo rende molto più facile costruire esperienze di compilazione di moduli consapevoli dei ruoli, ad esempio instradando gli utenti ai campi di cui sono responsabili o attivando logiche condizionali in base a chi sta compilando il modulo e in quale capacità.

function onStartFilling(event) {
  const roles = event.data;
  console.log("Ruoli:", roles);
}

const config = {
  // ...
  events: {
    onStartFilling,
  },
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);

Correzione di perdita di memoria in destroyEditor

È stata corretta una perdita di memoria nel metodo destroyEditor. In precedenza, chiamare destroyEditor non puliva completamente le risorse allocate. Se la tua applicazione crea e distrugge frequentemente istanze di editor, ad esempio, in configurazioni di applicazioni a pagina singola o flussi di lavoro di anteprima dei documenti, questa correzione migliora direttamente l’impronta di memoria della tua integrazione nel tempo.

Campo rimosso

Il campo obsoleto editorConfig.customization.commentAuthorOnly è stato rimosso. Se la tua integrazione fa ancora riferimento a questo parametro, ora è il momento di rimuoverlo per evitare comportamenti imprevisti.

Logging dei comandi del plugin per facilitare il debugging

Una delle aggiunte più pratiche per gli sviluppatori di plugin è il logging dei comandi del plugin che abilita l’output di debug dei comandi del plugin direttamente nella console del browser. Se hai trascorso tempo a fare debug del comportamento del plugin indovinando quali comandi si attivano realmente, questa funzionalità elimina una parte significativa di tale attrito, offrendo visibilità diretta sul flusso di esecuzione del plugin senza necessità di strumentare il tuo logging.

Blocco di plugin specifici al caricamento

Il nuovo parametro editorConfig.plugins.disable ti consente di impedire a specifici plugin di caricarsi quando l’editor si inizializza. Questo è utile quando stai incorporando l’editor in un ambiente controllato e desideri limitare la funzionalità a ciò che è rilevante per i tuoi utenti, senza dover modificare i file del plugin stessi. È un approccio più pulito, a livello di configurazione, per gestire la superficie del plugin.

Controlla il changelog completo per l’Docs API

ONLYOFFICE Plugins e Macros API 9.4

Nuovi metodi di controllo del cursore

Due nuovi metodi sono stati aggiunti a window.Asc.plugin.executeMethod per il Document API:

• MoveCursorToField: sposta il cursore in un campo modulo specifico;
• MoveCursorOutsideField: sposta il cursore in una posizione al di fuori del campo corrente.

Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);

Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);

Questi sono particolarmente utili per i plugin che guidano gli utenti nella compilazione dei moduli o automatizzano la navigazione campo per campo nei documenti. Invece di fare affidamento sull’interazione dell’utente per avanzare attraverso i campi, il tuo plugin può controllare programmaticamente il posizionamento del cursore.

Controllo migliorato di StartAction e EndAction

Il metodo StartAction accetta due nuovi parametri: lockScroll e keepSelection. Il metodo EndAction guadagna scrollToTarget e cancel. Insieme, questi offrono ai plugin un controllo più preciso dello stato dell’editor durante l’esecuzione delle macro. Puoi mantenere la selezione dell’utente, prevenire lo scorrimento indesiderato durante operazioni automatiche o annullare in modo pulito una sequenza di azioni — tutti aspetti che contribuiscono a un’esperienza di plugin più stabile e prevedibile.

Controlla il changelog completo per l’API Plugins e Macros

Office JavaScript API 9.4

Questa è la parte più ampia della versione 9.4. L’Office JavaScript API guadagna nuove capacità nelle operazioni sui documenti, nella gestione dei dati del foglio di calcolo, nei controlli dei moduli e altro ancora. Controlla l’elenco completo dei nuovi metodi

Unione di documenti

È stato aggiunto un nuovo metodo Api/MergeDocuments all’API Document. Questo ti consente di combinare più documenti in uno, una capacità che è stata frequentemente richiesta per scenari di automazione come la generazione di report, l’assemblaggio di contratti e l’elaborazione batch di documenti.

API Colore unificata tra tutti gli editor

Il metodo Api/Color è disponibile nell’API Document, Spreadsheet, Presentation e PDF. Avere un’interfaccia colore coerente tra tutti e quattro i tipi di editor semplifica il codice che deve applicare stili attraverso diversi formati di documento. Non hai più bisogno di logica di gestione del colore specifica per formato per operazioni comuni.

Supporto per i moduli di firma

La versione 9.4 introduce la classe ApiSignatureForm, disponibile sia nell’API Document che nell’API Form. Con essa arrivano i metodi GetValue e SetValue per leggere e scrivere i dati dei campi di firma. Questo apre la gestione programmatica dei campi di firma, utili per flussi di lavoro che devono precompilare, convalidare o estrarre dati di firma come parte di una pipeline di elaborazione documentale più ampia.

// Il metodo GetValue della classe ApiSignatureForm restituisce i dati dell'immagine della firma memorizzati nel modulo.

// Crea un modulo di firma, aggiungilo al documento e leggi il suo valore attuale.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "Si prega di firmare qui", "required": true, "placeholder": "Firma"});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("Valore del modulo di firma: " + value);
doc.Push(paragraph);

Inoltre, il nuovo metodo Api/CreateSignatureForm nell’API Form ti consente di creare campi di modulo di firma da zero tramite codice, invece di fare affidamento su inserimenti manuali.

Rilevamento dello stato del modulo

Il metodo ApiFormBase/IsFilled, aggiunto sia all’API Document che all’API Form, ti consente di controllare se un determinato campo modulo è stato compilato. Questa è un’aggiunta semplice ma importante per qualsiasi logica di convalida o invio. Ispeziona lo stato di completamento del modulo senza dover analizzare direttamente il contenuto del campo.

Ispezione dell’evidenziazione del modulo

Due nuovi metodi (ApiDocument/GetFormsHighlight e ApiDocument/GetControlsHighlight) sono disponibili nell’API Document e Form. Questi ti consentono di recuperare le impostazioni di evidenziazione attuali applicate ai campi modulo e ai controlli di contenuto. Se la tua integrazione gestisce la configurazione della visualizzazione del modulo o deve riflettere gli stati di evidenziazione in elementi UI esterni, questi metodi forniscono l’accesso in lettura che prima mancava.

API ListObject di Spreadsheet estesa

Questa è l’aggiunta più ricca di funzionalità nella versione 9.4. L’API Spreadsheet include una classe completa ApiListObject per lavorare con oggetti tabella strutturati (oggetti di lista), insieme a classi di supporto per colonne, righe e ordinamento.

Le capacità chiave includono:

• Creazione e recupero di oggetti lista tramite ApiWorksheet/AddListObject e ApiWorksheet/GetListObjects
• Lettere e scrittura delle proprietà della tabella come nome, nome visualizzato, testo alternativo, stile, intestazioni, totali e impostazioni di filtro automatico
• Accesso ai range della tabella inclusi le righe di intestazione, i range del corpo dati e le righe dei totali
• Gestione di colonne e righe tramite ApiListColumn e ApiListRow, con metodi per nomi, indici, range, calcolo dei totali e cancellazione
• Supporto all’ordinamento tramite le nuove classi ApiSort, ApiSortFields e ApiSortField, coprendo l’orientamento dell’ordinamento, corrispondenza maiuscole e minuscole, criteri di ordinamento (valore o colore), priorità e altro

Se la tua integrazione comporta qualsiasi tipo di gestione di dati strutturati nei fogli di calcolo come importazioni di dati, creazione di tabelle dinamiche, generazione di report. Questa aggiunta espande significativamente ciò che puoi fare senza chiedere agli utenti di manipolare manualmente le tabelle.

Nuovi metodi di riempimento e formula di Spreadsheet

Sono stati aggiunti quattro metodi di riempimento direzionale a ApiRange: FillDown, FillUp, FillRight, FillLeft.

Questi rispecchiano il comportamento di riempimento dei fogli di calcolo che gli utenti attivano manualmente, ora disponibili per l’uso programmatico. Combinati con il nuovo metodo ApiRange/SetFormula, puoi costruire automazioni che costruiscono intervalli basati su formule in modo dinamico. È utile per report generati, fogli di calcolo basati su template e automazione dell’immissione dei dati.

È stato anche aggiunto il metodo Api/GetDefNames all’API Spreadsheet, offrendoti accesso ai nomi definiti (intervalli nominati) in un workbook.

Controlli di formattazione dei campi di testo

La classe ApiTextForm guadagna quattro nuovi metodi sia nell’API Document che nell’API Form:

• GetFormat/SetFormat: leggi e applica una maschera di formato al campo di testo
• GetAllowedSymbols/SetAllowedSymbols: controlla quali caratteri gli utenti possono inserire

Questi sono essenziali per costruire moduli di immissione dati validati, ad esempio, imponendo formati di data, limitando l’immissione a caratteri numerici o applicando maschere personalizzate per numeri di telefono o ID.

Ispezione delle proprietà del paragrafo

Un insieme di metodi Get è stato aggiunto a ApiParaPr nell’API Document, coprendo:

• Proprietà dei bordi: superiore, sinistro, destro, inferiore, tra
• Paginazione: GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl
• Elenco: GetNumPr
• Tabs: GetTabs
• Spaziatura: GetContextualSpacing

Questi riempiono una lacuna di lunga data. Potresti impostare molti di questi parametri programmaticamente, ma leggerli indietro non era sempre possibile. Puoi ispezionare il formato del paragrafo senza dover ricorrere a soluzioni alternative, il che è particolarmente utile per strumenti di analisi dei documenti e script di convalida dei template.

Colore dei controlli di contenuto

La classe ApiInlineLvlSdt nell’API Document supporta i metodi SetColor e GetColor. Puoi assegnare e leggere colori di evidenziazione per controlli di contenuto inline, rendendo più facile costruire esperienze di modulo visivamente distinte o evidenziare controlli in base al loro stato.

// Come posso cambiare il colore di un controllo di contenuto inline in un documento?

// Applica un colore RGB specifico per distinguere visivamente un controllo di contenuto in un documento.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("Questo è un controllo di contenuto di testo inline con un colore di tag blu.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);