Depuração de plug-ins do ONLYOFFICE: guia prático

Desenvolver e depurar plug-ins do ONLYOFFICE pode ser desafiador, mas com as ferramentas e técnicas certas, o processo pode se tornar muito mais fácil. Este guia irá guiá-lo pelas etapas necessárias para depurar plug-ins de maneira eficaz em diferentes ambientes.

Sobre os plug-ins ONLYOFFICE

O ONLYOFFICE permite ampliar a funcionalidade de seus editores por meio de plug-ins. Esses plug-ins são páginas HTML incorporadas ao editor e utilizam uma API para interagir com ele. Compreender a estrutura do plug-in e os métodos de depuração é fundamental para o sucesso do desenvolvimento.

Estrutura do plugin

Um plugin típico do ONLYOFFICE consiste nos seguintes arquivos:

• config.json : Um arquivo de configuração que define informações básicas sobre o plug-in.
• index.html: A página HTML principal do plugin.
• scripts: Um diretório contendo os arquivos JavaScript necessários para o funcionamento do plug-in.

Uma estrutura detalhada e exemplos estão disponíveis aqui.

Depurando plug-ins em editores web

Para depurar plug-ins na versão web do ONLYOFFICE Editor, siga estas etapas:

• Adicione o comando do depurador ao seu script.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Pressione F12 para abrir o console no seu navegador.
• No ONLYOFFICE Editor, vá para a guia Plugins e execute seu plugin.

Observação: o comando do depurador só funcionará se as ferramentas de desenvolvedor estiverem abertas; caso contrário, ele será ignorado. Você pode ler mais sobre isso aqui na página.

Depurando plugins em desktop editors

Para depurar plug-ins na versão desktop do ONLYOFFICE editor, use a seguinte abordagem:

• Execute o editor com o comando –ascdesktop-support-debug-info.

• Esta flag permite a exibição de informações adicionais úteis para a depuração.
• Semelhante aos editores web, insira o depurador no local desejado em seu código.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Pressione F1 para abrir o console e executar o plugin.

Após iniciar o editor com o sinalizador especificado, abra o plug-in e rastreie a execução do código.

Instruções detalhadas para diferentes sistemas operacionais estão disponíveis aqui.

Gerenciando escopos

Ao desenvolver um plug-in ONLYOFFICE, é importante entender como passar dados entre a interface do usuário do seu plug-in (a página HTML) e o ambiente de execução do editor, onde os comandos da API do Document Builder são executados. Esses são contextos ou escopos diferentes.

Uma fonte comum de erros é o manuseio inadequado de dados entre esses escopos. O ONLYOFFICE fornece o objeto Asc.scope para facilitar isso. Você pode anexar variáveis ao Asc.scope no script principal do seu plug-in, e elas estarão acessíveis dentro da função passada para this.callCommand().

Aqui está um exemplo de como passar uma variável de texto do seu plugin para o editor:

(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);

O uso adequado do Asc.scope garante que os dados sejam transmitidos corretamente entre diferentes contextos, o que é fundamental para a criação de plug-ins complexos.

Problemas comuns e resolução de problemas

Durante a depuração, você pode encontrar vários problemas comuns. Aqui estão alguns dos problemas mais frequentes e suas soluções:

A instrução do depurador não está funcionando

A instrução debugger; é ignorada e a execução não é interrompida.

• Certifique-se de que as ferramentas de desenvolvedor do navegador (F12) estejam abertas antes de executar o plug-in.
• A instrução debugger; só funciona quando o DevTools está ativo.

Plugin não carregando ou não visível

• Verifique se o seu arquivo config.json está formatado corretamente (JSON válido).
• Verifique se todos os campos obrigatórios em config.json estão presentes (nome, guid, baseUrl).
• Verifique se há erros de carregamento no console do navegador.
• Certifique-se de que o plugin está instalado corretamente na guia Plugins do ONLYOFFICE..
• Instalação manual com arquivo .plugin compactado ou método Asc.editor.installDeveloperPlugin().

Erros de CORS (compartilhamento de recursos entre origens)

• Instale o ONLYOFFICE Docs.
• Para editores web no ONLYOFFICE Docs, certifique-se de executar o http-server dentro da sua pasta de plugins..
• Ou ajuste o caminho para o seu arquivo config.json no installDeveloperPlugin().

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

Arquivos alterados, código antigo ainda em execução – Web Editors

• Se você alterou os arquivos locais do seu plugin, será necessário atualizar a página e o cache.
• Clique com o botão direito do mouse no botão de atualização do seu navegador e selecione “Esvaziar cache e recarregar”, em seguida, execute o plugin novamente.

A depuração eficaz é crucial para o desenvolvimento de plug-ins ONLYOFFICE estáveis e funcionais. Ao utilizar as técnicas e ferramentas mencionadas, você pode identificar e resolver rapidamente problemas no seu código, melhorando assim a qualidade e o desempenho dos seus plug-ins.

Agradecemos suas perguntas, sugestões e ideias para plugins. Se desejar compartilhar seu trabalho conosco, não hesite em entrar em contato. Estamos abertos a colaborações e teremos prazer em nos conectar.