Τι νέο υπάρχει στο ONLYOFFICE API 9.4: Οδηγός προγραμματιστή για τις τελευταίες ενημερώσεις

Η έκδοση 9.4 του ONLYOFFICE εισάγει σημαντικές βελτιώσεις API για ενσωματώσεις, προσαρμοσμένα πρόσθετα (plugins) και αυτοματοποίηση υπολογιστικών φύλλων. Αυτό το άρθρο αναδεικνύει τις βασικές ενημερώσεις στο ONLYOFFICE Docs API, στο Plugins and Macros API και στο Office JavaScript API, και εξηγεί τι σημαίνουν για τους προγραμματιστές.

ONLYOFFICE Docs API 9.4

Υποστήριξη Κροατικής γλώσσας

Τα Κροατικά (hr) προστέθηκαν στη λίστα των υποστηριζόμενων γλωσσών διεπαφής. Αν δημιουργείτε εντοπισμένες εφαρμογές για Κροάτες χρήστες, μπορείτε να την συμπεριλάβετε στη ρύθμιση γλώσσας χωρίς προσωρινές λύσεις.

Δεδομένα ρόλου και χρήστη στο συμβάν onStartFilling

Το συμβάν onStartFilling περιλαμβάνει πλέον μια παράμετρο roles που μεταφέρει πληροφορίες ρόλου και χρήστη. Αυτό διευκολύνει πολύ τη δημιουργία εμπειριών συμπλήρωσης φορμών που αναγνωρίζουν ρόλους, για παράδειγμα, δρομολόγηση χρηστών στα πεδία για τα οποία είναι υπεύθυνοι ή ενεργοποίηση λογικής υπό συνθήκη βάσει του ποιος συμπληρώνει τη φόρμα και με ποια ιδιότητα.

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

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

Διόρθωση διαρροής μνήμης στο destroyEditor

Μια διαρροή μνήμης στη μέθοδο destroyEditor έχει διορθωθεί. Προηγουμένως, η κλήση του destroyEditor δεν εκκαθάριζε πλήρως τους δεσμευμένους πόρους. Εάν η εφαρμογή σας δημιουργεί και καταστρέφει συχνά στιγμιότυπα επεξεργαστή, όπως σε ρυθμίσεις εφαρμογής μίας σελίδας (single-page application) ή ροές εργασίας προεπισκόπησης εγγράφων, αυτή η διόρθωση βελτιώνει άμεσα το αποτύπωμα μνήμης της ενσωμάτωσής σας με την πάροδο του χρόνου.

Καταργημένο πεδίο

Το απαρχαιωμένο πεδίο editorConfig.customization.commentAuthorOnly έχει αφαιρεθεί. Εάν η ενσωμάτωσή σας εξακολουθεί να αναφέρεται σε αυτήν την παράμετρο, είναι καιρός να την αφαιρέσετε για να αποφύγετε απρόσμενη συμπεριφορά.

Καταγραφή εντολών plugin για ευκολότερη αποσφαλμάτωση

Μία από τις πιο πρακτικές προσθήκες για προγραμματιστές plugins είναι η καταγραφή εντολών plugin. Ενεργοποιήστε την έξοδο αποσφαλμάτωσης των εντολών του plugin απευθείας στην κονσόλα του προγράμματος περιήγησης. Εάν έχετε ξοδέψει χρόνο αποσφαλματώνοντας τη συμπεριφορά ενός plugin μαντεύοντας ποιες εντολές εκτελούνται πραγματικά, αυτή η δυνατότητα αφαιρεί σημαντικό μέρος αυτής της τριβής. Σας δίνει άμεση ορατότητα στη ροή εκτέλεσης του plugin χωρίς να χρειάζεται να ενσωματώσετε τη δική σας καταγραφή.

Αποκλεισμός συγκεκριμένων plugins κατά τη φόρτωση

Η νέα παράμετρος editorConfig.plugins.disable σας επιτρέπει να αποτρέψετε τη φόρτωση συγκεκριμένων plugins κατά την αρχικοποίηση του επεξεργαστή. Αυτό είναι χρήσιμο όταν ενσωματώνετε τον επεξεργαστή σε ένα ελεγχόμενο περιβάλλον και θέλετε να περιορίσετε τη λειτουργικότητα σε ό,τι σχετίζεται με τους χρήστες σας, χωρίς να χρειάζεται να τροποποιήσετε τα ίδια τα αρχεία του plugin. Είναι μια καθαρότερη προσέγγιση σε επίπεδο ρυθμίσεων για τη διαχείριση της επιφάνειας των plugins.

Δείτε το πλήρες changelog για το Docs API

ONLYOFFICE Plugins and Macros API 9.4

Νέες μέθοδοι ελέγχου δρομέα

Δύο νέες μέθοδοι προστέθηκαν στο window.Asc.plugin.executeMethod για το Document API:

• MoveCursorToField: μετακινεί το δρομέα σε ένα συγκεκριμένο πεδίο φόρμας.
• MoveCursorOutsideField: μετακινεί το δρομέα σε θέση εκτός του τρέχοντος πεδίου.

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

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

Αυτές είναι ιδιαίτερα χρήσιμες για plugins που καθοδηγούν τους χρήστες μέσω της συμπλήρωσης φορμών ή αυτοματοποιούν την πλοήγηση πεδίο προς πεδίο σε έγγραφα. Αντί να βασίζεστε στην αλληλεπίδραση του χρήστη για να προχωρήσετε στα πεδία, το plugin σας μπορεί να ελέγχει την τοποθέτηση του δρομέα μέσω προγραμματισμού.

Βελτιωμένος έλεγχος StartAction και EndAction

Η μέθοδος StartAction δέχεται δύο νέες παραμέτρους: lockScroll και keepSelection. Η μέθοδος EndAction αποκτά τις scrollToTarget και cancel. Μαζί, αυτές δίνουν στα plugins λεπτότερο έλεγχο της κατάστασης του επεξεργαστή κατά την εκτέλεση μακροεντολών. Μπορείτε να διατηρήσετε την επιλογή του χρήστη, να αποτρέψετε ανεπιθύμητη κύλιση κατά τη διάρκεια αυτοματοποιημένων λειτουργιών ή να ακυρώσετε μια ακολουθία ενεργειών καθαρά — όλα συμβάλλουν σε μια πιο σταθερή και προβλέψιμη εμπειρία plugin.

Δείτε το πλήρες changelog για το Plugins and Macros API

Office JavaScript API 9.4

Αυτό είναι το πιο εκτεταμένο μέρος της έκδοσης 9.4. Το Office JavaScript API αποκτά νέες δυνατότητες σε λειτουργίες εγγράφων, διαχείριση δεδομένων υπολογιστικών φύλλων, στοιχεία ελέγχου φορμών και άλλα. Δείτε την πλήρη λίστα νέων μεθόδων

Συγχώνευση εγγράφων

Μια νέα μέθοδος Api/MergeDocuments προστέθηκε στο Document API. Αυτό σας επιτρέπει να συνδυάσετε πολλά έγγραφα σε ένα — μια δυνατότητα που ζητήθηκε συχνά για σενάρια αυτοματισμού, όπως η δημιουργία αναφορών, η συναρμολόγηση συμβολαίων και η μαζική επεξεργασία εγγράφων.

Ενοποιημένο Color API σε όλους τους επεξεργαστές

Η μέθοδος Api/Color είναι διαθέσιμη στα Document, Spreadsheet, Presentation και PDF APIs. Η ύπαρξη μιας συνεπούς διεπαφής χρώματος και στους τέσσερις τύπους επεξεργαστή απλοποιεί τον κώδικα που πρέπει να εφαρμόζει στυλ σε διαφορετικές μορφές εγγράφων. Δεν χρειάζεστε πλέον λογική χειρισμού χρωμάτων ειδική ανά μορφή για κοινές λειτουργίες.

Υποστήριξη φόρμας υπογραφής

Η έκδοση 9.4 εισάγει την κλάση ApiSignatureForm, διαθέσιμη τόσο στο Document API όσο και στο Form API. Μαζί της έρχονται οι μέθοδοι GetValue και SetValue για ανάγνωση και εγγραφή δεδομένων πεδίου υπογραφής. Αυτό ανοίγει τον προγραμματικό χειρισμό πεδίων υπογραφής, τα οποία είναι χρήσιμα για ροές εργασίας που χρειάζεται να προσυμπληρώνουν, να επικυρώνουν ή να εξάγουν δεδομένα υπογραφής ως μέρος μιας μεγαλύτερης σωλήνωσης επεξεργασίας εγγράφων.

// Η μέθοδος GetValue της ApiSignatureForm επιστρέφει τα δεδομένα εικόνας υπογραφής που είναι αποθηκευμένα στη φόρμα.

// Δημιουργήστε μια φόρμα υπογραφής, προσθέστε την στο έγγραφο και διαβάστε την τρέχουσα τιμή της.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "Please sign here", "required": true, "placeholder": "Signature"});
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("Signature form value: " + value);
doc.Push(paragraph);

Επιπλέον, η νέα μέθοδος Api/CreateSignatureForm στο Form API σας επιτρέπει να δημιουργείτε πεδία φόρμας υπογραφής από την αρχή μέσω κώδικα, αντί να βασίζεστε στη χειροκίνητη εισαγωγή.

Ανίχνευση κατάστασης φόρμας

Η μέθοδος ApiFormBase/IsFilled, που προστέθηκε τόσο στο Document API όσο και στο Form API, σας επιτρέπει να ελέγχετε εάν ένα συγκεκριμένο πεδίο φόρμας έχει συμπληρωθεί. Αυτή είναι μια απλή αλλά σημαντική προσθήκη για οποιαδήποτε λογική επικύρωσης ή υποβολής. Επιθεωρήστε την κατάσταση συμπλήρωσης της φόρμας χωρίς να αναλύετε απευθείας το περιεχόμενο του πεδίου.

Επιθεώρηση επισήμανσης φόρμας

Δύο νέες μέθοδοι (ApiDocument/GetFormsHighlight και ApiDocument/GetControlsHighlight) είναι διαθέσιμες στα Document και Form APIs. Αυτές σας επιτρέπουν να ανακτήσετε τις τρέχουσες ρυθμίσεις επισήμανσης που εφαρμόζονται σε πεδία φόρμας και στοιχεία ελέγχου περιεχομένου. Εάν η ενσωμάτωσή σας διαχειρίζεται τη διαμόρφωση εμφάνισης φόρμας ή χρειάζεται να αντικατοπτρίζει καταστάσεις επισήμανσης σε εξωτερικά στοιχεία διεπαφής χρήστη, αυτές οι μέθοδοι παρέχουν την πρόσβαση ανάγνωσης που έλειπε προηγουμένως.

Εκτεταμένο Spreadsheet List Object API

Αυτή είναι η πιο πλούσια σε δυνατότητες προσθήκη στο 9.4. Το Spreadsheet API περιλαμβάνει μια πλήρη κλάση ApiListObject για εργασία με δομημένα αντικείμενα πίνακα (list objects), μαζί με υποστηρικτικές κλάσεις για στήλες, γραμμές και ταξινόμηση.

Οι βασικές δυνατότητες περιλαμβάνουν:

• Δημιουργία και ανάκτηση αντικειμένων λίστας μέσω των ApiWorksheet/AddListObject και ApiWorksheet/GetListObjects.
• Ανάγνωση και εγγραφή ιδιοτήτων πίνακα, όπως όνομα, εμφανιζόμενο όνομα, εναλλακτικό κείμενο, στυλ, κεφαλίδες, σύνολα και ρυθμίσεις αυτόματου φιλτραρίσματος.
• Πρόσβαση σε περιοχές του πίνακα, συμπεριλαμβανομένων των γραμμών κεφαλίδας, του εύρους σώματος δεδομένων και των γραμμών συνόλων.
• Διαχείριση στηλών και γραμμών μέσω των ApiListColumn και ApiListRow, με μεθόδους για ονόματα, ευρετήρια, εύρη, υπολογισμό συνόλων και διαγραφή.
• Υποστήριξη ταξινόμησης μέσω των νέων κλάσεων ApiSort, ApiSortFields και ApiSortField — που καλύπτουν προσανατολισμό ταξινόμησης, διάκριση πεζών/κεφαλαίων, κριτήρια ταξινόμησης (τιμή ή χρώμα), προτεραιότητα και άλλα.

Αν η ενσωμάτωσή σας περιλαμβάνει οποιοδήποτε είδος διαχείρισης δομημένων δεδομένων σε υπολογιστικά φύλλα, όπως εισαγωγές δεδομένων, δυναμική δημιουργία πινάκων, δημιουργία αναφορών, αυτή η προσθήκη επεκτείνει σημαντικά το τι μπορείτε να κάνετε χωρίς να ζητάτε από τους χρήστες να χειρίζονται πίνακες χειροκίνητα.

Νέες μέθοδοι συμπλήρωσης (Fill) και τύπου (Formula) υπολογιστικού φύλλου

Τέσσερις κατευθυντικές μέθοδοι συμπλήρωσης προστέθηκαν στο ApiRange: FillDown, FillUp, FillRight, FillLeft.

Αυτές αντικατοπτρίζουν τη συμπεριφορά συμπλήρωσης υπολογιστικών φύλλων που οι χρήστες ενεργοποιούν χειροκίνητα, διαθέσιμη πλέον για προγραμματική χρήση. Σε συνδυασμό με τη νέα μέθοδο ApiRange/SetFormula, μπορείτε να δημιουργήσετε αυτοματισμούς που κατασκευάζουν δυναμικά εύρη βάσει τύπων. Είναι χρήσιμο για δημιουργούμενες αναφορές, υπολογιστικά φύλλα προτύπων και αυτοματισμό εισαγωγής δεδομένων.

Η μέθοδος Api/GetDefNames έχει επίσης προστεθεί στο Spreadsheet API, δίνοντάς σας πρόσβαση στα καθορισμένα ονόματα (ονόμαστες περιοχές) σε ένα βιβλίο εργασίας.

Στοιχεία ελέγχου μορφοποίησης φόρμας κειμένου

Η κλάση ApiTextForm αποκτά τέσσερις νέες μεθόδους τόσο στο Document όσο και στο Form API:

• GetFormat/SetFormat: ανάγνωση και εφαρμογή μάσκας μορφοποίησης στο πεδίο κειμένου.
• GetAllowedSymbols/SetAllowedSymbols: έλεγχος ποιους χαρακτήρες μπορούν να εισάγουν οι χρήστες.

Αυτές είναι απαραίτητες για τη δημιουργία επικυρωμένων φορμών εισαγωγής δεδομένων, για παράδειγμα, επιβολή μορφών ημερομηνίας, περιορισμός εισόδου σε αριθμητικούς χαρακτήρες ή εφαρμογή προσαρμοσμένων μασκών για αριθμούς τηλεφώνου ή ταυτότητες.

Επιθεώρηση ιδιοτήτων παραγράφου

Ένα σύνολο μεθόδων Get προστέθηκε στο ApiParaPr στο Document API, που καλύπτει:

• Ιδιότητες περιγράμματος: πάνω, αριστερά, δεξιά, κάτω, μεταξύ.
• Αρίθμηση σελίδων: GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl.
• Λίστες: GetNumPr.
• Στηλοθέτες: GetTabs.
• Διάστιχο: GetContextualSpacing.

Αυτές καλύπτουν ένα μακροχρόνιο κενό. Μπορούσατε να ορίσετε πολλές από αυτές τις ιδιότητες μέσω προγραμματισμού, αλλά η ανάγνωσή τους δεν ήταν πάντα δυνατή. Τώρα μπορείτε να επιθεωρήσετε τη μορφοποίηση παραγράφου χωρίς να βασίζεστε σε προσωρινές λύσεις, κάτι ιδιαίτερα χρήσιμο για εργαλεία ανάλυσης εγγράφων και σενάρια επικύρωσης προτύπων.

Χρώμα στοιχείου ελέγχου περιεχομένου

Η κλάση ApiInlineLvlSdt στο Document API υποστηρίζει μεθόδους SetColor και GetColor. Μπορείτε να εκχωρήσετε και να διαβάσετε χρώματα επισήμανσης για ενσωματωμένα στοιχεία ελέγχου περιεχομένου, καθιστώντας ευκολότερη τη δημιουργία οπτικά διακριτών εμπειριών φόρμας ή την επισήμανση στοιχείων ελέγχου βάσει της κατάστασής τους.

// Πώς μπορώ να αλλάξω το χρώμα ενός ενσωματωμένου στοιχείου ελέγχου περιεχομένου σε ένα έγγραφο;

// Εφαρμόστε ένα συγκεκριμένο χρώμα RGB για να ξεχωρίσει οπτικά ένα στοιχείο ελέγχου περιεχομένου σε ένα έγγραφο.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("This is an inline text content control with a blue tag color.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);