Was gibt es Neues in der ONLYOFFICE API 9.4: Entwicklerleitfaden zu den neuesten Updates

Version 9.4 von ONLYOFFICE führt wichtige API-Verbesserungen für Integrationen, benutzerdefinierte Plugins und Tabellenkalkulationautomatisierung ein. Dieser Artikel hebt die wichtigsten Updates in der ONLYOFFICE Docs API, der Plugins- und Makros-API sowie der Office JavaScript API hervor und erklärt, was sie für Entwickler bedeuten.

ONLYOFFICE Docs API 9.4

Unterstützung der kroatischen Sprache

Kroatisch (hr) wurde zur Liste der unterstützten Benutzerschnittstellensprachen hinzugefügt. Wenn Sie lokalisierte Anwendungen für kroatischsprachige Benutzer erstellen, können Sie es ohne Umgehungslösungen in Ihre Sprachkonfiguration aufnehmen.

Rollen- und Benutzerdaten im onStartFilling-Ereignis

Das onStartFilling-Ereignis enthält jetzt einen roles-Parameter, der Rollen- und Benutzerinformationen überträgt. Dies erleichtert das Erstellen von rollenbewussten Formularfüllungserfahrungen erheblich, indem Benutzer beispielsweise zu den Feldern geleitet werden, für die sie verantwortlich sind, oder bedingte Logik ausgelöst wird, basierend darauf, wer das Formular ausfüllt und in welcher Funktion.

function onStartFilling(event) {
  const roles = event.data;
  console.log("Rollen:", roles);
}

const config = {
  // ...
  events: {
    onStartFilling,
  },
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);

Speicherleckbehebung in destroyEditor

Ein Speicherleck in der destroyEditor-Methode wurde behoben. Zuvor wurde beim Aufruf von destroyEditor nicht vollständig auf die zugewiesenen Ressourcen zugegriffen. Wenn Ihre Anwendung häufig Editorinstanzen erstellt und zerstört, wie dies bei Single-Page-Anwendungs-Setups oder Dokumentenvorschau-Workflows der Fall ist, verbessert diese Behebung direkt den Speicherbedarf Ihrer Integration im Laufe der Zeit.

Entferntes Feld

Das veraltete Feld editorConfig.customization.commentAuthorOnly wurde entfernt. Wenn Ihre Integration dieses Parameter weiterhin referenziert, ist jetzt der richtige Zeitpunkt, es zu entfernen, um unerwartete Verhaltensweisen zu vermeiden.

Plugin-Befehlsprotokollierung für einfacheres Debugging

Eine der praktischsten Ergänzungen für Plugin-Entwickler ist die Plugin-Befehlsprotokollierung. Aktivieren Sie die Debug-Ausgabe von Plugin-Befehlen direkt in der Browser-Konsole. Wenn Sie Zeit mit dem Debuggen des Plugin-Verhaltens verbracht haben, indem Sie erraten haben, welche Befehle tatsächlich ausgeführt werden, beseitigt diese Funktion erheblich viele davon Probleme. Sie erhalten direkten Einblick in den Ausführungsfluss des Plugins, ohne Ihre eigene Protokollierung instrumentieren zu müssen.

Bestimmte Plugins beim Laden blockieren

Der neue editorConfig.plugins.disable-Parameter ermöglicht es Ihnen, bestimmte Plugins beim Initialisieren des Editors zu verhindern. Dies ist nützlich, wenn Sie den Editor in einer kontrollierten Umgebung einbetten und die Funktionalität auf das beschränken möchten, was für Ihre Benutzer relevant ist, ohne die Plugin-Dateien selbst ändern zu müssen. Dies ist eine sauberere, konfigurationsbasierte Methode zur Verwaltung der Plugin-Oberfläche.

Überprüfen Sie das vollständige Änderungsprotokoll der Docs API

ONLYOFFICE Plugins und Makros API 9.4

Neue Methoden zur Steuerung des Cursors

Zwei neue Methoden wurden zu window.Asc.plugin.executeMethod für die Document API hinzugefügt:

• MoveCursorToField: bewegt den Cursor zu einem bestimmten Formularfeld;
• MoveCursorOutsideField: bewegt den Cursor zu einer Position außerhalb des aktuellen Feldes.

Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);

Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);

Diese sind besonders nützlich für Plugins, die Benutzer durch das Ausfüllen von Formularen leiten oder die Navigation von Feld zu Feld in Dokumenten automatisieren. Anstatt auf Benutzerinteraktionen zu vertrauen, um durch die Felder voranzukommen, kann Ihr Plugin die Cursorplatzierung programmatisch steuern.

Verbesserte Steuerung von StartAction und EndAction

Die StartAction-Methode akzeptiert zwei neue Parameter: lockScroll und keepSelection. Die EndAction-Methode erhält scrollToTarget und cancel. Zusammen geben diese Plugins eine feinere Kontrolle über den Editor-Zustand während der Makroausführung. Sie können die Auswahl des Benutzers beibehalten, unerwünschtes Scrollen während automatisierter Vorgänge verhindern oder eine Aktionssequenz sauber abbrechen — all dies trägt zu einer stabileren und vorhersehbaren Plugin-Erfahrung bei.

Überprüfen Sie das vollständige Änderungsprotokoll der Plugins- und Makros-API

Office JavaScript API 9.4

Dies ist der umfassendste Teil der Version 9.4. Die Office JavaScript API erhält neue Funktionen für Dokumentoperationen, Tabellenkalkulationsdatenverwaltung, Formularsteuerelemente und mehr. Überprüfen Sie die vollständige Liste der neuen Methoden

Dokumentenzusammenführung

Eine neue Api/MergeDocuments-Methode wurde zur Document API hinzugefügt. Mit dieser können Sie mehrere Dokumente zu einem einzigen kombinieren – eine Funktion, die häufig bei Automatisierungsszenarien wie Berichtsgenerierung, Vertragserstellung und Batch-Dokumentenverarbeitung angefragt wurde.

Einheitliche Farb-API in allen Editoren

Die Api/Color-Methode ist in den Document-, Spreadsheet-, Presentation- und PDF-APIs verfügbar. Eine konsistente Farboberfläche in allen vier Editor-Typen vereinfacht den Code, der Stilungen über verschiedene Dokumentformate hinweg anwenden muss. Sie müssen keine format-spezifischen Farbhandhabungslogik für gängige Operationen mehr erstellen.

Unterstützung für Unterschriftenformulare

Version 9.4 führt die Klasse ApiSignatureForm ein, die sowohl in der Document API als auch in der Form API verfügbar ist. Damit kommen die Methoden GetValue und SetValue zum Lesen und Schreiben von Unterschriftsfeld-Daten. Dies eröffnet die programmatische Handhabung von Unterschriftsfeldern, die in Workflows nützlich sind, die Unterschriftsdaten als Teil eines größeren Dokumentverarbeitungsprozesses vorausfüllen, validieren oder extrahieren müssen.

// Die GetValue-Methode von ApiSignatureForm gibt die im Formular gespeicherten Unterschriftsbilddaten zurück.

// Erstellen Sie ein Unterschriftenformular, fügen Sie es dem Dokument hinzu und lesen Sie seinen aktuellen Wert.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Unterschrift", "tip": "Bitte hier unterschreiben", "required": true, "placeholder": "Unterschrift"});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("Wert des Unterschriftenformulars: " + value);
doc.Push(paragraph);

Zusätzlich ermöglicht die neue Api/CreateSignatureForm-Methode in der Form API das Erstellen von Unterschriftenformularfeldern von Grund auf durch Code, anstatt sich auf eine manuelle Eingabe zu verlassen.

Erkennung des Formularstatus

Die ApiFormBase/IsFilled-Methode, die sowohl in der Document API als auch in der Form API hinzugefügt wurde, ermöglicht es Ihnen zu überprüfen, ob ein bestimmtes Formularfeld ausgefüllt wurde. Diese einfache, aber wichtige Ergänzung ist für jede Validierungs- oder Einreichungslogik von Bedeutung. Überprüfen Sie den Status des Formulars, ohne den Inhalt der Felder direkt zu analysieren.

Inspektion der Formularhervorhebung

Zwei neue Methoden (ApiDocument/GetFormsHighlight und ApiDocument/GetControlsHighlight) sind in den Document- und Form-APIs verfügbar. Diese ermöglichen es Ihnen, die aktuellen Hervorhebungseinstellungen abzurufen, die auf Formularfelder und Inhaltssteuerelemente angewendet werden. Wenn Ihre Integration die Formularanzeigekonfiguration verwaltet oder die Hervorhebungszustände in externen UI-Elementen widerspiegeln muss, bieten diese Methoden den zuvor fehlenden Lesezugriff.

Umfassende Spreadsheet List Object API

Dies ist die funktionsreichste Ergänzung in 9.4. Die Spreadsheet API umfasst eine vollständige ApiListObject-Klasse zur Arbeit mit strukturierten Tabellenobjekten (Listenobjekten) sowie unterstützende Klassen für Spalten, Zeilen und Sortierung.

Wichtige Funktionen umfassen:

• Erstellen und Abrufen von Listenobjekten über ApiWorksheet/AddListObject und ApiWorksheet/GetListObjects
• Lesen und Schreiben von Tabelleneigenschaften wie Name, angezeigter Name, Alternativtext, Stil, Kopfzeilen, Summen und Auto-Filter-Einstellungen
• Zugriff auf Tabellenbereiche einschließlich Kopfzeilen, Datenkörperbereichen und Summenzeilen
• Verwalten von Spalten und Zeilen über ApiListColumn und ApiListRow, mit Methoden für Namen, Indizes, Bereiche, Summenberechnungen und Löschung
• Sortierungsunterstützung über die neuen Klassen ApiSort, ApiSortFields und ApiSortField — einschließlich Sortierorientierung, Groß-/Kleinschreibung, Sortierkriterien (Wert oder Farbe), Priorität und mehr

Wenn Ihre Integration irgendwelche strukturierten Datenverwaltungen in Tabellenkalkulationen wie Datenimporte, dynamische Tabellenerstellung oder Berichtsgenerierung umfasst. Diese Ergänzung erweitert erheblich, was Sie tun können, ohne die Benutzer dazu zu bringen, Tabellen manuell zu manipulieren.

Neue Methoden zum Ausfüllen und Berechnen in der Tabellenkalkulation

Vier richtungsorientierte Füllmethoden wurden zu ApiRange hinzugefügt: FillDown, FillUp, FillRight, FillLeft.

Diese spiegeln das Verhalten der Tabellenkalkulationsfüllung wider, das Benutzer manuell auslösen, nun jedoch für programmatische Nutzung verfügbar ist. In Kombination mit der neuen ApiRange/SetFormula-Methode können Sie Automatisierungen erstellen, die dynamisch formelgesteuerte Bereiche erstellen. Dies ist nützlich für generierte Berichte, Vorlagentabellenkalkulationen und Datenentry-Automatisierung.

Die Api/GetDefNames-Methode wurde ebenfalls zur Spreadsheet API hinzugefügt, wodurch Sie Zugriff auf die definierten Namen (benannte Bereiche) in einer Arbeitsmappe erhalten.

Textformataussteuerungen

Die ApiTextForm-Klasse erhält vier neue Methoden in den Document- und Form-APIs:

• GetFormat/SetFormat: ließt und wendet eine Formatmaske auf das Textfeld an
• GetAllowedSymbols/SetAllowedSymbols: steuert, welche Zeichen Benutzer eingeben können

Diese sind entscheidend für den Aufbau validierter Dateneingabeformulare, z.B. um Datumsformate durchzusetzen, Eingaben auf numerische Zeichen zu beschränken oder benutzerdefinierte Masken für Telefonnummern oder IDs anzuwenden.

Inspektion von Absatz-Eigenschaften

Eine Reihe von Get-Methoden wurde zu ApiParaPr in der Document API hinzugefügt, die Folgendes abdecken:

• Rahmeneigenschaften: oben, links, rechts, unten, zwischen
• Seitenumbrüche: GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl
• Liste: GetNumPr
• Registerkarten: GetTabs
• Abstand: GetContextualSpacing

Diese schließen eine lange bestehende Lücke. Viele dieser Eigenschaften konnten programmatisch gesetzt werden, aber sie als gelesen zurückzubekommen, war nicht immer möglich. Sie können die Absatzformatierung inspect ohne auf Umgehungslösungen zurückgreifen zu müssen, was besonders nützlich für Dokumentenanalysetools und Validierungsskripte ist.

Farbe von Inhaltssteuerelementen

Die ApiInlineLvlSdt-Klasse in der Document API unterstützt die Methoden SetColor und GetColor. Sie können Hervorhebungsfarben für Inline-Inhaltssteuerelemente zuweisen und lesen, was es einfacher macht, visuell unterscheidbare Formulare oder Hervorhebungen für Steuerelemente basierend auf ihrem Zustand zu erstellen.

// Wie kann ich die Farbe eines Inline-Inhaltssteuerelements in einem Dokument ändern?

// Wenden Sie eine spezifische RGB-Farbe an, um ein Inhaltssteuerelement in einem Dokument visuell zu unterscheiden.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("Dies ist ein Inline-Text-Inhaltssteuerelement mit einer blauen Tagfarbe.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);