Guida per sviluppatori alle API di stile e colore di ONLYOFFICE

Sviluppare plugin per ONLYOFFICE spesso significa migliorare il modo in cui gli utenti interagiscono con i documenti, ad esempio aggiungendo evidenziatori, strumenti per rifinire la formattazione o elementi dell’interfaccia a tema.

Per aiutarti a lavorare in modo più efficiente, abbiamo raccolto i principali metodi API relativi a stile e colore che consentono agli sviluppatori di controllare facilmente l’aspetto e il comportamento visivo dei propri plugin.

Questo post del blog offre spiegazioni chiare, esempi pratici e suggerimenti per un’esperienza di sviluppo più fluida.

Comprendere il contesto dello stile

Le API dei plugin di ONLYOFFICE offrono modi flessibili per personalizzare l’aspetto dei documenti attraverso oggetti come ApiRange, ApiParagraph e ApiTextPr.

Queste interfacce permettono agli sviluppatori di modificare attributi del font, allineamento dei paragrafi, colori e altre proprietà visive direttamente dagli script dei plugin.

Un semplice esempio di applicazione di stili al testo:

const oDocument = Api.GetDocument();

const oRange = oDocument.GetRangeBySelect();

const oTextPr = oRange.GetTextPr();

oTextPr.Bold(true);

oTextPr.Italic(true);

oTextPr.SetColor(255, 0, 0); // RGB rosso

Questo frammento mostra come combinare più stili per ottenere una formattazione dinamica.

Metodi comuni per stile e colore

Quando si sviluppano plugin ONLYOFFICE che gestiscono la formattazione del documento (come evidenziatori, pulitori di formato o elementi dell’interfaccia basati su temi) gli sviluppatori hanno spesso bisogno di metodi chiari e pronti all’uso per gestire colori, font e attributi del testo.

Per semplificare questo processo, abbiamo raccolto qui le API di stile e colore più pratiche, con suggerimenti ed esempi per un’integrazione fluida.

Metodo	Descrizione	Esempio
SetColor(r, g, b)	Imposta il colore del testo usando i valori RGB.	oTextPr.SetColor(0, 102, 204)
SetHighlight(sColor)	Applica un colore di evidenziazione o di sfondo al testo.	oRange.SetHighlight("lightGray")
SetBackgroundColor(r, g, b)	Applica un colore di sfondo a un paragrafo.	oParagraph.SetBackColor(230, 230, 230)
SetBold(true/false)	Attiva o disattiva il grassetto.	oTextPr.SetBold(true)
SetItalic(true/false)	Attiva o disattiva il corsivo.	oTextPr.SetItalic(true)
SetUnderline(true/false)	Aggiunge o rimuove la sottolineatura.	oTextPr.SetUnderline(true)
SetFontSize(nSize)	Modifica la dimensione del font in punti.	oTextPr.SetFontSize(14)
SetFontName(name)	Imposta la famiglia di font.	oTextPr.SetFontName("Calibri")
ApiCell	Rappresenta una cella di un foglio di calcolo per la formattazione.	const cell = sheet.GetRange("A1");
SetCellColor(r, g, b)	Imposta il colore di sfondo di una cella.	cell.SetCellColor(255, 230, 191)

Per la formattazione dei paragrafi puoi usare metodi analoghi tramite l’interfaccia ApiParagraph:

const oParagraph = oRange.GetParagraph(0);

oParagraph.SetBackColor(230, 230, 230); // Sfondo grigio chiaro

oParagraph.SetAlign("center");

Questi metodi costituiscono la base per la formattazione di testo e paragrafi nei plugin di ONLYOFFICE. Le celle dei fogli di calcolo usano API concettualmente simili, come ApiCell e SetCellColor, seguendo la stessa logica di stile.

Lavorare con gli oggetti colore

Per i suoi metodi di stile ONLYOFFICE utilizza definizioni di colore basate su RGB. Se il tuo progetto usa codici colore HEX (comuni nei sistemi di design o nei temi aziendali), puoi convertirli facilmente con una piccola funzione di supporto:

function hexToRGB(hex) {

const bigint = parseInt(hex.replace("#", ""), 16);

const r = (bigint >> 16) & 255;

const g = (bigint >> 8) & 255;

const b = bigint & 255;

return [r, g, b];

}

// Esempio d’uso:

const [r, g, b] = hexToRGB("#3498db");

oTextPr.SetColor(r, g, b);
Questo consente un’integrazione fluida tra risorse di design e funzionalità del plugin.

Consigli per uno stile affidabile

• Riseleziona l’intervallo del documento prima di applicare le modifiche per garantire l’accuratezza dopo azioni dell’interfaccia.
• Usa chiamate di funzione separate per ogni operazione di stile, invece di concatenare troppi metodi insieme.
• Esegui sempre controlli di validazione, ad esempio verifica che GetRangeBySelect() restituisca un oggetto valido.
• Supporta le modalità tema regolando dinamicamente i valori dei colori con Asc.plugin.getTheme().

Questi piccoli accorgimenti aiutano a creare un comportamento del plugin più stabile e coerente con il tema.

Conclusione

Le API di stile in ONLYOFFICE mantengono un approccio coerente tra i vari editor, che si tratti di documenti, presentazioni o fogli di calcolo.

Riutilizzando gli stessi concetti (applicazione dei colori, regolazione dei font, allineamento dei paragrafi), gli sviluppatori possono adattare il proprio codice ai diversi editor mantenendo una logica di formattazione uniforme.

Raccogliendo queste informazioni in un unico posto, vogliamo rendere lo sviluppo dei plugin più veloce, fluido e intuitivo per chiunque lavori con ONLYOFFICE.

Se hai domande o suggerimenti, non esitare a contattarci. Insieme possiamo continuare a migliorare la documentazione di ONLYOFFICE.