Comment ajouter des fonctionnalités personnalisées au plugin IA d’ONLYOFFICE

Le plugin IA d’ONLYOFFICE a introduit une nouvelle architecture conviviale pour les développeurs. Si vous souhaitez étendre les capacités du plugin, par exemple pour ajouter une fonction IA spécifique, vous n’avez plus besoin de modifier un fichier monolithique volumineux.

À la place, le plugin dispose désormais d’un espace de travail dédié situé dans le dossier .dev. Ce guide vous montrera exactement comment utiliser cet espace de travail pour ajouter une nouvelle fonction personnalisée.

Nous allons créer la fonctionnalité « Décrire l’image » pour l’éditeur de documents à titre d’exemple.

Le processus de développement

Le concept de base est simple : vous travaillez dans .dev, et un script génère le code de production.

• .dev/helpers/ : C’est votre bac à sable. C’est ici que vous créez de nouveaux fichiers.
• helpers.js : Il s’agit du fichier de production que le plugin lit réellement. Ne le modifiez pas directement. Il est généré automatiquement.

Étape 1 : Choisissez la portée de votre éditeur

Dans .dev/helpers/, vous trouverez trois dossiers correspondant aux éditeurs ONLYOFFICE :

• word/ (éditeur de documents texte)
• cell/ (éditeur de feuilles de calcul)
• slide/ (éditeur de présentations)

Étant donné que notre fonction de description d’image est destinée aux documents texte, nous travaillerons dans .dev/helpers/word/.

Étape 2 : Créez votre propre fonction

Créez un nouveau fichier nommé describe-image.js dans .dev/helpers/word/.

Le plugin utilise une classe spécifique appelée RegisteredFunction pour définir les capacités. Cette structure indique à l’IA ce que fait la fonction et comment l’appeler.

Conseil : assurez-vous que votre syntaxe est correcte (vérifiez qu’il ne manque pas de parenthèses fermantes).

Le code :

<code class="language-javascript">(<span class="hljs-function">function</span><span class="hljs-function"> (</span><span class="hljs-function">) </span>{
  let func = new RegisteredFunction({
    <span class="hljs-attr">name</span>: "describeImage",
    <span class="hljs-attr">description</span>:
      "Allows users to select an image and generate a meaningful title, description, caption, or alt text for it using AI.",
    // Define parameters so the AI knows what to ask for
    <span class="hljs-attr">parameters</span>: {
      <span class="hljs-attr">type</span>: "object",
      <span class="hljs-attr">properties</span>: {
        <span class="hljs-attr">prompt</span>: {
          <span class="hljs-attr">type</span>: "string",
          <span class="hljs-attr">description</span>:
            "instruction for the AI (e.g., 'Add a short title for this chart.')",
        },
      },
      <span class="hljs-attr">required</span>: ["prompt"],
    },
    // Provide examples to train the AI on usage
    <span class="hljs-attr">examples</span>: [
      {
        <span class="hljs-attr">prompt</span>: "Add a short title for this chart.",
        <span class="hljs-attr">arguments</span>: { <span class="hljs-attr">prompt</span>: "Add a short title for this chart." },
      },
      {
        <span class="hljs-attr">prompt</span>: "Write me a 1–2 sentence description of this photo.",
        <span class="hljs-attr">arguments</span>: {
          <span class="hljs-attr">prompt</span>: "Write me a 1–2 sentence description of this photo.",
        },
      },
      {
        <span class="hljs-attr">prompt</span>: "Generate a descriptive caption for this organizational chart.",
        <span class="hljs-attr">arguments</span>: {
          <span class="hljs-attr">prompt</span>:
            "Generate a descriptive caption for this organizational chart.",
        },
      },
      {
        <span class="hljs-attr">prompt</span>: "Provide accessibility-friendly alt text for this infographic.",
        <span class="hljs-attr">arguments</span>: {
          <span class="hljs-attr">prompt</span>:
            "Provide accessibility-friendly alt text for this infographic.",
        },
      },
    ],
  });

   // The actual logic executed inside the editor
  func.call = async <span class="hljs-function">function</span><span class="hljs-function"> (</span><span class="hljs-function hljs-params">params</span><span class="hljs-function">) </span>{
    let prompt = params.prompt;

    async <span class="hljs-function">function</span> <span class="hljs-function">insertMessage</span><span class="hljs-function">(</span><span class="hljs-function hljs-params">message</span><span class="hljs-function">) </span>{
      Asc.scope._message = String(message || "");
      // 3. Insert the result into the document
      await Asc.Editor.callCommand(<span class="hljs-function">function</span><span class="hljs-function"> (</span><span class="hljs-function">) </span>{
        const msg = Asc.scope._message || "";
        const doc = Api.GetDocument();
        const selected =
          (doc.GetSelectedDrawings && doc.GetSelectedDrawings()) || [];
        if (selected.length > 0) {
          for (let i = 0; i < selected.length; i++) {
            const drawing = selected[i];
            const para = Api.CreateParagraph();
            para.AddText(msg);
            drawing.InsertParagraph(para, "after", true);
          }
        } else {
          const para = Api.CreateParagraph();
          para.AddText(msg);
          let range = doc.GetCurrentParagraph();
          range.InsertParagraph(para, "after", true);
        }
        Asc.scope._message = "";
      }, true);
    }

    try {
    // 1. Get the selected image
      let imageData = await new Promise(<span class="hljs-function">(</span><span class="hljs-function hljs-params">resolve</span><span class="hljs-function">) =></span> {
        window.Asc.plugin.executeMethod(
          "GetImageDataFromSelection",
          [],
          <span class="hljs-function">function</span><span class="hljs-function"> (</span><span class="hljs-function hljs-params">result</span><span class="hljs-function">) </span>{
            resolve(result);
          }
        );
      });

      if (!imageData || !imageData.src) {
        await insertMessage("Please select a valid image first.");
        return;
      }

      const whiteRectangleBase64 =
        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
      if (imageData.src === whiteRectangleBase64) {
        await insertMessage("Please select a valid image first.");
        return;
      }

      let argPrompt = prompt + " (for the selected image)";
      // 2. Send image + prompt to the AI engine
      let requestEngine = AI.Request.create(AI.ActionType.Chat);
      if (!requestEngine) {
        await insertMessage("AI request engine not available.");
        return;
      }

      const allowVision = /(vision|gemini|gpt-4o|gpt-4v|gpt-4-vision)/i;
      if (!allowVision.test(requestEngine.modelUI.name)) {
        await insertMessage(
          "⚠ This model may not support images. Please choose a vision-capable model (e.g. GPT-4V, Gemini, etc.)."
        );
        return;
      }

      await Asc.Editor.callMethod("StartAction", [
        "Block",
        "AI (" + requestEngine.modelUI.name + ")",
      ]);
      await Asc.Editor.callMethod("StartAction", ["GroupActions"]);

      let messages = [
        {
          <span class="hljs-attr">role</span>: "user",
          <span class="hljs-attr">content</span>: [
            { <span class="hljs-attr">type</span>: "text", <span class="hljs-attr">text</span>: argPrompt },
            {
              <span class="hljs-attr">type</span>: "image_url",
              <span class="hljs-attr">image_url</span>: { <span class="hljs-attr">url</span>: imageData.src, <span class="hljs-attr">detail</span>: "high" },
            },
          ],
        },
      ];

      let resultText = "";
      await requestEngine.chatRequest(messages, false, async <span class="hljs-function">function</span><span class="hljs-function"> (</span><span class="hljs-function hljs-params">data</span><span class="hljs-function">) </span>{
        if (data) {
          resultText += data;
        }
      });

      await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
      await Asc.Editor.callMethod("EndAction", [
        "Block",
        "AI (" + requestEngine.modelUI.name + ")",
      ]);

      Asc.scope.text = resultText || "";

      if (!Asc.scope.text.trim()) {
        await insertMessage(
          "⚠ AI request failed (maybe the model cannot handle images)."
        );
        return;
      }
      await insertMessage(Asc.scope.text);
    } catch (e) {
      try {
        await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
        await Asc.Editor.callMethod("EndAction", [
          "Block",
          "AI (describeImage)",
        ]);
      } catch (ee) {
        /* ignore */
      }
      console.error("describeImage error:", e);
      await insertMessage(
        "An unexpected error occurred while describing the image."
      );
    }
  };

  return func;
})();</code>

Étape 3 : Mettez à jour la version du plugin

Avant de compiler et de tester vos modifications, il est recommandé de mettre à jour la version du plugin. Cela garantit que ONLYOFFICE traite votre version comme un nouveau plugin, évite les problèmes de mise en cache et facilite le suivi des modifications au fil du temps.

Ouvrez le fichier config.json dans votre dossier de plugins.

Augmentez la version d’un niveau de correctif, par exemple :

<code class="language-javascript">"version": "3.0.0" to "3.1.0"
</code>

Ceci est recommandé pour les éditeurs de bureau et Web :

Bureau : garantit que l’application recharge le plugin mis à jour.

Web (y compris les liens vers les boutiques personnalisées) : empêche la mise en cache d’ignorer vos modifications dans helpers.js.

Étape 4 : Compilez vos modifications

Il s’agit de l’étape la plus importante du nouveau flux de travail. Le plugin ne peut pas encore lire directement votre nouveau fichier. Vous devez exécuter le script d’aide pour fusionner votre nouveau fichier dans la logique principale du plugin.

1. Ouvrez votre terminal.
2. Accédez au répertoire des aides :

   <code class="language-javascript">cd .dev/helpers</code>

3. Exécutez le script de compilation Python :

   <code class="language-javascript">python3 helpers.py
   </code>

Le script helpers.py analysera les dossiers word/, cell/ et slide/, trouvera votre nouveau fichier describe-image.js et le fusionnera dans le fichier principal helpers.js.

Étape 5 : Créez le fichier .plugin

• Sélectionnez tout le contenu du plugin.
• Compressez-le.
• Renommez l’archive de .zip en .plugin.
• Placez-la dans un dossier nommé deploy à l’intérieur de votre plugin.

Étape 6 : Remplacez le plugin dans ONLYOFFICE

Éditeurs de bureau

Dans les versions récentes d’ONLYOFFICE Desktop Editors, le plugin IA est inclus par défaut. Si vous utilisez une version plus ancienne dans laquelle le plugin n’était pas encore intégré, le processus d’installation dépend de votre situation et suit deux chemins possibles :

A) Installation du plugin IA pour la première fois

Si le plugin AI est absent de votre répertoire local de plugins :

1. Ouvrez ONLYOFFICE Desktop Editors.
2. Allez dans Modules complémentaires → Gestionnaire de plugins → Plugins disponibles → Installer le plugin manuellement.
3. Lorsque vous êtes invité à sélectionner un fichier, choisissez votre fichier .plugin compilé.

B) Mise à jour d’une copie locale existante du plugin IA

Si le plugin est déjà présent sur votre système :

1. Allez dans ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins
2. Recherchez le dossier dont le nom correspond au GUID du plugin dans config.json – {9DC93CDB-B576-4F0C-B55E-FCC9C48DD007}
3. Remplacez le dossier par votre nouveau plugin.
4. Redémarrez l’application de bureau.

Éditeur Web (via lien vers boutique personnalisée)

Lien vers la boutique personnalisée

Activez GitHub Pages pour votre fork.

Veillez à incrémenter la version dans config.json afin d’éviter les problèmes de mise en cache.

1. Créez une fourche du référentiel ONLYOFFICE Plugin Marketplace. Vous obtiendrez une copie à l’adresse suivante :
   https://github.com/YOUR-USERNAME/ONLYOFFICE/onlyoffice.github.io
2. Assurez-vous que votre dossier de plugins comprend un dossier deploy contenant le fichier .plugin.
3. Ajoutez votre dossier de plugins à :
   onlyoffice.github.io/sdkjs-plugins/content/ai/
4. Créez votre site GitHub Pages à partir de ce référentiel (voir la documentation GitHub Pages
5. Préparez un lien vers votre boutique personnalisée en ajoutant /store/index.html à votre URL GitHub Pages :
   https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html
6. Augmentez la version du plugin dans config.json (comme décrit à l’étape 3) pour contourner la mise en cache.

Mettre à jour le plugin

Avant de le mettre à jour avec votre version personnalisée, vous devrez peut-être supprimer la version préinstallée, selon votre configuration.

• Vérifiez si le plugin AI est déjà installé.

Ouvrez l’éditeur Web et accédez à Modules complémentaires → Gestionnaire de plugins.

Si le plugin AI est installé, supprimez-le :

Si ce n’est pas le cas, passez à l’étape suivante.

Cela garantit que la version personnalisée peut être installée ou mise à jour sans conflit.

• Ajoutez votre boutique personnalisée

Cliquez sur l’icône de la boutique dans le coin supérieur droit du gestionnaire de plugins :

Entrez l’URL personnalisée de votre boutique :

https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html

Votre boutique personnalisée apparaîtra désormais dans le gestionnaire de plugins.

• Installez le plugin AI

Une fois votre boutique personnalisée chargée, recherchez IA dans la liste et cliquez sur Installer.

Étape 7 : Testez votre fonctionnalité

1. Rechargez le plugin dans ONLYOFFICE.
2. Sélectionnez une image dans votre document.
3. Demandez à l’IA : « Décrivez cette image » ou « Écrivez une légende pour cette image ».

L’IA reconnaîtra désormais votre nouvelle fonction personnalisée et exécutera la logique que vous venez d’écrire.