Guia do desenvolvedor para APIs de estilo e cor do ONLYOFFICE

Desenvolver plug-ins para o ONLYOFFICE geralmente significa melhorar a forma como os usuários interagem com os documentos, seja adicionando marcadores, limpadores de formato ou elementos temáticos da interface do usuário.

Para ajudá-lo a trabalhar com mais eficiência, compilamos os principais métodos de API de estilo e cor que permitem aos desenvolvedores controlar facilmente a aparência de seus plug-ins.

Esta publicação no blog oferece explicações claras, exemplos práticos e dicas para uma experiência de desenvolvimento mais tranquila.

Compreender o contexto do estilo

As APIs do plugin ONLYOFFICE oferecem maneiras flexíveis de personalizar a aparência dos documentos por meio de objetos como ApiRange, ApiParagraph, e ApiTextPr.

Essas interfaces permitem que os desenvolvedores modifiquem atributos de fonte, alinhamento de parágrafos, cores e outras propriedades visuais diretamente a partir de scripts de plug-ins.

Um exemplo simples de aplicação de estilos de texto:

const oDocument = Api.GetDocument();

const oRange = oDocument.GetRangeBySelect();

const oTextPr = oRange.GetTextPr();

oTextPr.Bold(true);

oTextPr.Italic(true);

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

Este trecho demonstra como vários estilos podem ser combinados para obter uma formatação dinâmica.

Métodos de estilo e cor comumente usados

Ao desenvolver plug-ins ONLYOFFICE que trabalham com estilos de documentos, como marcadores, limpadores de formato ou elementos de interface do usuário baseados em temas, os desenvolvedores geralmente precisam de métodos claros e prontos para uso para lidar com cores, fontes e atributos de texto.

Para simplificar esse processo, reunimos aqui as APIs de estilo e cor mais práticas, juntamente com dicas e exemplos para uma integração tranquila.

Método	Descrição	Exemplo
SetColor(r, g, b)	Define a cor do texto usando valores RGB.	oTextPr.SetColor(0, 102, 204)
SetHighlight(sColor)	Aplica uma cor de destaque ou de fundo ao texto.	oRange.SetHighlight("lightGray")
SetBackgroundColor(r, g, b)	Aplica uma cor de fundo a um parágrafo.	oParagraph.SetBackColor(230, 230, 230)
SetBold(true/false)	Alterna o estilo em negrito.	oTextPr.SetBold(true)
SetItalic(true/false)	Alterna o estilo itálico.	oTextPr.SetItalic(true)
SetUnderline(true/false)	Adiciona ou remove o sublinhado.	oTextPr.SetUnderline(true)
SetFontSize(nSize)	Altera o tamanho da fonte em pontos.	oTextPr.SetFontSize(14)
SetFontName(name)	Define a família de fontes.	oTextPr.SetFontName("Calibri")
ApiCell	Representa uma célula da planilha para estilização.	const cell = sheet.GetRange("A1");
SetCellColor(r, g, b)	Define a cor de fundo de uma célula da planilha.	cell.SetCellColor(255, 230, 191)

Para estilizar parágrafos, você pode usar métodos análogos por meio da interface ApiParagraph:

const oParagraph = oRange.GetParagraph(0);

oParagraph.SetBackColor(230, 230, 230); // Light gray background

oParagraph.SetAlign("center");

Esses métodos formam a base da formatação de texto e parágrafos nos plug-ins do ONLYOFFICE. As células da planilha utilizam APIs conceitualmente semelhantes, como ApiCell e SetCellColor, seguindo a mesma lógica de estilo.

Trabalhando com objetos coloridos

O ONLYOFFICE usa definições de cores baseadas em RGB para seus métodos de estilo. Se o seu projeto usa códigos de cores HEX (comuns em sistemas de design ou temas de marca), você pode convertê-los facilmente usando uma pequena função auxiliar:

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];

}

// Example use:

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

oTextPr.SetColor(r, g, b);
This allows seamless integration between design resources and plugin functionality.

Dicas e truques para um estilo confiável

• Selecione novamente o intervalo do documento antes de aplicar as alterações para garantir a precisão após as ações da interface do usuário.
• Use chamadas de função separadas para cada operação de estilo, em vez de encadear muitos métodos de uma só vez.
• Sempre execute verificações de validação, por exemplo, confirme se GetRangeBySelect() retorna um objeto válido.
• Suporte modos de tema ajustando valores de cor dinamicamente com Asc.plugin.getTheme().

Esses pequenos ajustes ajudam a criar um comportamento mais estável e consistente do plugin.

Conclusão

As APIs de estilo do ONLYOFFICE mantêm uma abordagem consistente em diferentes editores, quer você esteja trabalhando com documentos, apresentações ou planilhas.

Ao reutilizar os mesmos conceitos (aplicação de cores, ajustes de fonte, alinhamento de parágrafos), os desenvolvedores podem adaptar seu código em diferentes editores, mantendo a lógica de estilo unificada.

Ao reunir essas informações em um único lugar, nosso objetivo é tornar o desenvolvimento de plug-ins mais rápido, fácil e intuitivo para todos que criam com o ONLYOFFICE.

Se você tiver alguma dúvida ou sugestão, sinta-se à vontade para entrar em contato. Juntos, podemos continuar melhorando a documentação do ONLYOFFICE.