أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل

تواصل Google عملها في مهمة تسهيل الحياة اليومية على المستخدمين، فبعد أن أتاحت التطبيقات المختلفة التي لا غِنى عنها، مثل: بريد Gmail، والمستندات، وجداول البيانات، والعروض التقديمية، وذلك لمساعدة الأفراد والشركات في إنجاز أعمالهم كلها من مكان واحد ودون عناء، فقد أتاحت أيضًا أداة تُعد من أكثر أدوات الإنتاجية فعالية وهي "برمجة التطبيقات Apps Script"، فهي تتيح لك إنشاء إضافات فعالة لتطبيقات Google باستخدام مقتطفات من شيفرة JavaScript، فبضعة دقائق من كتابة الشيفرة البرمجية تمكنك من تشكيل تطبيقات جوجل إلى أدوات مخصصة لعملك.

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

ومن خلال هذا الدليل سوف نتعلم سويًّا أساسيات Apps Script وكيفية استخدامها لتحسين تجربتك في استخدام جداول بيانات جوجل.

ما هو Apps Script؟

يُعد Apps Script نظامًا أساسيًا سريعًا لتطوير التطبيقات يمنحك القدرة على أتمتة المهام الخاصة بك وتخصيصها وتوسيعها. باستخدام Apps Script، يمكنك توفير الوقت والجهد من خلال تبسيط العمل الشاق أو المعقد داخل حزمة تطبيقات جوجل، وتتضمن ميزات Apps Script ما يلي: تتيح لك الخدمات المضمنة في Apps Script قراءة بيانات تطبيق Google Workspace وتحديثها ومعالجتها وذلك باستخدام "السكربت Script". يمكنك إنشاء نصوص برمجية باستخدام محرر السكربت في Apps Script وذلك من خلال المتصفح، فليست هناك حاجة لتثبيت أو تشغيل برنامج تحرير الشيفرات البرمجية. يمكنك تصميم واجهات مستخدم لتطبيقات Google Workspace مما يتيح لك تشغيل هذه التطبيقات مباشرة باستخدام عناصر القائمة ومربعات الحوار والأشرطة الجانبية.

جداول البيانات

يمكنك استخدام Apps Script مع جداول بيانات جوجل لتوفير الوقت والجهد، مما يسمح للنصوص بالتفاعل مع ملفات جداول بيانات جوجل والبيانات التي تحتوي عليها، ويمكنك استخدام هذه الخدمة لأتمتة مهام جدول البيانات الشائعة التالية:

• إنشاء أو تعديل جدول البيانات.
• قراءة وتحديث بيانات الخلية والصيغ والتنسيق.
• إنشاء أزرار وقوائم مخصصة.
• استيراد وتصدير البيانات من تطبيقات جوجل الأخرى أو من مصادر خارجية.
• المشاركة والتحكم في الوصول إلى جداول البيانات.

ماذا ستتعلم

يغطي هذا الدليل جميع الموضوعات التي ستحتاج إليها لبدء استخدام Apps Script مع جداول بيانات جوجل، وهي على النحو التالي:

1. أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل.
2. التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script.
3. العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script.
4. كيفية استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Script.
5. تنسيق البيانات داخل جداول بيانات جوجل باستخدام Apps Script.
6. الرسوم البيانية وعرضها في شرائح جوجل من خلال Apps Script.

وعلى وجه التحديد، سوف يركز هذا الدليل على مفهومين أساسيين، وهما:

• وحدات الماكرو Macros: وهي عبارة عن سلسلة من الإجراءات المسجلة داخل جداول بيانات جوجل، وبمجرد تسجيلها يمكنك تشغيلها لتكرار هذه الإجراءات لاحقًا باستخدام عنصر قائمة أو مفتاح اختصار، ويمكنك إنشاء وتحديث وحدات الماكرو الخاصة بك في كل من "جداول بيانات جوجل" و "محرر السكربت Apps Script".
• الدوال المخصصة Custom Functions: في محرر السكربت يمكنك أيضًا إنشاء دوال مخصصة، وذلك على غرار الدوال المضمنة التي توفرها جداول البيانات، مثل: SUM أو AVERAGE، ويمكنك استخدام Apps Script لكتابة دوالك المخصصة لعمليات بسيطة ومتخصصة، وبمجرد إنشاؤها يمكنك استدعاء هذه الدوال في "جداول البيانات" كما تفعل مع أي دالة مضمنة، ويمكنك أيضًا استخدام الدوال المخصصة في صيغ الخلايا التي تكتبها وتجمعها مع دوال أخرى حسب الحاجة.

ماذا ستحتاج

• الإلمام الأساسي بلغة البرمجة جافا سكريبت.
• الإلمام الأساسي بجداول بيانات جوجل.

اقتباس

تنويه: يعتمد استخدام Apps Script مع جدول بيانات جوجل أن تكون على دراية بلغة البرمجة جافا سكريبت JavaScript وكيفية التعامل مع جداول بيانات جوجل، فإن كنت جديدًا أو غير متمكنًا منهم فإن أكاديمية حسوب تقدم سلسلة مقالات في لغة البرمجة جافا سكريبت باسم دليل تعلم جافاسكربت وسلسلة مقالات حول جداول بيانات جوجل تغطي كل ما تحتاج إلى معرفته.

إنشاء ماكرو في جداول البيانات

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

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

لذلك في هذا القسم من دليل "أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل"، ستتعلم كيفية إنشاء وحدة ماكرو في "جداول البيانات"، وفي القسم التالي ستتعلم كيفية إنشاء وحدات الماكرو باستخدام Apps Script.

قبل أن تبدأ

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

الحل الأول أن تنسخ البيانات الموجودة بملف مايكروسوفت إكسل الذي حملته من المقالة وذلك من خلال الضغط على مفتاحي Ctrl + A من لوحة المفاتيح لتحديد جميع البيانات بالملف.

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

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

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

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

ومن النافذة التي ستظهر لك حدد الملف من المسار الذي حملته فيه ثم اضغط على زر "Open" ليتم رفعه إلى حسابك على جوجل درايف.

الآن انتبه من أمر هام، فالملف الذي رفعته هو بتنسيق "مايكروسوفت إكسيل" وبالتلي لن تجد به القائمة "إضافات" التي تمكنك من إضافة الشيفرات البرمجية لـ Apps Script

لذلك يجب علينا تحويل هذا الملف إلى "جدول بيانات جوجل"، وذلك من خلال النقر على القائمة "ملف" ثم اختيار "الحفظ بتنسيق جدول بيانات Google".

سوف يفتح لك الملف بتنسيق جدول بيانات جوجل في تبويبة جديدة، ويمكنك الآن حذف الملف الذي بتنسيق مايكروسوفت اكسل حتى لا يحدث لك ارتباك بين الملفين أثناء تنفيذ التدريبات. ذ

سنطبق هذه العملية مع كل الجداول في هذا المقال طبعًا والمقالات اللاحقة لذا لن نكررها لاحقًا في مقالات السلسلة.

أصبح الجدول الذي سنطبق عليه المقال جاهزًا حتى تتابع معنا ولا بأس من اختيار جدول آخر من اختيارك لتطبيق ما تريد.

طريقة إنشاء ماكرو

الآن بعد أن أصبح لديك جدول بيانات للعمل معه، يمكنك تسجيل ماكرو في جداول بيانات جوجل، ففي هذا المثال سوف ننشىء ماكرو يعمل على تنسيق صف الرأس لبياناتك، فقط ما عليك سوى اتباع هذه الخطوات:

• أولًا، انقر فوق الخلية "A1" لوضع المؤشر في صف الرأس لبياناتك.

• ثانيًا، من شريط القوائم بأعلى جدول البيانات حدد "الإضافات"، ثم اختر منها "وحدات الماكرو"، ثم اختر منها "تسجيل ماكرو".

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

• ثالثًا، في مربع حوار الماكرو حدد "استخدام المراجع ذات الصلة".

اقتباس

توضيح: يمكن لوحدات الماكرو استخدام نوعين من المراجع في "جداول البيانات" للإشارة إلى خلايا معينة، فيتم استخدام "المراجع المطلقة" على المواقع الدقيقة، مثل: الخلية "A5"، بينما يتم استخدام "المراجع ذات الصلة" لتحديد الموقع الحالي للمستخدم كنقطة بداية، مثل: الخلية الرابعة أسفل الموقع الحالي.

• رابعًا، حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1".

• خامسًا، أعد تلوين لون التعبئة للصف العلوي من الأبيض إلى أي لون تريده.

• سادسًا، أعد تلوين لون نص الصف العلوي من الأسود إلى أي لون تريده.

• سابعًا، لتغميق النص اضغط على مفتاحي Ctrl + B من لوحة المفاتيح، أو مفتاحي Cmd + B في نظام macOS.
• ثامنًا، لتجميد الصف العلوي حدد القائمة "عرض"، ثم اختر منها "تجميد"، ثم اختر منها "صف واحد".

• أخيرًا، انقر على "حفظ" في مربع حوار الماكرو، سيطلب منك مربع حوار جديد تسمية الماكرو، أدخل أي اسم تريده لكن يُفضل أن يكون ذا دلالة على وظيفته، كما يُفضل أن تكون التسمية بالإنجليزية، على سبيل المثال: "تنسيق الصف الرئيسي" أو "HeaderFormat"، ثم انقر على "حفظ".

أصبح لديك الآن ماكرو مخصص لتنسيق الصف الرئيسي، وذلك باستخدام واجهة مستخدم جداول البيانات.

استخدام الماكرو الخاص بك

يمكنك تطبيق الماكرو الجديد في "جداول البيانات" باتباع الإرشادات التالية:

• أولًا، في جدول البيانات الحالي انقر على (+) الموجودة أسفل يمين النافذة، وذلك لإضافة ورقة جديدة.

• ثانيا، في الورقة الجديدة أضف بعض النصوص ابتداءً من الخلية A1 إلى الخلية C2.

• ثالثًا، حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1".
• رابعًا، لتطبيق الماكرو على المنطقة المحددة، انقر على "الإضافات"، ثم اختر منها "وحدات الماكرو"، ثم اختر منها الاسم الذي أعطيته لوحدة الماكرو أثناء حفظه، وفي المثال الذي معنا سيكون باسم "تنسيق الصف الرئيسي".

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

اقتباس

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

• سادسًا، كرر الخطوة 4 لتشغيل الماكرو مرة أخرى، وذلك لأن عملية الحصول على إذن له أوقفت عملية التنفيذ.

تهانينا، لقد تعلمت كيفية تطبيق وحدات الماكرو في جداول البيانات، ويجب أن يبدو جدول البيانات كما يلي:

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

وحدات الماكرو في محرر السكربت

أثناء إنشاء وحدة ماكرو تحفظ "جداول بيانات جوجل" إجراءاتك كدالة Apps Script، وعند تطبيق الماكرو تستدعي "جداول بيانات جوجل" دالة Apps Script لتطبيق هذه الإجراءات بالترتيب نفسه.

محرر السكربت

الآن بعد أن أنشأت وحدة ماكرو، يمكنك إلقاء نظرة على الشيفرة البرمجية الخاصة به، ولعرض الشيفرة البرمجية لهذا الماكرو انقر على "الإضافات"، ثم اختر منها "برمجة تطبيقات جوجل" لفتح محرر شيفرات البرمجة لـ Apps Script من خلال المتصفح.

يتيح لك محرر السكربت كتابة التعليمات البرمجية في Apps Script وتشغيل تلك النصوص البرمجية على خوادم جوجل.

تحليل الشيفرات البرمجية لوحدات الماكرو gs.

أنشأت جداول البيانات ملف السكربت "macros.gs" عند تسجيل وحدة الماكرو، وملئه بدالة Apps Script التي تسمى HeaderFormat، وهو نفس الاسم الذي كتبناه أثناء حفظ وحدة الماكرو في الخطوة التاسعة من خطوات "إنشاء ماكرو"، لكن في حالة كتابة اسم الماكرو باللغة العربية ستظهر لك دالة Apps Script باسم MyFunction، لذلك أكرر عليك باستخدم التسميات الإنجليزية.

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

• السطر الأول: عبارة عن تعليق توضيحي يؤثر على التفويض، تطلب معظم البرامج النصية من المستخدم بعض الأذونات قبل تشغيلها، وتتحكم هذه الأذونات في ما يسمح المستخدم للبرنامج النصي بتنفيذه، فعندما يكون التعليق OnlyCurrentDoc موجودًا في مشروع شيفرة برمجية، فإن Apps Script تطلب فقط الإذن للوصول إلى جدول البيانات الحالي وتحديثه، لكن بدون هذا التعليق سيطلب Apps Script إذنًا للوصول إلى جميع جداول بيانات المستخدم وتحديثها، لذلك من الأفضل دائمًا تضمين هذا التعليق التوضيحي عندما تعمل مع ملف واحد فقط، ويضيف مسجل الماكرو هذا التعليق تلقائيًا نيابة عنك.

/** @OnlyCurrentDoc */

• السطر الثاني: عبارة عن تحديد اسم الدالة كما ذكرنا سابقًا، ثم يلي الاسم قوسان لتمرير المُعَامل، لكن دوال الماكرو في Apps Script لا تحتاج إلى أي مُعَامل أو مدخلات، ثم يأتي في نهاية السطر القوس المعقوص الذي يحتوي جسم الدالة.

function HeaderFormat() {

• السطر الثالث: لاحقًا في هذا الدليل سوف نتناول "الأصناف Classes" و "المفاهيم Concepts" التي ينطوي عليها إنشاء الماكرو، لكن في الوقت الحالي يمكنك الاطلاع على أوصاف الشيفرة البرمجية في هذا السطر للحصول على فكرة عامة عن مكوناته ودوره في بناء الماكرو الخاص بك، فعلى سبيل المثال: هنا يُرجع ()getActive. كائنًا يمثل ملف جدول البيانات النشط الحالي في "ورقة البيانات" ويخزنها في متغير اسمه spreadsheet.

var spreadsheet = SpreadsheetApp.getActive();

• السطرين الرابع والخامس: هذان السطران يتوافقان مع إجراء النقر على الصف الأول لتمييزه، وهذا الإجراء يسمى "التنشيط"، فيخزن السطر الرابع الورقة الحالية في متغير باسم sheet، بينما يحصل السطر الخامس على الصف الأول بالكامل باستخدام الـ Method أو التابع ()getRange. ثم استدعاء التابع ()activate. لتنشيطه، وحدد الصف الأول باستخدام أرقام الصفوف والأعمدة، فالاستدعاء ()spreadsheet.getCurrentCell().getRow يُرجع رقم الصف الحالي، أما الاستدعاء ()sheet.getMaxColumns يُرجع الحد الأقصى لعدد الأعمدة في الورقة.

var sheet = spreadsheet.getActiveSheet();
sheet.getRange(spreadsheet.getCurrentCell().getRow(), 1, 1, sheet.getMaxColumns()).activate();

• السطر السادس إلى الثامن: الاستدعاء ()getActiveRangeList. يُرجع قائمة بالنطاقات النشطة الحالية في جدول البيانات وهو الصف الأول بالكامل في مثالنا، وتعمل كل من (setBackground(color و (setFontColor(color على تغيير سمات اللون للخلايا في النطاق النشط، أما التابع (setFontWeight(fontWeight يضبط وزن الخط للخلايا في النطاق النشط.

spreadsheet.getActiveRangeList().setBackground('#38761d')
.setFontColor('#ffffff')
.setFontWeight('bold');

• السطر التاسع: يجمد هذا السطر الصف الأول من الماكرو.

spreadsheet.getActiveSheet().setFrozenRows(1);

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

تخصيص وحدات الماكرو باستخدام محرر Apps Script

يعرض محرر Apps Script الماكرو الذي أنشأته مسبقًا في جداول بيانات جوجل، فمن خلال ضبط محتويات جسم "الدالة Function" يمكنك تخصيص تعليمات الماكرو لاتخاذ إجراءات مختلفة أو إضافية، وتوضح التمارين التالية طرائق مختلفة للتعامل مع وحدات الماكرو باستخدام محرر السكربت.

تغيير الخلايا المستهدفة

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

بدايةً، في محرر السكربت استبدل الاستدعاء ()sheet.getMaxColumns بالعدد "9"، يغير هذا التعديل نطاق الخلايا التي يؤثر عليها الماكرو في جدول البيانات.

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

خذ نسخة جديدة من جدول البيانات "أفضل 10 أفلام لعام 2022" ثم طبق عليه وحدة الماكرو.

تغيير الألوان بوحدة الماكرو

لمساعدتك في تصميم نظام ألوان وحدات الماكرو أو العناصر الأخرى في "جداول البيانات"، يمكن لـ Apps Script تعديل لون تعبئة خلفية النطاق أو لون النص، اعمل من خلال الإرشادات التالية لتتعلم كيف يمكنك تخصيص ألوان الماكرو:

بدايةً، افتح جدول البيانات "أفضل 10 أفلام لعام 2022"، ثم حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1"، واستبدل في محرر السكربت نظام الألوان الستة عشري للخلفية من 38761d# إلى afeeee#.

احفظ الشيفرة البرمجية الخاص بك بالنقر على أيقونة "حفظ"، ثم حدد من قائمة الدوال اسم الدالة التي نعمل عليها وهي HeaderFormat، ثم انقر على الزر "Run".

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

في القسم التالي من هذا الدليل ستتمكن من عرض طريقة أخرى تساعدك بها Apps Script في العمل مع جداول بيانات جوجل، وهي: الدوال المخصصة.

أكتب نصك البرمجي الأول: الدوال المخصصة

مثل معظم تطبيقات جداول البيانات، تحتوي جداول بيانات جوجل على العديد من الدوال المضمنة مثل '()SUM=' التي تتيح إجراء عمليات حسابية سريعة على بيانات جدول البيانات، والدوال المخصصة هي ببساطة دالة تحددها باستخدام Apps Script، وبمجرد تحديد دالة مخصصة يمكنك استخدامها في أي مكان في جدول البيانات تمامًا مثل الدالة المضمنة.

ويوضح لك هذا القسم كيفية إنشاء دالة مخصصة في Apps Script تقوم بإجراء تحويل نقدي.

إنشاء ملف نصي

باستخدام نفس جدول البيانات الذي نعمل عليه "أفضل 10 أفلام لعام 2022"، اتبع هذه الإرشادات لمعرفة كيفية إنشاء نَص برمجي جديد، والذي يمكنك استخدامه في النهاية لإنشاء أول دالة مخصصة لك:

• أولًا، افتح محرر السكربت كما تعلمنا.
• ثانيًا، بجوار القائمة "الملفات" انقر على الأيقونة (+) لإضافة ملف، ثم اختر منها "نص برمجي".

• ثالثًا، سمّ ملف الشيفرة البرمجية الجديد "ChangeCurrency"، ثم اضغط على مفتاح "Enter" من لوحة المفاتيح، وستلاحظ أن Apps Script يُلحق تلقائيًا الامتداد "gs." لاسم ملف الشيفرة البرمجية.

الآن بعد أن أنشأت ملف شيفرة برمجية لدالة مخصصة، يمكنك ملؤه بالشيفرة البرمجية.

تحويل الدولار الأمريكي إلى جنيه مصري

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

لكن قبل أن تتمكن من كتابة أول دالة مخصصة لك، عَدِّل مجموعة البيانات الخاصة بك للسماح للدالة بإظهار مخرجات مناسبة، ولفعل هذا نفذ الآتي.

في جداول البيانات "أفضل 10 أفلام لعام 2022" انقر بزر الفأرة الأيمن على العمود "G"، ومن القائمة التي ستظهر انقر على "إدراج عمود واحد لليسار".

حدد الخلية "H1" ثم أعطها هذا الاسم "الإيرادات عالميًا بالجنيه المصري".

الآن أصبح لديك عمود يمكنه تخزين نتائج دالة تحويل العملة المخصصة، بعد ذلك يمكنك استخدام محرر السكربت لإنشاء أول دالة مخصصة لك.

اذهب بعدها إلى المحرر وحدد الملف النصي الذي أنشأته باسم "ChangeCurrency.gs" واحذف الشيفرة البرمجية الموجودة بداخله واستبدله بالشيفرة البرمجية التالية:

/**
 تحول الدولار الأمريكي إلى جنيه مصري *
*
* @param {number} dollars إجمالي الإيرادات بالدولار الأمريكي
* @return {number} EGPs إجمالي المبلغ المحول إلى الجنيه المصري
* @customfunction دالة مخصصة
 */
function USDTOEGP(dollars){
  var EGP = dollars * 18.31; 
  return EGP;
}

هذه هي الشيفرة البرمجية التي سوف تحول الدولار الأمريكي إلى الجنيه المصري، الآن جرب الإرشادات أدناه وشاهد كيف يمكنك تشغيل دالة مخصصة في جدول البيانات.

احفظ بعد ذلك الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ" ثم اذهب إلى جدول البيانات "أفضل 10 أفلام لعام 2022"، ثم حدد الخلية "H2"، واكتب في شريط المعادلات هذه المعادلة (USDTOEGP(G2=، ثم اضغط على زرار "Enter" من لوحة المفاتيح.

ولتطبيق هذه المعادلة على باقي الخلايا في العمود، اتبع التالي:

حرك بعد ذلك مؤشر الفأرة إلى الزاوية السفلية اليسرى للخلية "H2" وحدد المربع الأزرق الصغير، ويجب أن يتحول مؤشر الفأرة إلى علامة (+) عند الإشارة إلى المربع الأزرق بعدها اسحب المربع الأزرق للأسفل لتحديد جميع الخلايا.

تهانينا، لقد أنشأت أول دالة مخصصة لك تعمل على سرد العمود "H" تحويلات الجنيه المصري لقيم الدولار الأمريكي الموجودة في العمود "G"، وفي القسم التالي تحليل للشيفرة البرمجية لهذه الدالة.

تحليل الشيفرة البرمجية للدالة المخصصة ()USDTOEGP

أولًا، توضح التعليقات الأولية الغرض من الشيفرة البرمجية:

/**
 تحول الدولار الأمريكي إلى جنيه مصري *
 *
 * @param {number} dollars إجمالي الإيرادات بالدولار الأمريكي
 * @return {number} EGPs إجمالي المبلغ المحول إلى الجنيه المصري
 * @customfunction دالة مخصصة
 */

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

فعندما تكتب التعليقات التوضيحية يستخدم برمجة التطبيقات JSDoc لمساعدتك في توثيق وإنشاء تلميحات الإكمال التلقائي لشيفرتك البرمجية.

• فالتعليق param@: يستخدم لوصف كل مُعَامل تم تمريرها إلى الدالة.
• والتعليق return@: يستخدم لوصف ما تعيده الدالة.
• والتعليق customfunction@: يُخطر هذا التعليق جدول البيانات بالإكمال التلقائي لدالتك المخصصة، تمامًا كما تُكمل جداول البيانات تلقائيًا الدوال المضمنة عند إدخال اسمها في خلية، لذلك يجب عليك استخدام هذا التعليق مع أي دالة مخصصة تنشئها.

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

ثانيًا، تأخذ الدالة ()USDTOEGP متغير رقمي وهي "قيمة العملة بالدولار"، ثم يضربها في سعر الصرف وهو رقم ثابت، ثم يعيد القيمة المحولة إلى الجنيه المصري في المتغير الرقمي EGP، ومُعَامل الإدخال (dollars) هي القيمة المضمنة في الخلية المحددة عند إضافة دالة مخصصة إلى خلية، ففي مثالنا تأتي مبالغ الإدخال بالدولار من العمود "G"، وتوضع قيمة الإخراج EGP في الخلية التي كُتبت بها الدالة بالعمود "H".

ويمكن أن تُرجع الدوال المخصصة قيم رقمية أو سلسلة نصية، كما سترى في القسم التالي.

إرجاع سلسلة نصية

لنفترض أنك أردت أن يشتمل الناتج الرقمي للدالة ()USDTOEGP على بادئة تشير إلى أن العُملة المستخدم هي الجنيه المصري، يمكنك عمل ذلك في Apps Script باستخدام عامل التشغيل (+) كما هو موضح في الإرشادات التالية:

• أولًا، في محرر السكربت حَدِّث التعليق التوضيحي return@ لإرجاع سلسلة نصية بدلًا من رقم.

• ثانيًا، تعديل شيفرة الإرجاع return بالشكل التالي:

return 'جنيه مصري' + EGP;

يضيف عامل التشغيل (+) السلسلة النصية 'جنيه مصري' إلى مقدمة القيمة الرقمية الموجودة في EGP.

• ثالثًا، احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ".

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

خاتمة

وإلى هنا نكون قد وصلنا إلى نهاية هذا الدرس من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه إنشاء وتعديل وحدات ماكرو والدوال المخصصة، وفي الدرس القادم سوف نتعرف على "الأصناف Classes" والمصطلحات الأساسية لخدمة جداول بيانات Apps Script التي تمكنك من التحكم بدقة في قيم البيانات وعرضها في جداول بيانات جوجل باستخدام Apps Script.

نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات.

اقرأ أيضًا

• إنشاء وتصميم جداول بيانات جوجل Google Sheets