أساسيات برمجة التطبيقات مع جداول بيانات Google رقم 1: وحدات الماكرو &amp؛ الوظائف المخصصة

1. مرحبًا بك في برمجة التطبيقات

ما المقصود ببرمجة التطبيقات؟

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

تتضمن ميزات برمجة التطبيقات ما يلي:

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

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

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

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

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

ما ستتعرَّف عليه

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

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

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

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

2. مقدمة

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

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

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

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

ما ستتعرَّف عليه

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

الأشياء التي تحتاج إليها

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

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

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

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

قبل البدء

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

5b8aded1bb349ecf.png

يتم وضع نسخة من مثال جدول البيانات لك لتستخدِمه في مجلد Google Drive الخاص بك وتسميته &نسخة من أهم 10 أفلام من أعلى إجمالي (2018).

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

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

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

بعد بدء التسجيل، يتذكر تطبيق "جداول بيانات Google" كل إجراء تتخذه في جدول البيانات: تمييز الخلايا وإضافة البيانات والتبديل إلى أوراق مختلفة والتنسيق وما إلى ذلك. تصبح هذه الإجراءات "script&#39؛ والتي تكرر بعد حفظ وحدة الماكرو وتفعيلها لاحقًا.

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

c59f2f12317352d2.gif

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

1d782ee30c66a02b.gif

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

f7e7abaf76e338c7.png

  1. تغيير لون النص في الصف العلوي من اللون الأسود إلى الأبيض.

d5e630acbe83148.png

  1. لجعل النص غامقًا، اضغط على Ctrl+B (أو Cmd+B على نظام التشغيل macOS).
  2. لتجميد الصف العلوي، اختَر عرض &gt؛ تجميد &gt؛ صف واحد.

97cb244ffebe8953.png

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

b4610a54340da518.gif

باستخدام واجهة مستخدم "جداول بيانات Google"، يمكنك استخدام وحدة ماكرو لتخصيص عناوين العناوين.

4ed7fbed18ea3681.png

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

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

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

927c012b4e11475b.png

  1. في الورقة الجديدة، أضِف نصًا إلى A1:C2. يمكنك اتباع التعليمات المذكورة أدناه:

c3aadaef52a609bf.png

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

cfe36fcf833d0bd7.gif

  1. لتطبيق وحدة الماكرو على المنطقة المحدّدة، انقر على الإضافات&gt؛ وحدات الماكرو&gt؛ العنوان.
  2. تفويض وحدة الماكرو باتّباع التعليمات الظاهرة على الشاشة.
  1. كرِّر الخطوة 4 لتشغيل وحدة الماكرو مرة أخرى (يؤدي ذلك إلى إيقاف التنفيذ الأول).

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

7c7130a4a697bd92.png

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

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

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

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

الآن وبعد أن أنشأت ماكرو، يمكنك إلقاء نظرة على الرمز. لعرض النص البرمجي لماكرو، انقر على الإضافات&gt؛ برمجة التطبيقات لفتح محرر رموز المتصفح لبرمجة التطبيقات.

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

تحليل macro.gs

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

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

5d653a69a0897adf.png

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

/** @OnlyCurrentDoc */

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

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

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() لا تتطلب أي معلمات، حيث إن وظائف الماكرو في "برمجة التطبيقات" لا تحتاج إلى إدخالات. وتتضمن الأقواس دائمًا نص الدالة في برمجة التطبيقات.

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

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

وأخيرًا، يعمل السطر الأخير على تجميد الصف الأول من وحدة الماكرو:

spreadsheet.getActiveSheet().setFrozenRows(1);

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

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

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

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

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

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

  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);
}
  1. لحفظ النص البرمجي، انقر على رمز الحفظ تصدٍّ للكرة.
  2. لإعادة تسمية المشروع، أدخِل &quot؛وحدات الماكرو والدوال المخصصة&;؛ كاسم مشروع جديد، وانقر على إعادة تسمية.
  3. لإنشاء ورقة، انقر على "إضافة جدول بيانات" 9c9b0c19bf317e7f.png في "جداول بيانات Google".

927c012b4e11475b.png

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

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

8a58ba02535b2b9c.png

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

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

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

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

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

  1. في "جداول بيانات Google"، انتقِل مرة أخرى إلى الورقة التي تحتوي على البيانات الأصلية (الورقة 1).
  2. انقر على الصف الأول لتمييزه.
  3. في محرِّر النص البرمجي، استخدِم #afeeee بدلاً من لون الخلفية #4c1130. تمثل هذه القيم ألوانًا مختلفة باستخدام الإضافة السداسية الثلاثية.
/** @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);
}
  1. لحفظ النص البرمجي، انقر على رمز الحفظ تصدٍّ للكرة.
  2. من قائمة الدوال، اختَر Header وانقر على تشغيل.

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

BBD26f7c8e35039.png

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

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

  1. في جداول البيانات، انقر على الصف الأول للتأكد من أنه لا يزال محددًا.
  2. في محرِّر النص البرمجي، استخدِم #191970 بدلاً من لون الخط #ffffff. ويؤدي ذلك إلى ضبط وحدة الماكرو على لون خط أزرق داكن.
/** @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);
}
  1. لحفظ النص البرمجي، انقر على رمز الحفظ تصدٍّ للكرة.
  2. من قائمة الدوال، اختَر Header وانقر على تشغيل.

ارجع إلى جداول البيانات لمشاهدة لون النص لصف العناوين الآن باللون الأزرق الداكن.

2eaf2fb4879e1b36.png

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

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

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

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

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

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

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

تظهر علامة تبويب جديدة تُسمى customFunctions.gs في أداة التعديل.

بعد أن أنشأت نصًا برمجيًا للدوال المخصصة على وجه التحديد، يمكنك تعبئته برمز.

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

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

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

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

fc1421cb1c456e52.gif

  1. تصنيف العمود "Worldwide_Gross (السويسرا السويسرية)" في الخلية I1

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

  1. في 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;
}

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

  1. لحفظ النص البرمجي، انقر على رمز الحفظ تصدٍّ للكرة.
  2. في "جداول بيانات Google"، اختَر الخلية I2.
  3. في شريط الوظائف، أدخِل =USDTOCHF(H2).

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

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

.3cf46560d6cea0de.gif

يعرض العمود 1 الآن الإحالات الناجحة بالفرنك السويسري للقيم بالدولار الأمريكي في العمود H.

7fc06b3d7e3e2a9.png

تهانينا، لقد أنشأت أول وظيفة مُخصَّصة لك. يوضّح القسم التالي الرمز الذي يتألف من 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
 */

غالبًا ما تُستخدم مثل هذه التعليقات في البرمجة لشرح ما تؤديه الوظائف.

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

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

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

d8680ab6efae97ac.gif

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

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

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

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

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

ربط بادئة سلسلة

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

  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;
}
  1. لحفظ النص البرمجي، انقر على رمز الحفظ تصدٍّ للكرة.

تبدأ سلسلة الفرنك السويسري الآن قِيَم العمود 1:

20e4bfb7f0a994ea.png

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

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

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

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

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;
}

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

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

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

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

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

6- الخلاصة

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

هل وجدت هذا الدرس التطبيقي مفيدًا؟

نعم لا

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

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

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

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

ابحث عن الدرس التطبيقي التالي في جداول البيانات وجداول البيانات والنطاقات.