Création de plugins ONLYOFFICE : conseils, astuces et pièges cachés

La création de plugins pour les éditeurs ONLYOFFICE peut sembler simple, mais le développement dans le monde réel révèle souvent des défis inattendus, allant des goulots d’étranglement en matière de performances et des bizarreries du réseau aux différences subtiles entre les environnements web et de bureau. Cet article présente des conseils pratiques, des techniques éprouvées et les pièges courants que vous risquez de rencontrer lors de la création de plugins fiables qui fonctionnent sans heurts dans tous les éditeurs et scénarios de déploiement.

Pont et flux de travail

L’interface utilisateur de votre plugin s’exécute dans sa propre fenêtre et communique avec l’éditeur via un pont de messages. Ce pont fonctionne mieux avec de petites quantités de données et des modifications rapides et ciblées. Le fait de séparer le travail de votre interface utilisateur (comme la récupération de données ou le filtrage de listes) des modifications apportées au document (comme l’insertion de texte) rend tout plus rapide, plus facile à déboguer et plus prévisible lorsque plusieurs utilisateurs modifient le document en même temps.

Gardez les modifications apportées aux documents courtes et ciblées

Pourquoi : les commandes de l’éditeur s’exécutent en une seule fois ; le regroupement des modifications connexes évite les scintillements et maintient la cohérence de l’état du document.

Exemple (éditeur de document, insérer une citation) :

// UI side: prepare compact data
const citation = `${title} - ${source}${date ?  ', ' + date : ''}`;
Asc.scope.citation = citation;

// Editor side: run atomically
window.Asc.plugin.callCommand(function () {
  var doc = Api.GetDocument();
  var p = Api.CreateParagraph();
  p.AddText(Asc.scope.citation);
  doc.InsertContent([p]);
}, true);

Conseil : testez les appels API de l’éditeur dans l’espace de test afin de vérifier la syntaxe et le comportement avant de les intégrer au plugin.

Ne récupérez pas les données dans les commandes de l’éditeur

Pourquoi : l’attente des requêtes réseau dans une commande bloque l’éditeur.

Exemple (anti-modèle vs modèle correct) :

    // Anti-pattern: async in callCommand (don't do this)
window.Asc.plugin.callCommand(async function () {
  const res = await fetch(url);
  const text = await res.text();
  Api.GetDocument().InsertContent([Api.CreateParagraph().AddText(text)]);
}, true);

// Correct: fetch in the plugin window, then pass small data
const res = await fetch(url);
const text = await res.text().then(t => t.slice(0, 200)); // trim
Asc.scope.snippet = text;
window.Asc.plugin.callCommand(function () {
  var p = Api.CreateParagraph();
  p.AddText(Asc.scope.snippet);
  Api.GetDocument().InsertContent([p]);
}, true);

N’envoyez que de petites quantités de données via le pont

Pourquoi : le pont est optimisé pour les charges utiles de type JSON ; les chaînes de caractères volumineuses ou les objets imbriqués augmentent la latence.

Séparez le travail sur l’interface utilisateur et le travail sur les documents

Pourquoi : la récupération, l’analyse et le filtrage doivent être effectués dans la fenêtre de votre plugin ; seule l’insertion finale se fait dans la commande de l’éditeur.

Sécurité et mise en réseau

Les plugins récupèrent souvent du contenu provenant de sources externes telles que des flux RSS ou des API. Sans vérifications appropriées, vous pouvez accidentellement laisser entrer du code malveillant dans l’interface utilisateur de votre plugin, rencontrer des erreurs d’origine croisée qui bloquent les requêtes, ou échouer silencieusement lorsque vous mélangez HTTP et HTTPS. Un simple plan de sécurité et de mise en réseau permet d’éviter ces maux de tête.

Pratiques clés avec exemples

Nettoyez le code HTML non fiable avant de l’afficher

Pourquoi : les résumés ou extraits de flux peuvent contenir du code HTML qui perturbe votre interface utilisateur ou présente des risques pour la sécurité.

Exemple :

// Quick plain-text extraction
function toPlainText(html) {
  const tmp = document.createElement("div");
  tmp.innerHTML = html;
  return tmp. textContent || "";
}
const safeText = toPlainText(untrustedHtml);

// If rendering controlled HTML, use a sanitizer (e. g., DOMPurify)
// const safeHtml = DOMPurify.sanitize(untrustedHtml);
// container.innerHTML = safeHtml;

Préférez insérer du texte brut dans les documents

Justification : le texte brut évite les transferts de mise en forme inattendus et réduit la taille des charges utiles du pont ; réservez la mise en forme riche à une utilisation délibérée de l’API côté éditeur.

Utilisez le protocole HTTPS et évitez les contenus mixtes

Justification : les navigateurs bloquent les ressources HTTP dans les contextes sécurisés ; les échecs silencieux sont fréquents lorsque les points de terminaison ne sont pas HTTPS.

Utilisez un proxy simple pour les requêtes inter-origines

Justification : de nombreux points de terminaison n’autorisent pas l’accès direct entre origines ; un petit proxy ajoute des en-têtes CORS et normalise la sortie.

Exemple (schéma Node/Express) :

 // Minimal CORS/normalize proxy (server-side)
import express from "express";
import fetch from "node-fetch";

const app = express();
app.get("/feed", async (req, res) => {
  try {
    const url = new URL(req.query.src);
    const r = await fetch(url.toString(), { timeout: 8000 });
    const text = await r.text();
    // Convert to normalized JSON shape server-side as needed
    res.set("Access-Control-Allow-Origin", "*");
    res.json({ items: normalizeToCommonShape(text) });
  } catch (e) {
    res.set("Access-Control-Allow-Origin", "*");
    res.status(502).json({ error: "Upstream fetch failed" });
  }
});

app.listen(3000);

Performance, emballage et pré-expédition

Les plugins s’exécutent pendant que les utilisateurs modifient activement des documents, leur réactivité est donc essentielle. De bonnes habitudes en matière de performances, un packaging propre et des tests approfondis avant la mise en production permettent à votre plugin de rester rapide, prévisible et facile à mettre à jour.

Les performances dépendent de bonnes habitudes : débouncez les recherches et les filtres, virtualisez les longues listes, précalculez les chaînes exactes qui seront insérées afin de réduire le coût par action. À la fermeture, effacez les minuteries, annulez les requêtes en cours et supprimez les écouteurs afin d’éviter les fuites lentes qui s’accumulent au fil des sessions.

const controller = new AbortController();
const timer = setInterval(refresh, 300000);

window.Asc.plugin.button = function () {
  controller.abort();
  clearInterval(timer);
  window.Asc.plugin.executeCommand("close", "");
};

Pratiques clés

1. Regroupez vos fichiers JavaScript et CSS localement au lieu de dépendre de CDN externes.
2. Définissez vos propres palettes de couleurs claires et sombres au lieu de supposer que l’éditeur les fournira.
3. Maintenez votre identifiant de plugin (GUID) stable d’une version à l’autre afin que les mises à jour se déroulent sans problème.
4. Utilisez des numéros de version clairs (1.0.0, 1.1.0, 2.0.0) qui indiquent les modifications apportées.
5. Incluez toutes les icônes et métadonnées requises pour le gestionnaire de plugins et la marketplace.
6. Testez avec des URL similaires à celles de production afin de détecter les chemins d’accès aux images ou aux scripts qui ne fonctionnent pas.

Avant l’expédition, effectuez un contrôle compact mais rigoureux à l’aide des éditeurs pris en charge (document, feuille de calcul, présentation), les environnements (web et bureau), les thèmes (clair et sombre), la collaboration (insertions simultanées), les conditions réseau (hors ligne, lent, proxy en panne), la taille des ensembles de données (très petits et très grands) et un CSP plus strict sans scripts ni styles en ligne, afin que le comportement reste cohérent lorsque de vrais utilisateurs et de vrais réseaux testent le plugin.

Conclusion

Les plugins solides sont le fruit d’habitudes simples : préparez d’abord les données, modifiez les documents en une seule étape ciblée, nettoyez le contenu externe, acheminez les appels réseau via un petit proxy et regroupez tout localement afin que cela fonctionne de la même manière partout. Testez votre plugin sur différents éditeurs, environnements, thèmes et conditions réseau avant de le commercialiser, afin qu’il se comporte de manière prévisible lorsque de vrais utilisateurs et de vrais réseaux l’utilisent.