Erstellung von ONLYOFFICE-Plugins: Tipps, Tricks und versteckte Fallstricke

Die Entwicklung von Plugins für ONLYOFFICE-Editoren kann unkompliziert sein, doch in der Praxis treten oft unerwartete Herausforderungen auf – von Performance-Engpässen und Netzwerkproblemen bis hin zu subtilen Unterschieden zwischen Web- und Desktop-Umgebungen. Dieser Artikel bietet praktische Tipps, bewährte Techniken und Hinweise zu häufigen Fehlern, die Ihnen bei der Erstellung zuverlässiger Plugins begegnen können, die in verschiedenen Editoren und Einsatzszenarien reibungslos funktionieren.

Schnittstelle und Workflow

Die Benutzeroberfläche Ihres Plugins läuft in einem eigenen Fenster und kommuniziert über eine Nachrichtenschnittstelle mit dem Editor. Diese Schnittstelle eignet sich am besten für kleine Datenmengen und schnelle, zielgerichtete Bearbeitungen. Indem Sie die Bearbeitung Ihrer Benutzeroberfläche (z. B. Datenabruf oder Listenfilterung) von Dokumentänderungen (z. B. Einfügen von Text) trennen, beschleunigen Sie den gesamten Prozess, vereinfachen die Fehlersuche und erhöhen die Vorhersagbarkeit, wenn mehrere Benutzer gleichzeitig bearbeiten.

Dokumentbearbeitungen kurz und prägnant halten

Warum: Editorbefehle werden in einem Schritt ausgeführt; die Gruppierung zusammengehöriger Änderungen verhindert Flackern und sorgt für einen konsistenten Dokumentstatus.

Beispiel (Dokumenteditor, Zitat einfügen):

// 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);

Tipp: Testen Sie die Editor-API-Aufrufe in der Playground-Umgebung, um Syntax und Verhalten zu überprüfen, bevor Sie sie in das Plugin integrieren.

Daten nicht innerhalb von Editorbefehlen abrufen

Warum: Das Warten auf Netzwerkanfragen innerhalb eines Befehls führt zum Einfrieren des Editors.

Beispiel (Anti-Pattern vs. korrekt):

    // 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);

Nur kleine Datenmengen über die Bridge senden

Grund: Die Bridge ist für JSON-ähnliche Nutzdaten optimiert; lange Zeichenketten oder verschachtelte Objekte erhöhen die Latenz.

Die Arbeit mit der Benutzeroberfläche und die Dokumentbearbeitung trennen

Warum: Daten abrufen, analysieren und filtern gehören in das Plugin-Fenster; nur das Einfügen erfolgt im Editor.

Sicherheit und Netzwerk

Plugins beziehen häufig Inhalte aus externen Quellen wie RSS-Feeds oder APIs. Ohne entsprechende Prüfungen kann es passieren, dass schädlicher Code versehentlich in die Benutzeroberfläche des Plugins gelangt, Cross-Origin-Fehler auftreten, die Anfragen blockieren, oder dass es bei der gleichzeitigen Verwendung von HTTP und HTTPS zu unbemerkten Fehlern kommt. Ein einfaches Sicherheits- und Netzwerkkonzept beugt diesen Problemen vor.

Wichtige Vorgehensweisen mit Beispielen

Nicht vertrauenswürdiges HTML vor der Anzeige entfernen

Warum: Feed-Zusammenfassungen oder -Ausschnitte können HTML enthalten, das Ihre Benutzeroberfläche beeinträchtigt oder Sicherheitsrisiken birgt.

Beispiel:

// 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;

Das Einfügen von Klartext in Dokumente bevorzugen

Begründung: Klartext vermeidet unerwartete Formatierungsänderungen und hält die Datenmenge gering. Formatierungen sollten für die gezielte Verwendung mit der Editor-seitigen API reserviert werden.

HTTPS verwenden und gemischte Inhalte vermeiden

Begründung: Browser blockieren HTTP-Ressourcen in sicheren Kontexten; stille Fehler sind häufig, wenn Endpunkte nicht HTTPS-verschlüsselt sind.

Verwendung eines einfachen Proxys für ursprungsübergreifende Anfragen

Begründung: Viele Endpunkte erlauben keinen direkten ursprungsübergreifenden Zugriff; ein kleiner Proxy fügt CORS-Header hinzu und normalisiert die Ausgabe.

Beispiel (Node/Express-Skizze):

 // 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, Paketierung und Vorbereitung

Plugins laufen, während Benutzer aktiv Dokumente bearbeiten. Daher ist Reaktionsfähigkeit entscheidend. Gute Performance-Praktiken, eine saubere Paketierung und gründliche Tests vor der Veröffentlichung sorgen dafür, dass Ihr Plugin schnell, zuverlässig und einfach zu aktualisieren ist.

Die Performance hängt von konsistenten Vorgehensweisen ab: Entprellung von Suchvorgängen und Filtern, Virtualisierung langer Listen, Vorberechnung der einzufügenden Zeichenketten, um die Kosten pro Aktion zu reduzieren. Beim Schließen sollten Timer gelöscht, laufende Anfragen abgebrochen und Listener entfernt werden, um schleichende Speicherlecks über mehrere Sitzungen hinweg zu vermeiden.

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

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

Wichtige Vorgehensweisen

1. Bündeln Sie Ihr JavaScript und CSS lokal, anstatt externe CDNs zu verwenden.
2. Definieren Sie Ihre eigenen hellen und dunklen Farbschemata, anstatt davon auszugehen, dass der Editor diese bereitstellt.
3. Halten Sie Ihre Plugin-ID (GUID) versionsübergreifend stabil, damit Updates reibungslos funktionieren.
4. Verwenden Sie aussagekräftige Versionsnummern (1.0.0, 1.1.0, 2.0.0), die die Änderungen kennzeichnen.
5. Fügen Sie alle erforderlichen Symbole und Metadaten für den Plugin-Manager und den Marketplace hinzu.
6. Testen Sie mit produktionsnahen URLs, um fehlerhafte Bild- oder Skriptpfade zu erkennen.

Vor der Auslieferung sollte ein kompakter, aber strenger Testlauf über unterstützte Editoren (Dokument, Tabellenkalkulation, Präsentation), Umgebungen (Web und Desktop), Designs (hell und dunkel), Kollaboration (gleichzeitiges Einfügen), Netzwerkbedingungen (offline, langsam, Proxy-Ausfall), Datensatzgrößen (sehr klein und sehr groß) und eine strengere CSP ohne Inline-Skripte oder Stile durchgeführt werden, um sicherzustellen, dass das Verhalten konsistent bleibt, wenn echte Benutzer und echte Netzwerke das Plugin testen.

Fazit

Gute Plugins entstehen durch einfache Vorgehensweisen: Daten vorbereiten, Dokumentänderungen in einem Schritt durchführen, externe Inhalte bereinigen, Netzwerkaufrufe über einen kleinen Proxy leiten und alles lokal packen, damit es überall gleich funktioniert. Testen Sie Ihr Plugin vor der Veröffentlichung in verschiedenen Editoren, Umgebungen, Themes und Netzwerkumgebungen, damit es sich unter realen Benutzerbedingungen und in realen Netzwerken vorhersehbar verhält.