ONLYOFFICE Desktop-Plugin-Entwicklung und -Debugging aktivieren

Sie müssen in den ONLYOFFICE Desktop-Editoren keine separate Plugin-Entwicklung aktivieren. Erstellen Sie ein Plugin, installieren Sie das zugehörige .pluginPaket über den Plugin-Manager und starten Sie die Desktop-Anwendung, --ascdesktop-support-debug-infowenn Sie Debugging-Tools benötigen. Desktop- und Web-Editoren verwenden unterschiedliche Ladevorgänge. Beginnen Sie daher mit dem unten beschriebenen Workflow für den Desktop-Editor.

Bereiten Sie ein kleines Plugin-Projekt vor

Diese Anweisungen gelten für ONLYOFFICE Desktop-Editoren unter Windows, macOS und Linux. Verwenden Sie eine aktuelle Desktop-Installation und einen Code-Editor für Klartextdateien. Die offizielle Dokumentation behandelt die manuelle Plugin-Installation und das Entwickler-Debugging als separate Funktionen; der Plugin Marketplace ist für die Entwicklung und das Testen eines lokalen Plugins nicht erforderlich. Ein einfaches „Hello World“-Beispiel eignet sich gut als erster Test, da es das Laden von Plugins von komplexeren Diensten isoliert.

1. Erstellen Sie den Quellordner

Erstellen Sie einen Ordner mit dem Namen „“ hello-world-plugin. Fügen Sie eine config.jsonManifestdatei und einen index.htmlEinstiegspunkt hinzu. Optional können Sie ein icon.pngImage hinzufügen, falls Ihre Manifestdatei darauf verweist. Speichern Sie den Ordner außerhalb des Installationsverzeichnisses Ihrer Anwendung, damit Software-Updates Ihre Arbeitsdateien nicht überschreiben.

2. Definieren Sie das Manifest und generieren Sie Ihre eigene GUID.

Das Manifest teilt ONLYOFFICE mit, welche HTML-Datei geladen werden soll und welche Editoren das Plugin ausführen dürfen. Das folgende Beispiel unterstützt den Dokumenteditor. Ersetzen Sie die Beispiel-GUID vor der Installation durch eine neu generierte UUID: Führen Sie den Befehl New-Guidin Windows PowerShell oder uuidgenunter macOS bzw. Linux aus und formatieren Sie den Wert anschließend im entsprechenden Format asc.{YOUR-UUID}. Jedes Plugin benötigt eine eigene Kennung.

{
  "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"]
  }]
}

Verwenden Sie gültiges JSON: keine nachfolgenden Kommas, korrekte geschweifte Klammern und eine gültige Datei für jeden referenzierten Einstiegspunkt oder jedes Symbol. Verwenden Sie für ein Tabellenkalkulations- oder Präsentations-Plugin die entsprechenden Werte, EditorsSupportanstatt anzunehmen, dass ein reines Dokument-Plugin überall vorhanden ist. Vergleichen Sie die Struktur mit der offiziellen Hello-World-Schnellstartanleitung .

3. Den Einstiegspunkt implementieren

Laden Sie in index.htmlIhrer Datei die ONLYOFFICE-Plugin-API-Bibliothek, fügen Sie eine Schaltfläche hinzu und lassen Sie diese die entsprechende Funktion aufrufen . Das Schnellstartbeispielwindow.Asc.plugin.executeMethod("PasteText", ["Hello World!"]) des Herstellers enthält den vollständigen, lauffähigen HTML-Code und die Bibliotheks-URL. Das Kopieren dieses Beispiels ist sicherer, als die Initialisierung oder die API-Syntax zu erraten. Speichern Sie die Datei als UTF-8-kodierte Datei. Wenn Sie offline arbeiten möchten, denken Sie daran, dass eine Seite, die ihre Plugin-Bibliothek oder andere Ressourcen von einer Online-URL importiert, diese Ressourcen weiterhin zum Laden benötigt.

Installieren und starten Sie Ihr Entwicklungs-Plugin.

4. Erstellen Sie das .plugin-Archiv.

Wählen Sie die Dateien im Quellordner aus, komprimieren Sie sie in ein ZIP-Archiv und benennen Sie die ZIP-Dateiendung von `.zip` in ` .zip.zip` um .plugin. Das Archiv-Stammverzeichnis sollte `.zip` config.jsonund `.zip` enthalten index.html, kein zweites übergeordnetes hello-world-pluginVerzeichnis. Aktivieren Sie unter Windows die Dateinamenerweiterungen im Datei-Explorer, um versehentliche Erstellungen von `.zip`-Dateien zu vermeiden hello-world.plugin.zip. Die offizielle Installationsanleitung für Desktop Editors unterstützt ausdrücklich die manuelle Installation ohne Verbindung zum Marketplace.

5. Importieren Sie das Paket über den Plugin-Manager.

Öffnen Sie ein bearbeitbares Dokument in ONLYOFFICE Desktop Editors. Wählen Sie „Plugins“ > „Plugin-Manager“ > „Meine Plugins“ > „Plugin manuell installieren“ . Die genaue Darstellung des Managers kann je nach Version variieren, aber dies ist der dokumentierte Pfad für die manuelle Installation. Es handelt sich nicht um die separate Entwickler-URL-Einstellung des Marketplace.

6. Wählen Sie die Datei aus und überprüfen Sie deren Menüeintrag.

Wählen Sie Ihr hello-world.pluginArchiv im Dateidialog aus und öffnen Sie es. Das installierte Plugin sollte nun unter dem Reiter „Plugins“ verfügbar sein. Falls es fehlt, überprüfen Sie Manifest, GUID, unterstützten Editortyp und Archivverzeichnis, bevor Sie die Anwendungseinstellungen ändern. Versuchen Sie, nach der Installation ein Dokument erneut zu öffnen, falls das Menü nicht sofort aktualisiert wird.

7. Testen Sie das Plugin in einem temporären Dokument.

Öffnen Sie ein leeres Testdokument, starten Sie „Hello World“ über den Reiter „Plugins“ und klicken Sie auf die Schaltfläche. Prüfen Sie, ob die Wörter „Hello World!“ im Dokument erscheinen. Dies überprüft mehr als nur die Installation: Es bestätigt, dass die Plugin-Schnittstelle geladen wurde und der zugehörige API-Aufruf das Dokument erreicht hat. Testen Sie Plugins, die den Inhalt verändern, nicht an unersetzlichen Dateien.

Debugging für die Plugin-Entwicklung aktivieren

8. Starten Sie die Desktop-Editoren mit dem Debug-Flag neu.

Schließen Sie ONLYOFFICE Desktop Editors vollständig und starten Sie die Anwendung anschließend über ein Terminal mit dem offiziellen Debug-Flag. Verwenden Sie den Befehl, der für Ihr Betriebssystem und Ihren Installationsort relevant ist:

• Windows-Eingabeaufforderung: "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
• Linux (Standard-Paketspeicherort): "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
• macOS: "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

Der obige Windows-Befehl verwendet die Variablenerweiterung der Eingabeaufforderung, nicht die PowerShell-Syntax. In PowerShell rufen Sie die ausführbare Datei mit ihrem vollständigen Pfad auf. Wenn Ihre Anwendung an einem nicht standardmäßigen Ort installiert wurde, ersetzen Sie den Platzhalter durch den tatsächlichen Pfad der ausführbaren Datei. Sie können den Parameter auch dem Zielfeld einer Windows-Desktopverknüpfung hinzufügen. Weitere Informationen zu den Plattformen finden Sie in der Dokumentation zu den Desktop-Debug-Modus-Befehlen von ONLYOFFICE .

Sobald das Dokument geöffnet ist, klicken Sie in den Bearbeitungsbereich und drücken Sie F1 oder klicken Sie mit der rechten Maustaste auf ein bearbeitbares Symbolleistenfeld und wählen Sie „ Element untersuchen“ . Wählen Sie in den Entwicklertools den Plugin-iFrame aus, um den Plugin-Schnittstellencode und die Protokolle zu untersuchen. Der übergebene Code wird stattdessen callCommandim frameEditorKontext ausgeführt; wechseln Sie daher gegebenenfalls den Frame. Die Plugin-Debugging-Referenz erläutert diesen Unterschied und die Verwendung von Haltepunkten. Beim Debuggen können Dokumentinhalte und Laufzeitdetails offengelegt werden; geben Sie daher keine Rohprotokolle weiter, ohne sie vorher geprüft zu haben.

Den Bearbeitungs- und Testzyklus verkürzen, ohne die integrierten Plugins zu verändern.

Nach der manuellen Installation kopiert ONLYOFFICE ein Plugin in ein GUID-benanntes Verzeichnis unter Ihrem Benutzerprofil. Die dokumentierten Speicherorte sind %LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\für Windows, ~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/macOS und ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/Linux angegeben. Der GUID-benannte Ordner enthält nicht die asc.im Manifest verwendete führende URL.

Um zu vermeiden, dass für jede Änderung ein neues Archiv erstellt wird, können Entwickler die Anwendung schließen, ihren eigenen Plugin-Ordner durch einen symbolischen Link zum Quellcode-Ordner ersetzen und das Dokument nach der Bearbeitung wieder öffnen. Dies ist optional, und die genauen Link-Befehle unterscheiden sich je nach Betriebssystem. Beachten Sie vorab die offiziellen Anweisungen zur Desktop-Entwicklung . Ersetzen Sie keine mitgelieferten/Standard-Plugin-Ordner und verändern Sie nicht das macOS-Anwendungspaket: Der Hersteller warnt davor, dass das Entfernen von Standard-Plugins die Paketintegrität beeinträchtigen und zu Abstürzen führen kann.

Überprüfen Sie die Entwicklungsumgebung

Drei Prüfungen zeigen an, dass der Workflow bereit ist: Das benutzerdefinierte Plugin erscheint unter „Plugins“ , der „Hello World“-Test fügt Text in ein neues Dokument ein, und die Entwicklertools öffnen sich nach dem Start mit aktiviertem Debug-Flag. Falls die Benutzeroberfläche leer ist oder die Installation fehlschlägt, überprüfen Sie, ob das Manifest als JSON geparst wird, die GUID mit „“ beginnt asc., index.htmlsich im angegebenen relativen Pfad befindet und alle benötigten Ressourcen vorhanden sind. Die offizielle Fehleranleitung für Plugins beschreibt diese häufigen Fehler. Ein installiertes Plugin ist kein Beweis dafür, dass alle implementierten Funktionen funktionieren; wiederholen Sie dieselbe Prüfung nach jeder Codeänderung.