كيفية تشغيل برامج بايثون النصية في وحدات ماكرو LibreOffice Calc

نعم. يستطيع LibreOffice Calc تشغيل كود بايثون كوحدة ماكرو داخل عملية LibreOffice، كما يمكن لماكرو LibreOffice Basic استدعاء دالة بايثون عبر إطار عمل البرمجة النصية الخاص بـ LibreOffice. إذا كان هدفك قراءة أو تعديل خلايا في جدول البيانات المفتوح، فإن ماكرو بايثون داخل العملية هو عادةً أبسط نقطة بداية. استخدم استدعاء Basic-to-Python عندما يحتاج ماكرو Basic موجود إلى إسناد مهمة معينة إلى دالة بايثون قابلة لإعادة الاستخدام.

تختلف هذه الأساليب عن تشغيل سكربت بايثون عادي باستخدام أمر سطر الأوامر. لا تتلقى عملية بايثون خارجية عادية كائن المستند الخاص ببرنامج Calc تلقائيًا. للوصول إلى المصنف، شغّل ماكرو بايثون من خلال LibreOffice أو اربط عملية خارجية بنسخة LibreOffice عمدًا عبر UNO.

ماذا يعني "تشغيل بايثون داخل ماكرو كالك"؟

يدعم LibreOffice لغات برمجة نصية متعددة من خلال إطار عمله. في ماكرو بايثون، يوفر LibreOffice كائن سياق UNO يسمح للبرنامج النصي بالوصول إلى المستند الحالي وأوراقه. ماكرو بايثون هو دالة ضمن .pyوحدة نمطية؛ g_exportedScriptsوتحدد مجموعة الوحدة النمطية الدوال التي يجب أن يعرضها LibreOffice كوحدات ماكرو قابلة للتنفيذ.

يمكن تشغيل ماكرو بايثون بشكل مستقل من قائمة الماكرو في برنامج Calc، دون الحاجة إلى استدعائه من لغة Basic. إذا كان لديك ماكرو Basic وترغب في أن يستدعي بايثون، Session.ExecutePythonScriptفيمكنك استخدام موفر البرامج النصية في LibreOffice أو خدمة ScriptForge الأحدث لربط اللغتين.

أي نهج يجب أن تختار؟

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

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

كيف يمكنك إنشاء ماكرو بايثون يقوم بتحرير خلايا برنامج Calc؟

يخزن LibreOffice نصوص بايثون الشخصية في ملف تعريف المستخدم، والنصوص العامة للتطبيق في مجلد التثبيت، ونصوص المستندات مع المستند نفسه. في الاختبار الأولي، يُعد النص الشخصي مناسبًا لأنه متاح من أي مستند LibreOffice مفتوح لنفس المستخدم. مع ذلك، لا يُنقل هذا النص مع ملف ODS، لذا لن يتلقاه شخص آخر تلقائيًا مع جدول البيانات.

ابحث عن مجلد نصوص بايثون الشخصية لنظامك في تعليمات LibreOffice ضمن "تنظيم نصوص بايثون وموقعها". تشمل المواقع الشائعة %APPDATA%\LibreOffice\4\user\Scripts\pythonعلى نظامي التشغيل Windows و ~/.config/libreoffice/4/user/Scripts/pythonLinux. قد يختلف الملف الشخصي الفعلي؛ استخدم الموقع الموثق لتثبيتك بدلاً من إنشاء دليل ملف شخصي ثانٍ بشكل عشوائي.

أنشئ ملفًا باسم calc_tools.pyفي مجلد البرامج النصية الشخصية بلغة بايثون، ثم أضف هذا المثال البسيط:

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

يقرأ هذا الأمر القيمة العددية في الخلية A1 من الورقة النشطة ويكتب ضعف تلك القيمة في الخلية B1. XSCRIPTCONTEXTيتم تمرير هذا الأمر إلى ماكرو بايثون في LibreOffice أثناء التشغيل؛ فهو ليس متغيرًا عامًا عاديًا في بايثون عند تشغيل الملف نفسه خارج LibreOffice. يتم إدراج الدالة العامة في g_exportedScriptsملف `.org/libreoffice ...

احفظ الملف، ثم افتحه أو ارجع إلى برنامج Calc واختر أدوات > وحدات الماكرو > تشغيل وحدات الماكرو . قد يكون اسم القائمة بصيغة المفرد، وذلك حسب إصدار LibreOffice أو ترجمة النظام الأساسي. حدد وحدات الماكرو الخاصة بي > calc_tools > double_a1 وشغّلها. أدخل رقمًا في الخلية A1 أولًا، ثم تأكد من أن الخلية B1 تحتوي على القيمة المضاعفة. إذا لم يظهر البرنامج، فتأكد من أن امتداد الملف هو .py .py، وأن الملف موجود في مجلد Python الخاص بالملف الشخصي الصحيح، وأن دعم برمجة Python مثبت. قد يساعد إعادة تشغيل LibreOffice بعد إضافة برنامج جديد في تحديث قائمة البرامج النصية.

كيف يمكن لماكرو Basic استدعاء دالة Python؟

لإجراء استدعاء من لغة Basic إلى لغة Python، ضع وحدة Python في مجلد البرامج النصية الشخصية، ثم استدعِ دالتها عبر Sessionخدمة ScriptForge. يجمع هذا المثال قيمتين في Python ويكتب النتيجة في الخلية B1 في ورقة Calc الحالية.

في calc_tools.py، قم بتعريف الدالة:

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

ثم أنشئ ماكرو أساسي في برنامج Calc واستخدمه:

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

قم بتشغيل البرنامج RunPythonHelperمن مُحدِّد الماكرو الأساسي. إذا نجح الاستدعاء، يجب أن تعرض الخلية B1 الرقم 42. يتبع مرجع البرنامج النصي الشكل التالي module.py$function_name: ; بالنسبة لوحدة نمطية في مجلد فرعي أو موقع تخزين آخر، استخدم الصيغة وثابت الموقع الموثقين لإصدار ScriptForge هذا. حافظ على الوسائط وقيم الإرجاع من أنواع البيانات التي يمكن لكلا اللغتين تمثيلها بشكل صحيح، مثل الأرقام والسلاسل النصية والتسلسلات البسيطة.

CreateScriptServiceتتوفر أدوات مساعدة جلسات ScriptForge الموثقة في إصدارات LibreOffice الحديثة، ولكن قد تختلف أسماء القوائم والمكونات المضمنة في الإصدارات القديمة أو تلك المُجمّعة. في حال عدم توفر هذه الخدمة، استخدم طريقة مُزوّد ​​البرامج النصية UNO الموثقة في LibreOffice، والتي تحصل على مُعرّف البرنامج النصي XScriptمن عنوان URI الخاص بالبرنامج النصي وتستدعيه. تجنّب نسخ جزء من التعليمات البرمجية لموقع ماكرو مختلف دون تغيير إعدادات موقعه.

هل ينبغي أن يكون كود بايثون شخصيًا، أو مشتركًا، أو مضمنًا؟

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

لماذا قد يكون الماكرو مفقودًا أو فاشلاً؟

• خيار أو وحدة بايثون غير موجودة. في بعض توزيعات جنو/لينكس، يُعد إطار عمل برمجة بايثون الخاص بـ LibreOffice حزمة اختيارية. راجع تعليمات تثبيت LibreOffice الخاصة بالتوزيعة إذا لم تظهر وحدات ماكرو بايثون في مربع حوار الماكرو.
• تم حفظ البرنامج النصي في ملف تعريف خاطئ. يمكن لبرنامج LibreOffice استخدام ملفات تعريف مستخدمين متعددة. تأكد من مسار ملف التعريف الخاص بالتثبيت الحالي، واحفظ الوحدة النمطية في دليله Scripts/python.
• هذه الدالة غير مُصدَّرة. أضفها إلى g_exportedScriptsالدالة التي تنوي تشغيلها من مُحدِّد الماكرو. تأكد من أن صيغة المجموعة تتضمن الفاصلة الأخيرة لمجموعة من عنصر واحد.
• يعمل البرنامج النصي خارج LibreOffice. XSCRIPTCONTEXT هذا ينطبق على الماكرو الذي يتم تشغيله بواسطة LibreOffice، وليس عند تشغيل الملف نفسه باستخدام أمر النظام python. استخدم مُشغِّل الماكرو أو أنشئ اتصال UNO موثقًا.
• يمنع نظام أمان وحدات الماكرو تضمين التعليمات البرمجية. راجع إعدادات أمان وحدات الماكرو في LibreOffice، ولا تسمح إلا بتفعيل التعليمات البرمجية من مصدر موثوق. إن خفض مستوى الأمان العام ليس حلاً سريعاً وفعالاً لحل المشكلات.
• لا يمكن للوحدة النمطية المستوردة الوصول إلى سياق المستند. مستندات LibreOffice XSCRIPTCONTEXTغير مُمرَّرة إلى الوحدات النمطية المستوردة. مرِّر كائن المستند أو ورقة العمل المطلوب إلى الدوال المساعدة بدلاً من توقع أن تقرأ الوحدات النمطية المستوردة هذا المتغير العام.
• لا يوجد أي مخرج مرئي في وحدة التحكم. لا يتوفر الإخراج القياسي للغة بايثون عند تشغيل ماكرو من قائمة الأدوات > وحدات الماكرو. للحصول على ملاحظات، اكتب النتيجة في خلية، أو استخدم خدمة حوار LibreOffice، أو سجلها في مسار ملف محدد.

كيف يمكنك التحقق من النتيجة بأمان؟

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

عند نجاح الاختبار، حدد كيفية تثبيت البرنامج النصي على أجهزة الكمبيوتر الأخرى، ووثّق أي مكتبات بايثون مطلوبة أو افتراضات حول إصدار LibreOffice. بيئة بايثون المدمجة في LibreOffice هي المستخدمة لوحدات الماكرو داخل العملية؛ وقد لا تكون الحزم المثبتة لمفسر بايثون منفصل متاحة لها. إذا كنت بحاجة إلى حزم من مفسر آخر، فاستخدم طريقة العملية الخارجية/UNO وقم بتهيئة هذا الاتصال بعناية.

المراجع الرسمية

• مساعدة LibreOffice: إنشاء برامج بايثون باستخدام ScriptForge
• مساعدة LibreOffice: استدعاء نصوص بايثون من لغة Basic
• مساعدة LibreOffice: البرمجة باستخدام نصوص بايثون
• مساعدة LibreOffice: تنظيم وتحديد موقع نصوص بايثون
• مساعدة LibreOffice: قراءة وكتابة القيم في النطاقات
• مجموعة تطوير البرامج (SDK) الخاصة بـ LibreOffice: واجهة XScript