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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

البدء

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

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

function DOUBLE(input) {
  return input * 2;
}

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

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

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

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

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

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

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

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

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

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

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

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

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

التسمية

بالإضافة إلى العبارات العادية لتسمية دوال JavaScript، يجب الانتباه إلى ما يلي:

  • ويجب أن يكون اسم الدالة المخصّصة مختلفًا عن أسماء الدوال المضمّنة، مثل SUM().
  • لا يمكن أن ينتهي اسم الدالة المخصصة بشرطة سفلية (_)، والتي تشير إلى دالة خاصة في"برمجة تطبيقات Google".
  • يجب تحديد اسم الدالة المخصّصة باستخدام البنية 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 " البيانات بتنسيقات مختلفة استنادًا إلى طبيعة البيانات. وعند استخدام هذه القيم في دوال مخصّصة، تتعامل "برمجة التطبيقات" معها على أنها نوع البيانات المناسب في JavaScript. فيما يلي الجوانب الأكثر شيوعًا للالتباس:

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

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

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

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

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

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

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

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

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

  • انقر على الإضافات > برمجة التطبيقات لفتح محرّر النص البرمجي، ثم انسخ نص النص البرمجي من جدول البيانات الأصلي والصقه في محرِّر النصوص البرمجية لجدول بيانات آخر.
  • أنشئ نسخة من جدول البيانات الذي يحتوي على الدالة المخصصة من خلال النقر على ملف &gt وإنشاء نسخة. عند نسخ جدول بيانات، يتم نسخ أي نصوص برمجية مرفقة به أيضًا. أي شخص لديه حق الوصول إلى جدول البيانات يمكنه نسخ النص البرمجي. (لا يمكن للمتعاونين الذين لديهم الإذن بالاطّلاع فقط فتح محرِّر النص البرمجي في جدول البيانات الأصلي. ومع ذلك، عندما ينشئ نسخة، يصبح هو مالك النسخة ويمكنه الاطّلاع على النص البرمجي.)
  • انشر النص البرمجي كإضافة في "جداول بيانات 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 من JavaScriptArray لاستدعاء 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;
}

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