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

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

للاطّلاع على أمثلة على الدوال المخصّصة، راجِع البرامج التعليمية التالية:

• حساب سعر بيع السلع المخفّضة (دليل البدء السريع)
• حساب خصم على الأسعار المتدرّجة
• حساب مسافة القيادة وتحويل الأمتار إلى أميال
• تلخيص البيانات من أوراق متعددة
• التحقّق من صحة البيانات باستخدام وكيل الذكاء الاصطناعي في حزمة تطوير الذكاء الاصطناعي ونموذج Gemini

الخطوات الأولى

يتم إنشاء الدوال المخصّصة باستخدام JavaScript العادية. إذا كنت تستخدم JavaScript لأول مرة، تقدّم Codecademy دورة تدريبية للمبتدئين. لم يتم تطوير هذه الدورة التدريبية من قِبل 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 وليس لديك وقت لتعلّمها، اطّلِع على متجر إضافات Google Workspace لـ معرفة ما إذا كان مستخدم آخر قد أنشأ الدالة المخصّصة التي تحتاج إليها.

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

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

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

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

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

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

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

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

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

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

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

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

تسمية الدوال

بالإضافة إلى الاصطلاحات العادية لتسمية دوال JavaScript، يُرجى العِلم بما يلي:

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

الوسيطات

على غرار الدالة المضمّنة، يمكن أن تأخذ الدالة المخصّصة وسيطات كقيم إدخال:

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

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

  
  

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

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

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

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

• إذا عرضت دالة مخصّصة قيمة، ستظهر القيمة في الخلية التي تم استدعاء الدالة منها.
• إذا عرضت دالة مخصّصة صفيفًا ثنائي الأبعاد من القيم، ستنتقل القيم إلى الخلايا المجاورة طالما أنّ هذه الخلايا فارغة. إذا كان ذلك سيؤدي إلى استبدال الصفيف لمحتويات الخلايا الحالية، ستعرض الدالة المخصّصة خطأ بدلاً من ذلك. للاطّلاع على مثال، راجِع القسم حول تحسين الدوال المخصّصة.
• لا يمكن أن تؤثر الدالة المخصّصة في خلايا أخرى غير الخلايا التي تعرض قيمة لها. بعبارة أخرى، لا يمكن أن تعدّل الدالة المخصّصة خلايا عشوائية، بل الخلايا التي يتم استدعاؤها منها والخلايا المجاورة لها فقط. لتعديل خلايا عشوائية، استخدِم قائمة مخصّصة لتشغيل دالة بدلاً من ذلك.
• يجب أن يعرض استدعاء الدالة المخصّصة نتيجة في غضون 30 ثانية. إذا لم يحدث ذلك، ستعرض الخلية #ERROR! وستكون ملاحظة الخلية Exceeded maximum execution time (line 0).

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

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

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

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

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

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

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

إعدادات متقدمة

يتناول هذا القسم مواضيع متقدّمة حول الدوال المخصّصة.

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

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

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

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

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

مشاركة الدوال المخصّصة

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

• انقر على الإضافات > برمجة تطبيقات 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 على الصفيف ثنائي الأبعاد لـ cells للحصول على كل صف، ثم يستخدم map مرة أخرى لكل صف لعرض ضعف قيمة كل خلية. ويعرض صفيفًا ثنائي الأبعاد يحتوي على النتائج. بهذه الطريقة، يمكنك استدعاء DOUBLE مرة واحدة فقط، ولكن يمكنك حسابها لعدد كبير من الخلايا في آنٍ واحد، كما هو موضّح في لقطة الشاشة التالية. يمكنك تحقيق النتيجة نفسها باستخدام عبارات if متداخلة بدلاً من استدعاء map.

وبالمثل، تجلب الدالة المخصّصة التالية المحتوى المباشر من الإنترنت بكفاءة وتستخدم صفيفًا ثنائي الأبعاد لعرض عمودَين من النتائج باستخدام طلب استدعاء دالة واحد فقط. إذا كانت كل خلية تتطلّب طلب استدعاء دالة خاصًا بها، ستستغرق العملية وقتًا أطول بكثير، لأنّ خادم "برمجة تطبيقات Google" سيضطر إلى تنزيل خلاصة 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;
}

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