ما الجديد في ONLYOFFICE API 9.4: دليل المطور لآخر التحديثات

يقدم الإصدار 9.4 من ONLYOFFICE تحسينات رئيسية في واجهة برمجة التطبيقات (API) لعمليات التكامل، والإضافات المخصصة، وأتمتة جداول البيانات. يسلط هذا المقال الضوء على التحديثات الرئيسية في كل من ONLYOFFICE Docs API، وPlugins و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 ينظف الموارد المخصصة بالكامل. إذا كان تطبيقكم ينشئ ويدمر مثيلات المحرر بشكل متكرر، كما هو الحال في إعدادات تطبيقات الصفحة الواحدة أو سير عمل معاينة المستندات، فإن هذا الإصلاح يحسن بشكل مباشر البصمة الذاكرية لتكاملكم بمرور الوقت.

حقل محذوف

تم إزالة حقل editorConfig.customization.commentAuthorOnly المهمل. إذا كان تكاملكم لا يزال يشير إلى هذا المعامل، فقد حان الوقت الآن لإزالته لتجنب أي سلوك غير متوقع.

تسجيل أوامر الإضافات لتصحيح الأخطاء بشكل أسهل

إن أحد أكثر الإضافات عملية لمطوري الإضافات هو تسجيل أوامر الإضافات. يمكنكم تمكين مخرجات تصحيح الأخطاء لأوامر الإضافات مباشرة في وحدة تحكم المتصفح. إذا كنتم قد قضيتم وقتاً في تصحيح أخطاء سلوك الإضافات عن طريق تخمين الأوامر التي يتم تشغيلها بالفعل، فإن هذه الميزة تزيل قدراً كبيراً من هذا الاحتكاك. فهي تمنحكم رؤية مباشرة لتدفق تنفيذ الإضافة دون الحاجة إلى إعداد أدوات التسجيل الخاصة بكم.

حظر إضافات معينة عند التحميل

يتيح لكم معامل editorConfig.plugins.disable الجديد منع تحميل إضافات معينة عند بدء تشغيل المحرر. هذا مفيد عندما تقومون بتضمين المحرر في بيئة خاضعة للتحكم وتريدون قصر الوظائف على ما هو وثيق الصلة بمستخدميكم، دون الحاجة إلى تعديل ملفات الإضافات نفسها. إنه نهج أنظف على مستوى التكوين لإدارة واجهة الإضافات.

راجعوا سجل التغييرات الكامل لـ 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]);

هذه التوابع مفيدة بشكل خاص للإضافات التي توجه المستخدمين خلال إكمال النماذج أو تدمج التنقل التلقائي حقلاً بحقل في المستندات. وبدلاً من الاعتماد على تفاعل المستخدم للانتقال عبر الحقول، يمكن للإضافة الخاصة بكم التحكم في وضع المؤشر برمجياً.

تحسين التحكم في StartAction و EndAction

يقبل التابع StartAction معاملين جديدين: lockScroll و keepSelection. ويكتسب التابع EndAction المعاملين scrollToTarget و cancel. تمنح هذه المعاملات معاً الإضافات تحكماً أدق في حالة المحرر أثناء تنفيذ الماكرو. يمكنكم الحفاظ على تحديد المستخدم، أو منع التمرير غير المرغوب فيه أثناء العمليات التلقائية، أو إلغاء تسلسل الإجراءات بشكل نظيف — وكل هذا يساهم في تقديم تجربة إضافات أكثر استقراراً وقابلية للتنبؤ.

راجعوا سجل التغييرات الكامل لـ 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. إن وجود واجهة ألوان متسقة عبر جميع أنواع المحررات الأربعة يبسط البرمجة التي تحتاج إلى تطبيق التنسيق عبر تنسيقات مستندات مختلفة. لم تعودوا بحاجة إلى منطق معالجة ألوان خاص بكل تنسيق للعمليات الشائعة.

دعم نموذج التوقيع

يقدم الإصدار 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. يتيح لكم هذان التابعان استرداد إعدادات التمييز الحالية المطبقة على حقول النموذج وعناصر التحكم في المحتوى. إذا كان تكاملكم يدير تكوين عرض النموذج أو يحتاج إلى عكس حالات التمييز في عناصر واجهة المستخدم الخارجية، فإن هذه التوابع توفر صلاحية القراءة التي كانت مفقودة سابقاً.

واجهة برمجة تطبيقات لـ Spreadsheet List Object موسعة

هذه هي الإضافة الأكثر كثافة بالميزات في الإصدار 9.4. تتضمن Spreadsheet API فئة ApiListObject كاملة للعمل مع عناصر الجداول المنظمة (عناصر القائمة)، إلى جانب فئات داعمة للأعمدة والصفوف والفرز.

تشمل القدرات الرئيسية ما يلي:

• إنشاء واسترداد عناصر القائمة عبر ApiWorksheet/AddListObject و ApiWorksheet/GetListObjects
• قراءة وكتابة خصائص الجدول مثل الاسم، واسم العرض، والنص البديل، والنمط، والرؤوس، والإجماليات، وإعدادات الفلترة التلقائية
• الوصول إلى نطاقات الجدول بما في ذلك صفوف الرؤوس، ونطاقات نص البيانات، وصفوف الإجماليات
• إدارة الأعمدة والصفوف من خلال ApiListColumn و ApiListRow، مع توابع للأسماء، والفهارس، والنطاقات، وحساب الإجماليات، والحذف
• دعم الفرز عبر فئات ApiSort و ApiSortFields و ApiSortField الجديدة — بما يغطي اتجاه الفرز، ومطابقة حالة الأحرف، ومعايير الفرز بناءً على (القيمة أو اللون)، والأولوية، والمزيد

إذا كان تكاملكم يتضمن أي نوع من إدارة البيانات المنظمة في جداول البيانات مثل استيراد البيانات، أو إنشاء الجداول الديناميكية، أو إنشاء التقارير، فإن هذه الإضافة توسع بشكل كبير ما يمكنكم القيام به دون مطالبة المستخدمين بفرز الجداول يدوياً.

توابع التعبئة والمعادلات الجديدة لـ Spreadsheet

تم إضافة أربعة توابع تعبئة اتجاهية إلى ApiRange: وهي FillDown و FillUp و FillRight و FillLeft.

تحاكي هذه التوابع سلوك تعبئة جداول البيانات الذي يقوم المستخدمون بتشغيله يدوياً، وهي متاحة الآن للاستخدام البرمجي. بالاشتراك مع تابع ApiRange/SetFormula الجديد، يمكنكم بناء أتمتة تنشئ نطاقات مدفوعة بالمعادلات ديناميكياً. وهي مفيدة للتقارير التي يتم إنشاؤها، وجداول البيانات القائمة على القوالب، وأتمتة إدخال البيانات.

تم أيضاً إضافة تابع Api/GetDefNames إلى Spreadsheet API، مما يمنحكم إمكانية الوصول إلى الأسماء المعرفة (النطاقات المسماة) في مصنف العمل.

عناصر التحكم في تنسيق نموذج النص

تكتسب فئة ApiTextForm أربعة توابع جديدة في كل من واجهتي برمجة تطبيقات Document و Form:

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