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

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

البدء

يتم إنشاء الدوال المخصّصة باستخدام JavaScript عادي. إذا كنت مبتدئًا في مجال JavaScript، تقدّم لك Codecademy دورة تدريبية رائعة للمبتدئين. (ملاحظة: لم يتم تطوير هذه الدورة التدريبية من قِبل Google، وهي غير مرتبطة بشركة Google.)

في ما يلي دالة مخصّصة بسيطة، اسمها DOUBLE، والتي تضرب قيمة الإدخال في 2:

/**
 * Multiplies an input value by 2.
 * @param {number} input The number to double.
 * @return The input multiplied by 2.
 * @customfunction
*/
function DOUBLE(input) {
  return input * 2;
}

إذا كنت لا تعرف كيفية كتابة JavaScript وليس لديك الوقت للتعلّم، يمكنك الاطّلاع على متجر الإضافات لمعرفة ما إذا كان مستخدم آخر قد أنشأ الوظيفة المخصّصة التي تريدها.

إنشاء دالة مخصصة

لكتابة دالة مخصصة:

1. أنشئ جدول بيانات أو افتحه في "جداول بيانات Google".
2. اختر عنصر القائمة الإضافات > برمجة التطبيقات.
3. احذف أي رمز في أداة تعديل النصوص البرمجية. بالنسبة إلى دالة DOUBLE أعلاه، ما عليك سوى نسخ الرمز ولصقه في محرر البرنامج النصي.
4. في أعلى الصفحة، انقر على "حفظ" .

يمكنك الآن استخدام الدالة المخصّصة.

الحصول على دالة مخصصة من Google Workspace Marketplace

توفر Google Workspace Marketplace العديد من الدوال المخصّصة كإضافات لجداول بيانات Google. لاستخدام هذه الإضافات أو استكشافها:

1. أنشئ جدول بيانات أو افتحه في "جداول بيانات Google".
2. في أعلى الصفحة، انقر على الإضافات > الحصول على إضافات.
3. بعد فتح Google Workspace Marketplace، انقر على مربّع البحث في أعلى يسار الصفحة.
4. اكتب "دالة مخصّصة" واضغط على مفتاح Enter.
5. إذا عثرت على إضافة وظائف مخصّصة تهمّك، انقر على تثبيت لتثبيتها.
6. قد يخبرك مربع حوار أن الإضافة تتطلب إذنًا. إذا كان الأمر كذلك، فاقرأ الإشعار بعناية، ثم انقر على السماح.
7. تصبح الإضافة متاحة في جدول البيانات. لاستخدام الإضافة في جدول بيانات مختلف، افتح جدول البيانات الآخر، وانقر في أعلى الصفحة على الإضافات > إدارة الإضافات. ابحث عن الإضافة التي تريد استخدامها وانقر على الخيارات > استخدام في هذا المستند.

استخدام دالة مخصصة

بعد كتابة دالة مخصّصة أو تثبيت دالة من Google Workspace Marketplace، سيصبح استخدامها بنفس سهولة استخدام الدالة المضمّنة:

1. انقر على الخلية التي تريد استخدام الدالة فيها.
2. اكتب علامة يساوي (=) متبوعة باسم الدالة وأي قيمة إدخال، على سبيل المثال، =DOUBLE(A1)، واضغط على Enter.
3. ستعرض الخلية Loading... لحظيًا، ثم تعرض النتيجة.

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

قبل كتابة الدالة المخصصة، هناك بعض الإرشادات التي يجب معرفتها.

التسمية

بالإضافة إلى الاصطلاحات القياسية لتسمية دوال JavaScript، كن على دراية بما يلي:

• يجب أن يكون اسم الدالة المخصصة مختلفًا عن أسماء الدوال المضمَّنة، مثل SUM().
• لا يمكن أن ينتهي اسم الدالة المخصّصة بشرطة سفلية (_)، تشير إلى دالة خاصة في "برمجة التطبيقات".
• يجب الإعلان عن اسم الدالة المخصّصة باستخدام البنية function myFunction()، وليس var myFunction = new Function().
• الكتابة بالأحرف الكبيرة غير مهمة، على الرغم من أن أسماء دوال جداول البيانات عادةً ما تكون بأحرف كبيرة.

الوسيطات

مثل الدالة المضمّنة، يمكن للدالة المخصّصة استخدام الوسيطات كقيم إدخال:

• إذا استدعيت الدالة مع مرجع إلى خلية واحدة كوسيطة (مثل =DOUBLE(A1))، ستكون الوسيطة هي قيمة الخلية.

• إذا استدعيت الدالة مع مرجع إلى نطاق من الخلايا كوسيطة (مثل =DOUBLE(A1:B10))، ستكون الوسيطة صفيفًا ثنائي الأبعاد لقيم الخلايا. على سبيل المثال، في لقطة الشاشة أدناه، يتم تفسير الوسيطات في =DOUBLE(A1:B2) عن طريق "برمجة التطبيقات" على أنّها double([[1,3],[2,4]]). لاحظ أنه يجب تعديل نموذج الرمز الخاص بـ DOUBLE من أعلاه لقبول صفيف كإدخال.

  
  

• يجب أن تكون وسيطات الدوال المخصّصة محدّدة. وهذا يعني أنّه لا يُسمح باستخدام دوال جداول البيانات المضمّنة التي تعرض نتيجة مختلفة في كل مرة يتم فيها إجراء الحساب، مثل NOW() أو RAND()، كوسيطات لدالة مخصّصة. إذا حاولت دالة مخصّصة عرض قيمة استنادًا إلى إحدى هذه الدوال المضمنة المتغيرة، سيتم عرضها Loading... إلى أجل غير مسمى.

القيم المعروضة

يجب أن ترجع كل دالة مخصصة قيمة لعرضها، مثل:

• إذا عرضت دالة مخصصة قيمةً، يتم عرض القيمة في الخلية التي تم استدعاء الدالة منها.
• إذا كانت الدالة المخصصة تعرض صفيفًا ثنائي الأبعاد من القيم، فتتجاوز القيم إلى الخلايا المجاورة طالما أن هذه الخلايا فارغة. إذا كان هذا سيؤدي إلى استبدال الصفيف بمحتويات الخلية الحالية، ستعرض الدالة المخصصة خطأ بدلاً من ذلك. للحصول على مثال، راجِع القسم الذي يتناول تحسين الدوال المخصّصة.
• لا يمكن للدالة المخصصة أن تؤثر في الخلايا غير تلك التي تُرجع قيمة لها. بمعنى آخر، لا يمكن للدالة المخصّصة تعديل الخلايا العشوائية، بل فقط الخلايا التي يتم طلبها منها والخلايا المجاورة لها. لتعديل الخلايا العشوائية، استخدِم قائمة مخصّصة لتشغيل دالة بدلاً من ذلك.
• يجب أن يعود استدعاء الدالة المخصصة في غضون 30 ثانية. إذا لم يكن الأمر كذلك، ستعرض الخلية رسالة الخطأ: Internal error executing the custom function.

أنواع البيانات

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

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

الإكمال التلقائي

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

ستظهر الدوال المخصّصة في هذه القائمة إذا كان النص البرمجي الخاص بها يتضمّن علامة JsDoc @customfunction، كما في مثال DOUBLE() أدناه.

/**
 * Multiplies the input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return The input multiplied by 2.
 * @customfunction
 */
function DOUBLE(input) {
  return input * 2;
}

مزايا متقدّمة

استخدام خدمات "برمجة تطبيقات Google"

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

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

الخدمات المتوافقة	Notes
ذاكرة التخزين المؤقت	تعمل، ولكنها غير مفيدة بشكلٍ خاص في الدوال المخصّصة
HTML	يمكنه إنشاء ترميز HTML، ولكن لا يمكنه عرضه (نادرًا ما يكون مفيدًا)
JDBC
اللغة
قفل	تعمل، ولكنها غير مفيدة بشكلٍ خاص في الدوال المخصّصة
الخرائط	إمكانية حساب الاتجاهات، ولكن لا يمكن عرض الخرائط
المواقع	لا يحصل getUserProperties() إلا على سمات مالك جدول البيانات. لا يمكن لمحرّري جداول البيانات ضبط خصائص المستخدمين في دالة مخصّصة.
جدول البيانات	للقراءة فقط (يمكن استخدام معظم طرق get*()، ولكن ليس set*()). لا يمكن فتح جداول البيانات الأخرى (SpreadsheetApp.openById() أو SpreadsheetApp.openByUrl()).
جلب عنوان URL
برامج الخدمات
XML

إذا كانت الدالة المخصّصة تعرض رسالة الخطأ You do not have permission to call X service.، تتطلّب الخدمة إذنًا من المستخدم، وبالتالي لا يمكن استخدامها في دالة مخصّصة.

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

تتمّ مشاركة الأرباح

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

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

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

التحسين

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

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

على سبيل المثال، يمكن إعادة كتابة الدالة DOUBLE() الموضحة أعلاه لقبول خلية واحدة أو نطاق من الخلايا على النحو التالي:

/**
 * Multiplies the input value by 2.
 *
 * @param {number|Array<Array<number>>} input The value or range of cells
 *     to multiply.
 * @return The input multiplied by 2.
 * @customfunction
 */
function DOUBLE(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

يستخدم الأسلوب أعلاه الطريقة map لكائن Array في JavaScript لاستدعاء DOUBLE بشكل متكرر لكل قيمة في مصفوفة الخلايا الثنائية الأبعاد. وتعرض صفيفًا ثنائي الأبعاد يحتوي على النتائج. بهذه الطريقة، يمكنك استدعاء DOUBLE مرة واحدة فقط ولكن قم بحسابه لعدد كبير من الخلايا في وقت واحد، كما هو موضح في لقطة الشاشة أدناه. (يمكنك إنجاز الشيء نفسه باستخدام عبارات if المدمجة بدلاً من استدعاء map).

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

/**
 * Show the title and date for the first page of posts on the
 * Developer blog.
 *
 * @return Two columns of data representing posts on the
 *     Developer blog.
 * @customfunction
 */
function getBlogPosts() {
  var array = [];
  var url = 'https://gsuite-developers.googleblog.com/atom.xml';
  var xml = UrlFetchApp.fetch(url).getContentText();
  var document = XmlService.parse(xml);
  var root = document.getRootElement();
  var atom = XmlService.getNamespace('http://www.w3.org/2005/Atom');
  var entries = document.getRootElement().getChildren('entry', atom);
  for (var i = 0; i < entries.length; i++) {
    var title = entries[i].getChild('title', atom).getText();
    var date = entries[i].getChild('published', atom).getValue();
    array.push([title, date]);
  }
  return array;
}

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