إتقان التعامل مع ONLYOFFICE APIs باستخدام Playground

٢٧ نوفمبر ٢٠٢٥بواسطة Moncif MEFTAH

قد يمثل اختبار واستكشاف ONLYOFFICE APIs تحدياً إذا كان عليكم إعداد إضافة (plugin) كاملة أو بيئة أتمتة لكل تجربة صغيرة. توفر وثائق ONLYOFFICE API Playground مساحة مخصصة حيث يمكن للمطورين التفاعل مع المستندات برمجياً، وتجربة الأوامر، وفهم سلوك واجهة برمجة التطبيقات (API) في الوقت الفعلي.

في هذا الدليل، سنوضح كيف يسرع Playground عملية التطوير، ونسلط الضوء على أمثلة عملية، ونقدم إرشادات لاختيار الـ API المناسب لاحتياجاتكم.

Mastering ONLYOFFICE APIs with Playground

\لماذا يُعد Playground مهماً

صُمم Playground للمطورين الذين يريدون:

  • تجرِبة APIs مختلفة في بيئة محرر حية.
  • إدراج ومعالجة النصوص أو محتوى HTML برمجياً.
  • مراقبة أحداث المستند والاستجابة لها.
  • اختبار الحالات الطرفية (edge cases)، أو المدخلات الكبيرة، أو الأحرف الخاصة دون الحاجة لإعداد بيئة إضافة أو موصل (connector) كاملة.

يساعدكم استخدام Playground قبل بناء إضافة أو سير عمل أتمتة على اكتشاف المشكلات المحتملة مبكراً، وفهم قيود الـ API، وتبسيط عملية التطوير الخاصة بكم.

فهم الـ APIs المتاحة

يدعم Playground ثلاث واجهات برمجة تطبيقات (APIs) رئيسية:

  1. Office JavaScript API – مخصص لبناء المستندات ومعالجتها بشكل مباشر، وهو الأفضل للسكربتات، وإنشاء المستندات، ومهام الأتمتة البسيطة.
  2. Plugin API – يُستخدم لبناء إضافات ONLYOFFICE التفاعلية. يدعم أنماط async/await لتنفيذ تعليمات برمجية نظيفة وعمليات معقدة.
  3. Automation API / Connector – يُستخدم للأنظمة الخارجية للوصول إلى المستندات وتعديلها، باستخدام الاستدعاءات الخلفية (callbacks) للتكامل والأتمتة.

تخدم كل واجهة غرضاً متميزاً، ويسمح لكم Playground باختبارها جنباً إلى جنب لمعرفة أي منها يناسب سير عملكم.

البدء مع مقتطفات Playground البرمجية

فيما يلي أمثلة عملية توضح كيفية استخدام كل API. انسخوا المقتطف البرمجي إلى محرر Playground لتشغيله فوراً.

إدراج نص بسيط (Basic text insertion)

الغرض: يوضح كيفية إدراج نص في موضع المؤشر الحالي باستخدام جميع واجهات برمجة التطبيقات الثلاث.

حالة الاستخدام: إدراج نص بسيط في المستندات أو اختبار سلوك الـ API.

//APPROACH 1: Using Automation API (Connector)

// Use this when working with connector for external document access

connector.executeMethod(
  "PasteText",
  ["Hello from ONLYOFFICE Automation API!"],
  function() {
    console.log("Text inserted using Automation API");
  }
);
//APPROACH 2: Using Plugin API with Editor helper

// Use this when developing plugins
(async function(){
  await Editor.callMethod("PasteText", ["Hello from ONLYOFFICE Plugin API!"]);
  console.log("Text inserted using Plugin API");
})();

//APPROACH 3: Using Office JavaScript API directly
// Use this for direct document building and manipulation
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText("Hello from ONLYOFFICE Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Text inserted using Office JavaScript API");

نصيحة للمطورين: تحققوا دائماً من استجابة الـ API في وحدة التحكم (console) فوراً بعد استدعاء الطريقة. حتى العمليات البسيطة مثل PasteText أو PasteHtml يمكن أن تتصرف بشكل مختلف اعتماداً على موضع المؤشر، أو التحديد، أو بنية HTML. يساعد تسجيل النتائج في اكتشاف السلوك غير المتوقع مبكراً.

محتوى HTML مع التنسيق

الغرض: يوضح كيفية إدراج محتوى HTML غني، بما في ذلك العناوين، والقوائم، والأنماط المخصصة.

حالة الاستخدام: استيراد محتوى منسق، أو لصق نص غني، أو إنشاء أقسام ديناميكياً.

// HTML string with various formatting elements
const htmlContent = `
  <h2 style="color: #2E86C1;">Welcome to ONLYOFFICE</h2>
  <p>This is a <strong>bold text</strong> and this is <em>italic text</em>.</p>
  <ul>
    <li>First bullet point</li>
    <li>Second bullet point with <u>underlined text</u></li>
    <li>Third bullet point</li>
  </ul>
  <p style="color: #28B463;">This paragraph has custom color styling.</p>
`;

// APPROACH 1: Using Automation API (Connector)

// The PasteHtml method automatically converts HTML to document elements

connector.executeMethod(
  "PasteHtml",
  [htmlContent],
  function() {
    console.log("HTML content inserted using Automation API");
  }
);
// APPROACH 2: Using Plugin API with Editor helper

(async function(){
  await Editor.callMethod("PasteHtml", [htmlContent]);
  console.log("HTML content inserted using Plugin API");
})();

مستمعو الأحداث لتغييرات المستند (Event listeners)

الغرض: يوضح مراقبة أحداث المستند مثل تغييرات التحديد أو تحديثات المحتوى.

حالة الاستخدام: بناء ميزات سريعة الاستجابة، أو تتبع إجراءات المستخدم، أو المزامنة مع الأنظمة الخارجية.

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

  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
  // Get the current word under cursor
  connector.executeMethod("GetCurrentWord", [], function(currentWord) {
    console.log("Current word:", currentWord);
  });

});

connector.attachEvent("onDocumentContentReady", function() {
  console.log("Document ready");
});
// APPROACH 2: Using Plugin API

// Event listeners work similarly with Asc.plugin.attachEvent()
Asc.plugin.attachEvent("onSelectionChanged", function(selectionInfo) {
  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
});
(async function(){

  let word = await Editor.callMethod("GetCurrentWord");
  console.log("Current word:", word);
})();

محتوى HTML كبير ومتداخل

الغرض: يختبر التعامل مع هياكل HTML المعقدة ذات العناصر المتداخلة والجداول.

حالة الاستخدام: إنشاء التقارير، أو ترحيل المستندات المنسقة، أو إنشاء تخطيطات متقدمة.

const complexHtml = `
  <h1 style="color: #2C3E50; text-align: center;">Comprehensive Document Report</h1>
  
  <h2 style="color: #E74C3C;">1. Executive Summary</h2>
  <p>This report demonstrates the ONLYOFFICE API's capability to handle 
  <em>complex HTML structures</em> with <u>multiple levels of nesting</u>.</p>
  
  <h2 style="color: #E74C3C;">2. Key Features</h2>
  <ul>
    <li>Rich Text Formatting: Bold, italic, underline, and colors</li>
    <li>Hierarchical Lists: Nested bullet points
      <ul>
        <li>Sub-item level 1</li>
        <li>Sub-item level 2
          <ul>
            <li>Sub-item level 3 (deeply nested)</li>
          </ul>
        </li>
      </ul>
    </li>
    <li>Tables and Structures: Complex layouts</li>
  </ul>
  
  <h2 style="color: #E74C3C;">3. Data Presentation</h2>
  <table border="1" cellpadding="10" style="width: 100%; border-collapse: collapse;">
    <thead>
      <tr style="background-color: #3498DB; color: white;">
        <th>Feature</th>
        <th>Description</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Text Insertion</td>
        <td>Insert plain and formatted text</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>HTML Import</td>
        <td>Convert HTML to document elements</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>Event Handling</td>
        <td>Monitor document changes</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
    </tbody>
  </table>
  
  <h2 style="color: #E74C3C;">4. Conclusion</h2>
  <p style=" padding: 15px;">
    The ONLYOFFICE API successfully handles 
    <span style="background-color: #F39C12; color: white; padding: 2px 5px;">
    complex HTML content</span> with multiple levels of nesting.
  </p>
`;
// APPROACH 1: Using Automation API (Connector)
connector.executeMethod(
  "PasteHtml",
  [complexHtml],
  function() {
    console.log("Complex HTML inserted (" + complexHtml.length + " characters)");
  }
);
// APPROACH 2: Using Plugin API with Editor helper

(async function(){
  await Editor.callMethod("PasteHtml", [complexHtml]);
  console.log("Complex HTML inserted using Plugin API");
})();

أول استدعاء بسيط لـ API مع الحالات الطرفية (Edge cases)

الغرض: تعريف المبتدئين باستخدام الـ API، والحالات الطرفية الشائعة، وأنماط معالجة الأخطاء.

حالة الاستخدام: تعلم أساسيات Office JavaScript API، و Plugin API، و Automation API.

// APPROACH 1: Office JavaScript API
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText(" Hello from Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Content created with Office JavaScript API");

// EDGE CASE 1: Handling empty or null text
var oParagraph2 = Api.CreateParagraph();
var textToInsert = ""; // Empty string
if (textToInsert && textToInsert.trim().length > 0) {
  oParagraph2.AddText(textToInsert);
} else {
  oParagraph2.AddText("(Empty text was provided)");
}
oDocument.InsertContent([oParagraph2]);

// EDGE CASE 2: Working with special characters and Unicode
var oParagraph3 = Api.CreateParagraph();
oParagraph3.AddText("Special chars: © ® ™ € £ ¥ • · « » — 'quotes' 中文 العربية");
oDocument.InsertContent([oParagraph3]);

// EDGE CASE 3: Creating content with mixed formatting
var oParagraph4 = Api.CreateParagraph();
var oRun1 = Api.CreateRun();
oRun1.AddText("This is bold ");
oRun1.SetBold(true);
oParagraph4.AddElement(oRun1);
var oRun2 = Api.CreateRun();
oRun2.AddText("and this is italic ");
oRun2.SetItalic(true);
oParagraph4.AddElement(oRun2);
var oRun3 = Api.CreateRun();
oRun3.AddText("and this is colored.");
oRun3.SetColor(220, 20, 60, false); // Crimson color
oParagraph4.AddElement(oRun3);
oDocument.InsertContent([oParagraph4]);
// EDGE CASE 4: Checking if document exists before operations
if (oDocument) {
  var oParagraph5 = Api.CreateParagraph();
  oParagraph5.AddText("Document validation: OK");
  oDocument.InsertContent([oParagraph5]);
  console.log("Document exists and is accessible");
} else {
  console.log("ERROR: Document not accessible");
}
// APPROACH 2: Plugin API with Editor Helper (For Plugin Development)
// Use async/await pattern with error handling
(async function(){
  try {
    // Get editor version
    let version = await Editor.callMethod("GetVersion");
    console.log("Editor version:", version);

    // EDGE CASE 1: Insert HTML with error handling
    await Editor.callMethod("PasteHtml", [
      "<p><b>Hello</b> from <i>Plugin API</i>!</p>"
    ]);
    console.log("Content inserted with Plugin API");
   
    // EDGE CASE 2: Check if method returns undefined or null
    let selectedText = await Editor.callMethod("GetSelectedText");
    if (selectedText) {
      console.log("Selected text:", selectedText);
    } else {
      console.log("No text selected or selection is empty");
    }
    // EDGE CASE 3: Handling special characters in Plugin API
    await Editor.callMethod("PasteText", [
      "Special: © 2024 | €100 | 中文"
    ]);

    // EDGE CASE 4: Multiple async operations in sequence
    await Editor.callMethod("PasteText", ["Line 1 "]);
    await Editor.callMethod("PasteText", ["Line 2 "]);
    await Editor.callMethod("PasteText", ["Line 3"]);
    console.log("Multiple operations completed");
  } catch (error) {
    console.log("ERROR in Plugin API:", error.message || error);
  }
})();

نصيحة للمطورين: عند استخدام Plugin API مع async/await، قوموا بتغليف استدعاءاتكم في كتل try/catch. يضمن هذا عدم توقف السكربت الخاص بكم بسبب أخطاء مثل التحديدات غير المعرفة أو المحتوى غير المدعوم، ويسمح لكم بتقديم رسائل مفيدة في وحدة التحكم لتصحيح الأخطاء.

// APPROACH 3: Automation API (Connector - For External Access)

// Uses callbacks with error handling

// EDGE CASE 1: Check if connector exists before using

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

  // Basic text insertion with callback error handling
  connector.executeMethod(
    "PasteText",
    ["Hello from Automation API!"],
    function(result) {
      if (result !== undefined) {
        console.log("Content inserted with Automation API");
      } else {
        console.log("Insert may have failed, result is undefined");
      }

      // EDGE CASE 2: Chain multiple operations with error checking
      connector.executeMethod("GetCurrentWord", [], function(word) {
        if (word && word.length > 0) {
          console.log("Current word:", word);
        } else {
          console.log("No word at cursor position");
        }
      });
    }
  );

  // EDGE CASE 3: Handling empty or invalid HTML

  var htmlToInsert = "<p>Test</p>";
  if (htmlToInsert && htmlToInsert.includes("<")) {
    connector.executeMethod(
      "PasteHtml",
      [htmlToInsert],
      function() {
        console.log("HTML inserted successfully");
      }
    );
  } else {
    console.log("Invalid HTML content");
  }

  // EDGE CASE 4: Timeout handling for slow operations

  var operationTimeout = setTimeout(function() {

    console.log("WARNING: Operation taking longer than expected");

  }, 5000);
  connector.executeMethod(
    "PasteText",
    ["Async operation test"],
    function() {
      clearTimeout(operationTimeout);

      console.log("Operation completed in time");
    }
  );

} else {
  console.log("ERROR: Connector is not available");
}

تعليمات الاستخدام وأفضل الممارسات

  • قوموا بتشغيل المقتطفات بشكل فردي لتجنب التعارضات.
  • استخدموا وحدة تحكم المتصفح (browser console) لعرض سجلات التنفيذ وتصحيح النتائج.
  • اختاروا الـ API المناسب:

بناء المستندات من الصفر ← Office JavaScript API.

تطوير إضافات (plugins) ← Plugin API.

التكامل مع التطبيقات الخارجية ← Automation API (Connector).

  • جربوا التنسيق، و HTML، والأحداث لفهم سلوك الـ API بشكل شامل.

مسار التعلم الموصى به

  1. ابدأوا بـ أول استدعاء بسيط لـ API لمقارنة الأساليب.
  2. انتقلوا إلى إدراج نص بسيط لفهم الاختلافات بين الـ APIs.
  3. اختبروا إدراج HTML للتنسيق والمحتوى الغني.
  4. استكشفوا مستمعي الأحداث لـ Automation API و Plugin API.
  5. تقدموا إلى محتوى HTML المعقد للتعامل مع الهياكل الكبيرة والمتداخلة.

الخاتمة

تُعد ONLYOFFICE Playground أداة قوية لتسريع تعلم الـ API، والاختبار، وتطوير الإضافات. من خلال توفير بيئة تفاعلية ومعزولة (sandboxed)، فإنها تسمح للمطورين بالتجربة بأمان، وفهم سلوك الـ API بعمق، وبناء إضافات قوية وسير عمل أتمتة بكفاءة أكبر.

روابط مفيدة

البدء مع Playground

كيفية إنشاء الإضافة الخاصة بكم

ONLYOFFICE على GitHub

المساهمة في ONLYOFFICE

ONLYOFFICE ١. أنشئ حسابك المجاني من

،٢. قم بعرض و تحرير أو التعاون على المستندات، الجداول ، العروض التقديمية