Activer le développement et le débogage du plugin ONLYOFFICE Desktop

Il n'est pas nécessaire d'activer un paramètre de développement de plugins distinct dans ONLYOFFICE Desktop Editors. Créez un plugin, installez son .pluginpackage via le Gestionnaire de plugins, puis lancez l'application de bureau --ascdesktop-support-debug-infolorsque vous avez besoin d'outils de débogage. Les éditeurs de bureau et web utilisent des procédures de chargement différentes ; commencez donc par suivre la procédure spécifique à la version de bureau ci-dessous.

Préparer un petit projet de plugin

Ces instructions s'appliquent aux éditeurs de bureau ONLYOFFICE sous Windows, macOS et Linux. Utilisez une installation de bureau à jour et un éditeur de code pour les fichiers texte. La documentation officielle traite l'installation manuelle des plugins et le débogage pour développeurs comme des fonctionnalités distinctes ; le Plugin Marketplace n'est pas nécessaire pour développer et tester un plugin local. Un exemple « Hello World » est un bon point de départ, car il permet d'isoler le chargement du plugin des services plus complexes.

1. Créez le dossier source

Créez un dossier nommé `.yml` hello-world-plugin. Ajoutez-y un config.jsonfichier manifeste et un index.htmlpoint d'entrée. Vous pouvez également ajouter une icon.pngimage si votre manifeste en référence une. Placez ce dossier en dehors du répertoire d'installation de l'application afin d'éviter que les mises à jour logicielles n'écrasent vos fichiers de travail.

2. Définissez le manifeste et générez votre propre GUID

Le fichier manifeste indique à ONLYOFFICE quel fichier HTML charger et quels éditeurs peuvent exécuter le plugin. L'exemple suivant concerne l'éditeur de documents. Remplacez le GUID d'exemple par un UUID nouvellement généré avant l'installation : exécutez la commande suivante New-Guiddans Windows PowerShell ou, uuidgensur macOS ou Linux, formatez la valeur comme suitasc.{YOUR-UUID} : `<UID_UID_UID>`. Chaque plugin distinct nécessite son propre identifiant.

{
  "name": "Hello World",
  "guid": "asc.{12345678-1234-1234-1234-1234567890AB}",
  "version": "1.0.0",
  "variations": [{
    "url": "index.html",
    "icons": ["icon.png"],
    "isViewer": false,
    "EditorsSupport": ["word"]
  }]
}

Utilisez un JSON valide : pas de virgules finales, des accolades correspondantes et un fichier réel pour chaque point d’entrée ou icône référencé. Pour un plugin de type tableur ou présentation, utilisez les valeurs appropriées au lieu de supposer qu’un plugin de type document est présent partout. Comparez la structure avec le guide de démarrage rapideEditorsSupport officiel « Hello World » .

3. Mettre en œuvre le point d'entrée

Dans le fichier index.html, chargez la bibliothèque API du plugin ONLYOFFICE, ajoutez un bouton et faites en sorte que ce bouton appelle la fonction correspondante . L'exemple de démarrage rapidewindow.Asc.plugin.executeMethod("PasteText", ["Hello World!"]) du fabricant fournit le code HTML complet et fonctionnel ainsi que l'URL de la bibliothèque ; il est plus sûr de copier cet exemple que de deviner l'initialisation ou la syntaxe de l'API. Enregistrez le fichier au format UTF-8. Si vous prévoyez de travailler hors ligne, n'oubliez pas qu'une page qui importe sa bibliothèque de plugins ou d'autres ressources depuis une URL en ligne a toujours besoin de ces ressources pour se charger.

Installez et exécutez votre plugin de développement

4. Créez l'archive .plugin

Sélectionnez les fichiers du dossier source, compressez-les dans une archive ZIP et renommez l'extension ZIP en .zip.zip .plugin. Le répertoire racine de l'archive doit contenir `<nom_du_dossier>` config.jsonet index.html`<nom_du_dossier>`, sans second hello-world-pluginrépertoire parent. Sous Windows, activez l'affichage des extensions de fichiers dans l'Explorateur de fichiers afin d'éviter la création accidentelle de fichiers `.zip` hello-world.plugin.zip. Les instructions d'installation officielles de Desktop Editors prennent explicitement en charge l'installation manuelle sans connexion au Marketplace.

5. Importez le package depuis le Gestionnaire de plugins

Ouvrez un document modifiable dans ONLYOFFICE Desktop Editors. Sélectionnez Modules d'extension > Gestionnaire de modules d'extension > Mes modules d'extension > Installer le module d'extension manuellement . L'apparence exacte du gestionnaire peut varier selon la version, mais cette action correspond à la procédure d'installation manuelle documentée. Il ne s'agit pas de l'URL développeur distincte du Marketplace.

6. Sélectionnez le fichier et vérifiez son entrée de menu

Sélectionnez votre hello-world.pluginarchive dans la boîte de dialogue et ouvrez-la. Le plugin installé devrait apparaître dans l'onglet « Plugins ». S'il est absent, vérifiez le manifeste, le GUID, le type d'éditeur compatible et le répertoire racine de l'archive avant de modifier les paramètres de l'application. Si le menu ne s'actualise pas immédiatement après l'installation, essayez de rouvrir un document.

7. Testez le plugin dans un document jetable

Ouvrez un document de test vierge, lancez le plugin « Hello World » depuis l'onglet « Extensions » et utilisez son bouton. Vérifiez que le texte « Hello World ! » apparaît bien dans le document. Cette vérification va au-delà de la simple installation : elle confirme que l'interface du plugin s'est chargée et que son appel API a bien atteint le document. Ne testez pas les plugins modifiant le contenu sur un fichier irremplaçable.

Activer le débogage pour le développement de plugins

8. Relancez les éditeurs de bureau avec l'indicateur de débogage

Fermez complètement ONLYOFFICE Desktop Editors, puis lancez l'application depuis un terminal avec l'option de débogage officielle. Utilisez la commande correspondant à votre système d'exploitation et à votre emplacement d'installation :

• Invite de commandes Windows : "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
• Linux (emplacement standard des paquets) : "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
• macOS : "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

La commande Windows ci-dessus utilise l'expansion des variables de l'invite de commandes, et non la syntaxe PowerShell ; en PowerShell, appelez l'exécutable avec son chemin complet. Si votre application est installée dans un emplacement non standard, indiquez le chemin réel de l'exécutable. Vous pouvez également ajouter l'indicateur au champ Cible d'un raccourci sur le Bureau Windows. Consultez la documentation d'ONLYOFFICE sur les commandes du mode débogage pour plus d'informations sur les plateformes.

Une fois le document ouvert, cliquez dans sa zone d'édition et appuyez sur F1 , ou cliquez avec le bouton droit sur un champ modifiable de la barre d'outils et choisissez « Inspecter l'élément » . Dans les outils de développement, sélectionnez l'iframe du plugin pour examiner le code de son interface et ses journaux. Le code transmis callCommands'exécute dans le frameEditorcontexte du plugin ; changez donc d'iframe si nécessaire. La documentation de débogage des plugins explique cette distinction et comment utiliser les points d'arrêt. Le débogage peut révéler le contenu du document et des détails d'exécution ; ne partagez pas les journaux bruts sans les avoir vérifiés.

Raccourcir le cycle édition-test sans modifier les plugins intégrés

Après une installation manuelle, ONLYOFFICE copie le plugin dans un répertoire nommé par un GUID sous votre profil utilisateur. Les emplacements documentés sont les %LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\suivants : sous Windows, ~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/sous macOS et ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/sous Linux. Le nom du dossier, identifié par un GUID, ne contient pas le préfixe asc.utilisé dans le manifeste.

Pour éviter de créer une nouvelle archive à chaque modification, les développeurs peuvent fermer l'application, remplacer leur dossier de plugins installé par un lien symbolique vers le dossier source de travail, puis rouvrir le document après modification. Cette opération est facultative et les commandes de lien exactes varient selon le système d'exploitation. Veuillez suivre les instructions officielles de développement pour ordinateur avant de procéder. Ne remplacez pas les dossiers de plugins intégrés/par défaut et ne modifiez pas le package de l'application macOS : l'éditeur avertit que la suppression des plugins par défaut peut compromettre l'intégrité du package et provoquer des plantages.

Vérifiez la configuration de développement

Trois vérifications indiquent que le flux de travail est prêt : le plugin personnalisé apparaît dans la liste des plugins , le test « Hello World » insère du texte dans un nouveau document et les outils de développement s’ouvrent après un lancement avec l’option de débogage. Si l’interface est vide ou si l’installation échoue, vérifiez que le manifeste est bien analysé au format JSON, que le GUID commence par ` asc./ var/lib index.html...