Πλήρης κυριαρχία των ONLYOFFICE APIs με το Playground

2 Δεκεμβρίου 2025Από τον Efstathios Iosifidis

Η δοκιμή και εξερεύνηση των ONLYOFFICE APIs μπορεί να είναι δύσκολη αν χρειαστεί να ρυθμίσετε ένα πλήρες περιβάλλον plugin ή αυτοματισμού για κάθε μικρό πείραμα. Το ONLYOFFICE docs API Playground παρέχει έναν αποκλειστικό χώρο όπου οι προγραμματιστές μπορούν να αλληλεπιδρούν με έγγραφα μέσω προγραμματισμού, να δοκιμάζουν εντολές και να κατανοούν τη συμπεριφορά του API σε πραγματικό χρόνο.

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

Mastering ONLYOFFICE APIs with Playground

Γιατί το Playground είναι σημαντικό

Το Playground σχεδιάστηκε για προγραμματιστές που θέλουν να:

  • Πειραματιστούν με διαφορετικά APIs σε ένα περιβάλλον ζωντανού επεξεργαστή.
  • Εισάγουν και χειρίζονται κείμενο ή περιεχόμενο HTML μέσω προγραμματισμού.
  • Παρακολουθούν και ανταποκρίνονται σε συμβάντα εγγράφων.
  • Δοκιμάζουν οριακές περιπτώσεις, μεγάλες εισόδους ή ειδικούς χαρακτήρες χωρίς να ρυθμίσουν ένα πλήρες περιβάλλον plugin ή σύνδεσης.

Η χρήση του Playground πριν από την κατασκευή ενός plugin ή μιας ροής εργασιών αυτοματισμού σας βοηθά να εντοπίσετε πιθανά ζητήματα νωρίς, να κατανοήσετε τους περιορισμούς του API και να απλοποιήσετε τη διαδικασία ανάπτυξής σας.

Κατανόηση των διαθέσιμων APIs

Το Playground υποστηρίζει τρία κύρια APIs:

  1. Office JavaScript API – Άμεση δημιουργία και χειρισμός εγγράφων, καλύτερο για scripts, δημιουργία εγγράφων και απλές εργασίες αυτοματισμού.
  2. Plugin API – Χρησιμοποιείται για τη δημιουργία διαδραστικών ONLYOFFICE plugins. Υποστηρίζει μοτίβα async/await για καθαρή εκτέλεση κώδικα και σύνθετες λειτουργίες.
  3. Automation API / Connector – Χρησιμοποιείται από εξωτερικά συστήματα για πρόσβαση και τροποποίηση εγγράφων, χρησιμοποιώντας callbacks για ενσωμάτωση και αυτοματισμό.

Κάθε API εξυπηρετεί διακριτούς σκοπούς και το Playground σας επιτρέπει να τα δοκιμάσετε παράλληλα για να δείτε ποιό ταιριάζει στη ροή εργασίας σας.

Ξεκινώντας με αποσπάσματα (snippets) στο Playground

Παρακάτω υπάρχουν πρακτικά παραδείγματα που δείχνουν πώς να χρησιμοποιήσετε κάθε API. Αντιγράψτε ένα απόσπασμα στον επεξεργαστή Playground για να το εκτελέσετε αμέσως.

Βασική εισαγωγή κειμένου

Σκοπός: Δείχνει την εισαγωγή κειμένου στην τρέχουσα θέση του δρομέα χρησιμοποιώντας και τα τρία APIs.

Περίπτωση χρήσης: Απλή εισαγωγή κειμένου σε έγγραφα ή δοκιμή συμπεριφοράς API.

//ΠΡΟΣΕΓΓΙΣΗ 1: Χρήση Automation API (Connector)

// Χρησιμοποιήστε αυτό όταν εργάζεστε με connector για εξωτερική πρόσβαση σε έγγραφα

connector.executeMethod(
  "PasteText",
  ["Γεια σας από το ONLYOFFICE Automation API!"],
  function() {
    console.log("Το κείμενο εισήχθη χρησιμοποιώντας το Automation API");
  }
);
//ΠΡΟΣΕΓΓΙΣΗ 2: Χρήση Plugin API με βοηθό Editor

// Χρησιμοποιήστε αυτό όταν αναπτύσσετε plugins
(async function(){
  await Editor.callMethod("PasteText", ["Γεια σας από το ONLYOFFICE Plugin API!"]);
  console.log("Το κείμενο εισήχθη χρησιμοποιώντας το Plugin API");
})();

//ΠΡΟΣΕΓΓΙΣΗ 3: Άμεση χρήση Office JavaScript API
// Χρησιμοποιήστε αυτό για άμεση δημιουργία και χειρισμό εγγράφων
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText("Γεια σας από το ONLYOFFICE Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Το κείμενο εισήχθη χρησιμοποιώντας το Office JavaScript API");

Συμβουλή προγραμματιστή: Πάντα ελέγξτε την απόκριση του API στην κονσόλα αμέσως μετά την κλήση μιας μεθόδου. Ακόμα και απλές λειτουργίες όπως οι PasteText ή PasteHtml μπορούν να συμπεριφέρονται διαφορετικά ανάλογα με τη θέση του δρομέα, την επιλογή ή τη δομή HTML. Η καταγραφή των αποτελεσμάτων βοηθά στον έγκαιρο εντοπισμό απροσδόκητης συμπεριφοράς.

Περιεχόμενο HTML με μορφοποίηση

Σκοπός: Δείχνει πώς να εισάγετε πλούσιο περιεχόμενο HTML, συμπεριλαμβανομένων επικεφαλίδων, λιστών και προσαρμοσμένων στυλ.

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

// Συμβολοσειρά HTML με διάφορα στοιχεία μορφοποίησης
const htmlContent = `
  <h2 style="color: #2E86C1;">Καλώς ήρθατε στο ONLYOFFICE</h2>
  <p>Αυτό είναι ένα <strong>έντονο κείμενο</strong> και αυτό είναι <em>πλάγιο κείμενο</em>.</p>
  <ul>
    <li>Πρώτο σημείο λίστας</li>
    <li>Δεύτερο σημείο λίστας με <u>υπογραμμισμένο κείμενο</u></li>
    <li>Τρίτο σημείο λίστας</li>
  </ul>
  <p style="color: #28B463;">Αυτή η παράγραφος έχει προσαρμοσμένο χρωματικό στυλ.</p>
`;

// ΠΡΟΣΕΓΓΙΣΗ 1: Χρήση Automation API (Connector)

// Η μέθοδος PasteHtml μετατρέπει αυτόματα το HTML σε στοιχεία εγγράφου

connector.executeMethod(
  "PasteHtml",
  [htmlContent],
  function() {
    console.log("Το περιεχόμενο HTML εισήχθη χρησιμοποιώντας το Automation API");
  }
);
// ΠΡΟΣΕΓΓΙΣΗ 2: Χρήση Plugin API με βοηθό Editor

(async function(){
  await Editor.callMethod("PasteHtml", [htmlContent]);
  console.log("Το περιεχόμενο HTML εισήχθη χρησιμοποιώντας το Plugin API");
})();

Ακροατές συμβάντων για αλλαγές εγγράφων

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

Περίπτωση χρήσης: Δημιουργία ανταποκρινόμενων λειτουργιών, παρακολούθηση ενεργειών χρήστη ή συγχρονισμός με εξωτερικά συστήματα.

connector.attachEvent("onSelectionChanged", function(selectionInfo) {

  console.log("Η επιλογή άλλαξε:", JSON.stringify(selectionInfo, null, 2));
  // Λήψη της τρέχουσας λέξης κάτω από τον δρομέα
  connector.executeMethod("GetCurrentWord", [], function(currentWord) {
    console.log("Τρέχουσα λέξη:", currentWord);
  });

});

connector.attachEvent("onDocumentContentReady", function() {
  console.log("Το έγγραφο είναι έτοιμο");
});
// ΠΡΟΣΕΓΓΙΣΗ 2: Χρήση Plugin API

// Οι ακροατές συμβάντων λειτουργούν παρόμοια με την Asc.plugin.attachEvent()
Asc.plugin.attachEvent("onSelectionChanged", function(selectionInfo) {
  console.log("Η επιλογή άλλαξε:", JSON.stringify(selectionInfo, null, 2));
});
(async function(){

  let word = await Editor.callMethod("GetCurrentWord");
  console.log("Τρέχουσα λέξη:", word);
})();

Μεγάλο και ένθετο περιεχόμενο HTML

Σκοπός: Δοκιμή χειρισμού σύνθετων δομών HTML με ένθετα στοιχεία και πίνακες.

Περίπτωση χρήσης: Δημιουργία αναφορών, μετεγκατάσταση μορφοποιημένων εγγράφων ή δημιουργία προηγμένων διατάξεων.

const complexHtml = `
  <h1 style="color: #2C3E50; text-align: center;">Λεπτομερής Αναφορά Εγγράφου</h1>
  
  <h2 style="color: #E74C3C;">1. Εκτελεστική Περίληψη</h2>
  <p>Αυτή η αναφορά επιδεικνύει την ικανότητα του ONLYOFFICE API να χειρίζεται
  <em>σύνθετες δομές HTML</em> με <u>πολλαπλά επίπεδα ένθεσης</u>.</p>
  
  <h2 style="color: #E74C3C;">2. Βασικά Χαρακτηριστικά</h2>
  <ul>
    <li>Πλούσια Μορφοποίηση Κειμένου: Έντονο, πλάγιο, υπογράμμιση και χρώματα</li>
    <li>Ιεραρχικές Λίστες: Ένθετα σημεία λίστας
      <ul>
        <li>Υπο-στοιχείο επίπεδο 1</li>
        <li>Υπο-στοιχείο επίπεδο 2
          <ul>
            <li>Υπο-στοιχείο επίπεδο 3 (βαθιά ένθετο)</li>
          </ul>
        </li>
      </ul>
    </li>
    <li>Πίνακες και Δομές: Σύνθετες διατάξεις</li>
  </ul>
  
  <h2 style="color: #E74C3C;">3. Παρουσίαση Δεδομένων</h2>
  <table border="1" cellpadding="10" style="width: 100%; border-collapse: collapse;">
    <thead>
      <tr style="background-color: #3498DB; color: white;">
        <th>Χαρακτηριστικό</th>
        <th>Περιγραφή</th>
        <th>Κατάσταση</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Εισαγωγή Κειμένου</td>
        <td>Εισαγωγή απλού και μορφοποιημένου κειμένου</td>
        <td style="color: #27AE60;">✓ Υποστηρίζεται</td>
      </tr>
      <tr>
        <td>Εισαγωγή HTML</td>
        <td>Μετατροπή HTML σε στοιχεία εγγράφου</td>
        <td style="color: #27AE60;">✓ Υποστηρίζεται</td>
      </tr>
      <tr>
        <td>Χειρισμός Συμβάντων</td>
        <td>Παρακολούθηση αλλαγών εγγράφου</td>
        <td style="color: #27AE60;">✓ Υποστηρίζεται</td>
      </tr>
    </tbody>
  </table>
  
  <h2 style="color: #E74C3C;">4. Συμπέρασμα</h2>
  <p style=" padding: 15px;">
    Το ONLYOFFICE API χειρίζεται με επιτυχία
    <span style="background-color: #F39C12; color: white; padding: 2px 5px;">
    σύνθετο περιεχόμενο HTML</span> με πολλαπλά επίπεδα ένθεσης.
  </p>
`;
// ΠΡΟΣΕΓΓΙΣΗ 1: Χρήση Automation API (Connector)
connector.executeMethod(
  "PasteHtml",
  [complexHtml],
  function() {
    console.log("Το σύνθετο HTML εισήχθη (" + complexHtml.length + " χαρακτήρες)");
  }
);
// ΠΡΟΣΕΓΓΙΣΗ 2: Χρήση Plugin API με βοηθό Editor

(async function(){
  await Editor.callMethod("PasteHtml", [complexHtml]);
  console.log("Το σύνθετο HTML εισήχθη χρησιμοποιώντας το Plugin API");
})();

Απλή πρώτη κλήση API με οριακές περιπτώσεις

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

Περίπτωση χρήσης: Μάθετε τα βασικά του Office JavaScript API, Plugin API και Automation API.

// ΠΡΟΣΕΓΓΙΣΗ 1: Office JavaScript API
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText(" Γεια σας από το Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Το περιεχόμενο δημιουργήθηκε με το Office JavaScript API");

// ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 1: Χειρισμός κενού ή μηδενικού κειμένου
var oParagraph2 = Api.CreateParagraph();
var textToInsert = ""; // Κενή συμβολοσειρά
if (textToInsert && textToInsert.trim().length > 0) {
  oParagraph2.AddText(textToInsert);
} else {
  oParagraph2.AddText("(Παρεχόταν κενό κείμενο)");
}
oDocument.InsertContent([oParagraph2]);

// ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 2: Εργασία με ειδικούς χαρακτήρες και Unicode
var oParagraph3 = Api.CreateParagraph();
oParagraph3.AddText("Ειδικοί χαρακτήρες: © ® ™ € £ ¥ • · « » — 'εισαγωγικά' 中文 العربية");
oDocument.InsertContent([oParagraph3]);

// ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 3: Δημιουργία περιεχομένου με μικτή μορφοποίηση
var oParagraph4 = Api.CreateParagraph();
var oRun1 = Api.CreateRun();
oRun1.AddText("Αυτό είναι έντονο ");
oRun1.SetBold(true);
oParagraph4.AddElement(oRun1);
var oRun2 = Api.CreateRun();
oRun2.AddText("και αυτό είναι πλάγιο ");
oRun2.SetItalic(true);
oParagraph4.AddElement(oRun2);
var oRun3 = Api.CreateRun();
oRun3.AddText("και αυτό είναι χρωματισμένο.");
oRun3.SetColor(220, 20, 60, false); // Χρώμα Crimson
oParagraph4.AddElement(oRun3);
oDocument.InsertContent([oParagraph4]);
// ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 4: Έλεγχος ύπαρξης εγγράφου πριν από λειτουργίες
if (oDocument) {
  var oParagraph5 = Api.CreateParagraph();
  oParagraph5.AddText("Επικύρωση εγγράφου: OK");
  oDocument.InsertContent([oParagraph5]);
  console.log("Το έγγραφο υπάρχει και είναι προσβάσιμο");
} else {
  console.log("ΣΦΑΛΜΑ: Το έγγραφο δεν είναι προσβάσιμο");
}
// ΠΡΟΣΕΓΓΙΣΗ 2: Plugin API με Βοηθό Editor (Για Ανάπτυξη Plugin)
// Χρησιμοποιήστε το μοτίβο async/await με χειρισμό σφαλμάτων
(async function(){
  try {
    // Λήψη έκδοσης επεξεργαστή
    let version = await Editor.callMethod("GetVersion");
    console.log("Έκδοση επεξεργαστή:", version);

    // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 1: Εισαγωγή HTML με χειρισμό σφαλμάτων
    await Editor.callMethod("PasteHtml", [
      "<p><b>Γεια σας</b> από το <i>Plugin API</i>!</p>"
    ]);
    console.log("Το περιεχόμενο εισήχθη με το Plugin API");
   
    // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 2: Έλεγχος αν η μέθοδος επιστρέφει undefined ή null
    let selectedText = await Editor.callMethod("GetSelectedText");
    if (selectedText) {
      console.log("Επιλεγμένο κείμενο:", selectedText);
    } else {
      console.log("Δεν έχει επιλεγεί κείμενο ή η επιλογή είναι κενή");
    }
    // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 3: Χειρισμός ειδικών χαρακτήρων στο Plugin API
    await Editor.callMethod("PasteText", [
      "Ειδικοί χαρακτήρες: © 2024 | €100 | 中文"
    ]);

    // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 4: Πολλαπλές ασύγχρονες λειτουργίες σε σειρά
    await Editor.callMethod("PasteText", ["Γραμμή 1 "]);
    await Editor.callMethod("PasteText", ["Γραμμή 2 "]);
    await Editor.callMethod("PasteText", ["Γραμμή 3"]);
    console.log("Οι πολλαπλές λειτουργίες ολοκληρώθηκαν");
  } catch (error) {
    console.log("ΣΦΑΛΜΑ στο Plugin API:", error.message || error);
  }
})();

Συμβουλή προγραμματιστή: Όταν χρησιμοποιείτε το Plugin API με async/await, τυλίξτε τις κλήσεις σας σε μπλοκ try/catch. Αυτό διασφαλίζει ότι σφάλματα όπως απροσδιόριστες επιλογές ή μη υποστηριζόμενο περιεχόμενο δεν θα σπάσουν το script σας και σας επιτρέπει να παρέχετε ενημερωτικά μηνύματα κονσόλας για τον εντοπισμό σφαλμάτων.

// ΠΡΟΣΕΓΓΙΣΗ 3: Automation API (Connector - Για Εξωτερική Πρόσβαση)

// Χρησιμοποιεί callbacks με χειρισμό σφαλμάτων

// ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 1: Έλεγχος ύπαρξης connector πριν τη χρήση

if (typeof connector !== 'undefined' && connector) {

  // Βασική εισαγωγή κειμένου με χειρισμό σφάλματος callback
  connector.executeMethod(
    "PasteText",
    ["Γεια σας από το Automation API!"],
    function(result) {
      if (result !== undefined) {
        console.log("Το περιεχόμενο εισήχθη με το Automation API");
      } else {
        console.log("Η εισαγωγή μπορεί να απέτυχε, το αποτέλεσμα είναι απροσδιόριστο");
      }

      // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 2: Αλυσίδα πολλαπλών λειτουργιών με έλεγχο σφαλμάτων
      connector.executeMethod("GetCurrentWord", [], function(word) {
        if (word && word.length > 0) {
          console.log("Τρέχουσα λέξη:", word);
        } else {
          console.log("Δεν υπάρχει λέξη στη θέση του δρομέα");
        }
      });
    }
  );

  // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 3: Χειρισμός κενού ή μη έγκυρου HTML

  var htmlToInsert = "<p>Δοκιμή</p>";
  if (htmlToInsert && htmlToInsert.includes("<")) {
    connector.executeMethod(
      "PasteHtml",
      [htmlToInsert],
      function() {
        console.log("Το HTML εισήχθη με επιτυχία");
      }
    );
  } else {
    console.log("Μη έγκυρο περιεχόμενο HTML");
  }

  // ΟΡΙΑΚΗ ΠΕΡΙΠΤΩΣΗ 4: Χειρισμός χρονικού ορίου για αργές λειτουργίες

  var operationTimeout = setTimeout(function() {

    console.log("ΠΡΟΕΙΔΟΠΟΙΗΣΗ: Η λειτουργία διαρκεί περισσότερο από το αναμενόμενο");

  }, 5000);
  connector.executeMethod(
    "PasteText",
    ["Δοκιμή ασύγχρονης λειτουργίας"],
    function() {
      clearTimeout(operationTimeout);

      console.log("Η λειτουργία ολοκληρώθηκε εγκαίρως");
    }
  );

} else {
  console.log("ΣΦΑΛΜΑ: Ο connector δεν είναι διαθέσιμος");
}

Οδηγίες χρήσης και βέλτιστες πρακτικές

  • Εκτελέστε αποσπάσματα μεμονωμένα για να αποφύγετε συγκρούσεις.
  • Χρησιμοποιήστε την κονσόλα του προγράμματος περιήγησης για να δείτε τα αρχεία καταγραφής εκτέλεσης και να διορθώσετε αποτελέσματα.
  • Επιλέξτε το σωστό API:

Δημιουργία εγγράφων από το μηδέν → Office JavaScript API,

Ανάπτυξη plugins → Plugin API,

Ενσωμάτωση με εξωτερικές εφαρμογές → Automation API (Connector).

  • Πειραματιστείτε με μορφοποίηση, HTML και συμβάντα για να κατανοήσετε διεξοδικά τη συμπεριφορά του API.

Προτεινόμενη διαδρομή μάθησης

  1. Ξεκινήστε με την απλή πρώτη κλήση API για να συγκρίνετε προσεγγίσεις.
  2. Προχωρήστε στην βασική εισαγωγή κειμένου για να κατανοήσετε τις διαφορές μεταξύ των APIs.
  3. Δοκιμάστε την εισαγωγή html για μορφοποίηση και πλούσιο περιεχόμενο.
  4. Εξερευνήστε τους ακροατές συμβάντων για τα Automation και Plugin APIs.
  5. Προχωρήστε στο σύνθετο περιεχόμενο html για τη διαχείριση μεγάλων, ένθετων δομών.

Συμπέρασμα

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

Χρήσιμοι σύνδεσμοι

Ξεκινήστε με το Playground

Πώς να δημιουργήσετε το δικό σας plugin

Το ONLYOFFICE στο GitHub

Συμβάλλετε στο ONLYOFFICE

#API
#Playground

Δημιουργήστε τον δωρεάν λογαριασμό ONLYOFFICE σας

Online προβολή, επεξεργασία και συνεργασία σε έγγραφα, υπολογιστικά φύλλα, παρουσιάσεις, φόρμες και αρχεία PDF.