أساسيات "برمجة تطبيقات Google" مع "جداول بيانات Google" #1: وحدات الماكرو والدوال المخصّصة

1. مرحبًا بك في Apps Script

ما هي "برمجة تطبيقات Google"؟

برمجة تطبيقات Google هي منصة لتطوير التطبيقات بسرعة، وتتيح لك إمكانية إدارة تجربة Google Workspace تلقائيًا وتخصيصها وتوسيعها. باستخدام Apps Script، يمكنك توفير الوقت والجهد من خلال تبسيط المهام الصعبة أو المعقّدة في Google Workspace.

تشمل ميزات Apps Script ما يلي:

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

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

خدمة "جداول بيانات Google"

يمكنك استخدام "برمجة التطبيقات" من أجل توسيع نطاق "جداول بيانات Google" لتوفير الوقت والجهد. توفّر "برمجة تطبيقات Google" خدمة جداول البيانات التي تتيح للبرامج النصية التفاعل مع ملفات "جداول بيانات Google" والبيانات التي تحتوي عليها. يمكنك استخدام هذه الخدمة لأتمتة مهام جداول البيانات الشائعة التالية:

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

أهداف الدورة التعليمية

تغطّي قائمة التشغيل هذه جميع المواضيع التي تحتاج إليها لبدء استخدام "برمجة تطبيقات Google" مع "جداول بيانات Google":

1. وحدات الماكرو والدوال المخصّصة
2. جداول البيانات والصفحات والنطاقات
3. العمل باستخدام البيانات
4. تنسيق البيانات
5. إنشاء رسوم بيانية وعرض البيانات في "العروض التقديمية من Google"

من المفترض قراءة دروس Codelab في قائمة التشغيل هذه بالترتيب، لذا ابدأ بهذا الدرس وأكمِلها بالتسلسل للحصول على أفضل تجربة تعليمية.

انتقِل إلى القسم التالي لمعرفة المزيد عن محتوى هذا الدرس العملي.

2. مقدمة

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

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

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

اطّلِع على ما يلي للتعرّف على المفاهيم والمتطلبات التي يتضمّنها هذا الدرس التطبيقي حول الترميز.

أهداف الدورة التعليمية

• كيفية إنشاء نص برمجي لـ "جداول بيانات Google"
• كيفية التنقّل في محرِّر "برمجة تطبيقات Google"
• كيفية إنشاء وحدات ماكرو وتعديلها
• كيفية إنشاء أول دالة مخصّصة في "جداول بيانات Google"

المتطلبات

• معرفة أساسية بلغة JavaScript
• معرفة أساسية بـ جداول بيانات Google
• إمكانية قراءة ترميز A1 في "جداول بيانات Google"

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

لقد انتهيت من المقدمات. انتقِل إلى القسم التالي لبدء العمل باستخدام وحدات الماكرو.

3- إنشاء وحدة ماكرو في "جداول بيانات Google"

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

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

قبل البدء

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

تم وضع نسخة من جدول البيانات النموذجي لتستخدمها في مجلد Google Drive باسم "نسخة من أفضل 10 أفلام من حيث الأرباح (2018)".

إنشاء وحدة ماكرو

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

1. انقر على الخلية A1 لوضع المؤشر في الصف. هذا هو صف العناوين.
2. في القائمة، اختَر الإضافات > وحدات الماكرو > تسجيل وحدات الماكرو.

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

3. في مربّع حوار "وحدة الماكرو"، اختَر مرجع نسبي.

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

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

4. اختَر الصف 1.

5. أعِد تلوين لون التعبئة للصف العلوي من الأبيض إلى الأرجواني الداكن 3.

6. غيِّر لون النص في الصف العلوي من الأسود إلى الأبيض.

7. لتنسيق النص بالخط العريض، اضغط على Ctrl+B (أو Cmd+B على نظام التشغيل macOS).
8. لتجميد الصف العلوي، انقر على عرض > تجميد > صف واحد.

9. انقر على حفظ في مربّع حوار وحدة الماكرو. يطلب منك مربّع حوار جديد تسمية وحدة الماكرو. أدخِل الاسم "العنوان" وانقر على حفظ.

باستخدام واجهة مستخدم "جداول بيانات Google"، أنشأتَ ماكرو مخصّصًا لتنسيق العناوين.

تفعيل وحدة الماكرو

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

1. لإنشاء ورقة، انقر على "إضافة ورقة" .

2. في ورقة البيانات الجديدة، أضِف بعض النصوص إلى النطاق A1:C2. يمكنك الاطّلاع على أمثلة الإدخالات أدناه:

3. ميِّز الصف الأول.

4. لتطبيق الماكرو على المنطقة المحدّدة، انقر على الإضافات> وحدات الماكرو> العنوان.
5. امنح الإذن بتشغيل الماكرو باتّباع التعليمات الظاهرة على الشاشة.

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

6. كرِّر الخطوة 4 لتشغيل وحدة الماكرو مرة أخرى (يؤدي منح الإذن إلى إيقاف التنفيذ الأول).

تهانينا، لقد تعلّمت كيفية تطبيق وحدات الماكرو في "جداول بيانات Google". يجب أن يظهر جدول البيانات على النحو التالي:

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

4. وحدات الماكرو في محرِّر النصوص البرمجية

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

مُحرِّر النصوص البرمجية

بعد إنشاء ماكرو، يمكنك الاطّلاع على رمزه. لعرض نص وحدة الماكرو البرمجي، انقر على الإضافات > برمجة تطبيقات Google لفتح محرِّر الرموز البرمجية في المتصفّح لـ "برمجة تطبيقات Google".

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

ملاحظة: إنّ وحدات الماكرو والنصوص البرمجية التي تنشئها في هذا الدرس العملي المبرمَج تكون مرفقة بملف "جداول بيانات Google" الذي تعمل عليه، ويمكن الوصول إليها في أي وقت من قائمة الإضافات > برمجة تطبيقات Google في "جداول بيانات Google". تُعرف النصوص البرمجية المرتبطة بجدول بيانات Google على هذا النحو باسم نصوص برمجية مرتبطة بحاوية.

تحليل macros.gs

راجِع النص البرمجي الحالي. أنشأت "جداول بيانات Google" ملف النص البرمجي macros.gs عند تسجيل وحدة الماكرو Header، وملأته بدالة "برمجة تطبيقات Google" المقابلة التي تحمل الاسم Header. عند تفعيل الماكرو Header، تنفّذ "جداول بيانات Google" هذه الدالة.

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

السطر الأول هو تعليق توضيحي يؤثر في التفويض:

/** @OnlyCurrentDoc */

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

لفهم الطريقة التي تمثّل بها "برمجة تطبيقات Google" تعليمات الماكرو، يمكنك الاطّلاع على الدالة:

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
};

يتم تنفيذ هذا الرمز عند تفعيل ماكرو Header. بعد function، تحدّد التصنيف Header() اسم الدالة ومَعلماتها. يجب معرفة أنّ Header() لا تتطلّب أي مَعلمات لأنّ دوال الماكرو في "برمجة تطبيقات Google" لا تحتاج إلى مُدخلات. تحيط الأقواس المعقوفة دائمًا بنص الدالة في "برمجة تطبيقات Google".

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

var spreadsheet = SpreadsheetApp.getActive();

في هذا المثال، تعرض الدالة getActive() عنصرًا يمثّل ملف جدول البيانات النشط الحالي في "جداول بيانات Google" وتضبطه على المتغيّر الجديد spreadsheet.

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

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

spreadsheet.getActiveRangeList().setBackground('#4c1130')
.setFontColor('#ffffff')
.setFontWeight('bold');

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

• تعرض getActiveRangeList() RangeList النشط حاليًا في spreadsheet. في هذه الحالة، يكون هذا السطر هو ببساطة السطر الأول الذي تم تنشيطه في السطر السابق.
• تغيّر كلّ من الطريقتَين setBackground(color) وsetFontColor(color) سمات الألوان للخلايا في النطاق النشط.
• setFontWeight(fontWeight) يضبط سُمك الخط للخلايا في النطاق النشط.

أخيرًا، يجمّد السطر الأخير الصف الأول من الماكرو:

spreadsheet.getActiveSheet().setFrozenRows(1);

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

يركّز القسم التالي على تعديل رمز الدالة Header() لتوضيح كيفية استخدام "محرّر النصوص البرمجية" لتخصيص وحدات الماكرو بشكلٍ أكبر.

تخصيص وحدات الماكرو باستخدام "برمجة تطبيقات Google"

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

تغيير الخلايا المتأثرة

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

1. في محرِّر النصوص البرمجية، استبدِل sheet.getMaxColumns() بـ 10. يؤدي هذا التعديل إلى تغيير نطاق الخلايا التي يؤثّر فيها الماكرو في جدول البيانات.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
    /* sheet.getMaxColumns() replaced with 10.*/
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

2. لحفظ النص، انقر على "حفظ" .
3. لإعادة تسمية مشروعك، أدخِل "وحدات الماكرو والدوال المخصّصة" كاسم جديد للمشروع وانقر على إعادة التسمية.
4. لإنشاء ورقة، انقر على "إضافة ورقة" في "جداول بيانات Google".

5. في محرّر النصوص البرمجية، اختَر Header من قائمة الدوال، ثم انقر على تشغيل.

في ورقة البيانات الجديدة، من المفترض أن تظهر لك النتيجة التالية:

من خلال تعديل النطاق النشط أو المستهدَف، لن يؤثّر الماكرو الآن إلا في جزء من الصف الأول. تتضمّن العديد من طرق Apps Script نطاقًا أو ترميز A1 كمَعلمة لتحديد الخلايا التي سيتم تنفيذ الإجراء عليها.

بعد ذلك، سنتعرّف على كيفية تخصيص ألوان وحدات الماكرو.

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

لمساعدتك في تصميم نظام الألوان لوحدات الماكرو أو العناصر الأخرى في "جداول بيانات Google"، يمكن لبرمجة التطبيقات تعديل لون التعبئة أو لون النص لنطاق معيّن. اتّبِع التعليمات التالية لمعرفة كيفية تخصيص ألوان الماكرو.

تركّز هذه التعليمات على تغيير لون خلفية الماكرو:

1. في "جداول بيانات Google"، ارجع إلى الورقة التي تحتوي على البيانات الأصلية (الورقة 1).
2. انقر على الصف الأول لتحديده.
3. في "محرّر النصوص البرمجية"، استبدِل لون الخلفية #4c1130 بـ #afeeee. تمثّل هذه القيم ألوانًا مختلفة باستخدام ترميز ثلاثي سداسي عشري.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
    /* #4c1130 replaced with #afeeee.*/
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

4. لحفظ النص، انقر على "حفظ" .
5. من قائمة الدوال، اختَر Header وانقر على تنفيذ.

في "جداول بيانات Google"، يتم إعادة تلوين خلفية أول 10 أعمدة في الصف الأول إلى لون فيروزي مخصّص:

من خلال تبديل ترميز الألوان السداسية العشرية في مَعلمات setBackground(color) من #4c1130 (أرجواني داكن 3) إلى #afeeee (فيروزي شاحب، وهو خيار لا يمكن الوصول إليه في قائمة الألوان التلقائية في "جداول بيانات Google")، يمكنك تغيير سمة اللون الخلفي لوحدة الماكرو.

لقد عدّلت الآن مجموعة ألوان الخلفية التي حدّدتها وحدة الماكرو. إذا أردت تغيير لون النص أيضًا، غيِّر رمز اللون الثاني.

1. في "جداول بيانات Google"، انقر على الصف الأول للتأكّد من أنّه لا يزال مميّزًا.
2. في "محرّر النصوص البرمجية"، استبدِل لون الخط #ffffff بـ #191970. يؤدي ذلك إلى ضبط لون الخط على الأزرق الداكن.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
  .setFontColor('#191970')/* #ffffff replaced with #191970.*/
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

3. لحفظ النص، انقر على "حفظ" .
4. من قائمة الدوال، اختَر Header وانقر على تنفيذ.

ارجع إلى "جداول بيانات Google" وستلاحظ أنّ لون نص صف العناوين أصبح أزرق داكنًا.

بعد أن تعرّفت على كيفية تسجيل وحدات الماكرو كإجراءات في "جداول بيانات Google" باستخدام رمز "برمجة تطبيقات Google"، في القسم التالي، يمكنك الاطّلاع على طريقة أخرى يمكن أن تساعدك بها "برمجة تطبيقات Google" في العمل مع "جداول بيانات Google": الدوال المخصّصة.

5- كتابة الرمز البرمجي الأول: الدوال المخصّصة

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

يوضّح لك هذا القسم كيفية إنشاء دالة مخصّصة في "برمجة تطبيقات Google" لإجراء عملية تحويل عملة.

إنشاء ملف نص برمجي

باستخدام جدول البيانات ومشروع النص البرمجي نفسهما من قسم "وحدات الماكرو"، اتّبِع هذه التعليمات للتعرّف على كيفية إنشاء نص برمجي جديد (يمكنك استخدامه في النهاية لإنشاء دالتك المخصّصة الأولى):

1. لإنشاء ملف "برمجة تطبيقات Google"، ارجع إلى محرِّر النصوص البرمجية.
2. بجانب الملفات، انقر على "إضافة ملف" > نص برمجي.
3. أدخِل اسمًا لملف البرنامج النصي الجديد customFunctions واضغط على Enter. (تضيف "برمجة التطبيقات" تلقائيًا اللاحقة .gs إلى اسم ملف البرنامج النصي).

تظهر علامة تبويب جديدة باسم customFunctions.gs ضمن أداة التعديل.

بعد إنشاء نص برمجي مخصّص للدوال المخصّصة، يمكنك ملؤه بالرمز.

تحويل الدولار الأمريكي إلى فرنك سويسري

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

قبل أن تتمكّن من كتابة دالتك المخصّصة الأولى، عليك تعديل مجموعة البيانات للسماح للدالة بعرض ناتج مناسب. ولإجراء ذلك:

1. في "جداول بيانات Google"، انقر بزر الماوس الأيمن على العمود H.
2. في القائمة الناتجة، انقر على إدراج عمود واحد على اليسار.

3. أضِف التصنيف "Worldwide_Gross (Swiss francs)" إلى العمود في الخلية I1.

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

4. في customFunctions.gs، استبدِل الرمز الخاص بـ myFunction() بالرمز التالي:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The converted total of Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

هذا هو الرمز الذي سيحوّل الدولارات الأمريكية إلى فرنكات سويسرية. جرِّب التعليمات أدناه، واطّلِع على كيفية تنفيذ دالة مخصّصة في جداول بيانات Google.

5. لحفظ النص، انقر على "حفظ" .
6. في "جداول بيانات Google"، اختَر الخلية I2.
7. في شريط الدوال، أدخِل =USDTOCHF(H2).

لتطبيق الصيغة على بقية الخلايا في العمود، اتّبِع الخطوات التالية:

8. حرِّك مؤشر الماوس إلى الزاوية اليمنى السفلية من الخلية I2 وانقر على المربّع الأزرق الصغير (يجب أن يتحوّل المؤشر إلى عند الإشارة إلى المربّع الأزرق).
9. اسحب المربّع الأزرق للأسفل لتمييز النطاق I3:I11.

يسرد العمود I الآن عمليات تحويل قيم الدولار الأمريكي في العمود H إلى الفرنك السويسري.

تهانينا، لقد أنشأت أول دالة مخصّصة. يوضّح القسم التالي الرمز الذي يتضمّنه USDTOCHF().

تحليل USDTOCHF()

توضّح التعليقات الأولية الغرض من الرمز البرمجي:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */

يتم استخدام مجموعات التعليقات هذه بشكل متكرر في البرمجة لشرح وظائف الدوال.

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

من خلال التعليقات التوضيحية، تستخدم Apps Script JSDoc لمساعدتك في توثيق وإنشاء تلميحات الإكمال التلقائي للرمز البرمجي. يمكنك الاطّلاع أدناه على كيفية مساعدة كل تعليق توضيحي مستخدَم في USDTOCHF() في عملية تطوير "برمجة تطبيقات Google":

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

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

بعد ذلك، ركِّز على الرمز في الدالة USDTOCHF():

function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

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

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

دمج بادئة سلسلة

لنفترض أنّك تريد أن يتضمّن الناتج الرقمي للدالة USDTOCHF() البادئة CHF الخاصة بالفرنك السويسري. يمكنك إجراء ذلك باستخدام "برمجة تطبيقات Google" من خلال استخدام عامل التسلسل (+), كما هو موضّح في التعليمات التالية:

1. في محرّر النصوص البرمجية، عدِّل التعليق التوضيحي @return لعرض السلسلة بدلاً من الرقم.
2. تغيير return swissFrancs إلى return 'CHF' + swissFrancs

يضيف عامل التشغيل + السلسلة CHF إلى بداية القيمة الواردة في swissFrancs. يجب أن تبدو التعليمات البرمجية الآن على النحو التالي:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {string} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99;
  return 'CHF' + swissFrancs;
}

3. لحفظ النص، انقر على "حفظ" .

يتم الآن إضافة سلسلة الفرنك السويسري إلى بداية قيم العمود I:

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

متقدّم: استرجاع البيانات الخارجية

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

يمكنك استخدام رمز مثل الرمز أدناه للحصول على سعر الصرف الحالي من الفرنك السويسري إلى الدولار الأمريكي:

function USDTOCHF(dollars){
  // Gets a cache that is common to all users of the script.
  var cache = CacheService.getScriptCache();

  // Accesses the memory location (rates.CHF) of the script cache.
  var rate = cache.get('rates.CHF');

  // If a cache miss occurs, the program fetches the current
  // CHF rate from an API and stores the rate in the cache
  // for later convenience.
  if (!rate) {
    var response =
UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');
    var result = JSON.parse(response.getContentText());
    rate = result.rates.CHF;
    cache.put('rates.CHF', rate);
  }
  // Converts dollars to CHF according to the latest rate.
  var swissFrancs = dollars * rate;
  // Returns the CHF value.
  return 'CHF' + swissFrancs;
}

يجلب هذا الرمز سعر الصرف الحالي من خادم معلومات مالية باستخدام واجهة برمجة تطبيقات لسعر الصرف تابعة لجهة خارجية. يتم ذلك باستخدام خدمات "برمجة تطبيقات Google"، مثل UrlFetchApp و CacheService. لا تتناول هذه التجربة العملية هذه المفاهيم المتقدّمة، ولكن يمكنك البدء في استكشاف تنوّع استخدامات "برمجة تطبيقات Google" لتنفيذ المهام المعقّدة آليًا في "جداول بيانات Google".

إرشادات الدوال المخصّصة

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

• لا تنشئ دوال مخصّصة تتطلّب إذن المستخدم. بدلاً من ذلك، يمكنك إنشاء دوال مخصّصة لتنفيذ مهام أبسط، مثل عمليات حسابية على عيّنات البيانات وتعديل النصوص وما إلى ذلك. انتقِل إلى استخدام خدمات "برمجة تطبيقات Google".
• لا تسمِّ دالة مخصّصة بالاسم نفسه كدالة مضمّنة أخرى، أو تنهِ الاسم بشرطة سفلية. راجِع إرشادات التسمية.
• لا تمرِّر وسيطات متغيرة إلى الدوال المخصّصة. يمكنك فقط تمرير قيم ثابتة إلى الدوال المخصّصة كوسيطات. سيؤدي تمرير وسيطات متغيرة، مثل نتيجة =RAND()، إلى إيقاف الدالة المخصّصة. اطّلِع على إرشادات الوسيطات.
• لا تنشئ دوالاً تستغرق أكثر من 30 ثانية لإكمالها. إذا استغرق الأمر وقتًا أطول، سيحدث خطأ، لذا يجب أن يكون رمز الدالة بسيطًا ومحدود النطاق. من الأفضل أن تكون العمليات الحسابية التي يتم إجراؤها في الدوال المخصّصة بسيطة قدر الإمكان. اطّلِع على إرشادات حول قيم الإرجاع.

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

6. الخاتمة

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

هل كان هذا الدرس التطبيقي العملي مفيدًا؟

نعم لا

المواضيع التي تناولناها

• المفاهيم الأساسية في "برمجة تطبيقات Google"
• كيفية التنقّل في محرِّر النصوص البرمجية
• كيفية إنشاء وحدات ماكرو في "جداول بيانات Google" وتعديلها
• كيفية إنشاء دوال مخصّصة في "جداول بيانات Google"

المصطلحات الرئيسية

• المرجع المطلق: هو إعداد لتسجيل وحدات الماكرو يحدّد أنّه يتم تطبيق إجراءات الماكرو المسجَّلة على الخلايا المستخدَمة في التسجيل بالضبط.
• نشط (الحالة): يشير إلى أنّ جدول البيانات أو الورقة أو النطاق أو الخلية المحدّدة هي ما يعرضه حاليًا مستخدم جدول البيانات أو يميّزه.
• برمجة تطبيقات Google: هي منصة لتطوير التطبيقات بسرعة استنادًا إلى JavaScript، ما يتيح سرعة وسهولة توسيع تطبيقات Google Workspace وتنفيذ المهام آليًا.
• التفويض: هي عملية منح المستخدم أذونات لـ "برمجة التطبيقات" من أجل الوصول إلى بيانات المستخدم في خدمات Google ذات الصلة أو اتّخاذ إجراءات أخرى نيابةً عن المستخدم.
• البرنامج النصي المرتبط بالحاوية: أي برنامج نصي مرتبط بمستند Google Workspace وتم إنشاؤه منه، مثل جدول بيانات Google أو مستند Google
• الدوال المخصّصة: هي صيغ يحدّدها المستخدم في "برمجة التطبيقات" وتُستخدم في جداول البيانات لإجراء عمليات بسيطة.
• JSDoc: هي لغة ترميز تُستخدَم لكتابة ملاحظات توضيحية على ملفات المصدر المستندة إلى JavaScript.
• التعليمات الكلية: هي اختصار لعبارة "التعليمات الكلية". سلسلة مسجّلة من الإجراءات في "جداول بيانات Google" يمكنك تكرارها باستخدام عنصر قائمة أو مفتاح اختصار
• تسلسل استدعاء الدوال: عبارة عن أسلوب برمجة لاستدعاء عدة دوال في كائن واحد، مع الاعتماد على حقيقة أنّ كل استدعاء دالة يعرض الكائن.
• النطاق: مجموعة من خلية واحدة أو أكثر من الخلايا المتجاورة في ورقة.
• المرجع النسبي: هو إعداد لتسجيل وحدات الماكرو يحدّد أنّه يتم تطبيق إجراءات الماكرو المسجَّلة على الخلايا ذات الصلة بتحديد الخلية الحالية.
• محرِّر النصوص البرمجية: هو أداة تعديل الرموز البرمجية في المتصفّح لخدمة "برمجة تطبيقات Google".
• ورقة: صفحة واحدة من جدول بيانات (مشابهة لمصنفات Microsoft Excel). يُستخدم أحيانًا للإشارة إلى ملف "جداول بيانات Google" ضِمن Google Drive.
• SpreadsheetApp: تعمل هذه الفئة كفئة أصلية لخدمة "جداول بيانات Google" وتوفّر نقطة بداية للرمز الذي يقرأ بيانات "جداول بيانات Google" أو يعالجها.
• جدول البيانات: ملف "جداول بيانات Google" موجود في Google Drive.
• خدمة جداول البيانات: هي خدمة في "برمجة تطبيقات Google" تتيح للبرامج النصية إنشاء ملفات "جداول بيانات Google" والوصول إليها وتعديلها.

يمكنك الاطّلاع على مزيد من المعلومات عن Apps Script في مستندات Apps Script.

الخطوات التالية

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

يمكنك العثور على الدرس التالي في جداول البيانات وأوراق البيانات والنطاقات.