البحث في الموقع

هذا هو المقال الأخير من سلسلة مقالات حول تعلم أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، يعلمك هذا المقال كيفية استخدام خدمة جدول البيانات في Apps Script لعمل رسم بياني لمجموعة بياناتك، وستتعلم أيضًا كيفية استخدام خدمة العروض التقديمية لتصدير الرسم البياني إلى عرض تقديمي جديد في Google Slides. هذا هو المقال السادس في دليل تعلم أساسيات برمجة التطبيقات مع جداول بيانات جوجل، وقبل البدء تأكد من إكمال المقالات السابقة: أساسيات برمجة التطبيقات Apps Script. جداول البيانات والأوراق والنطاقات. العمل مع البيانات. استدعاء واجهة برمجة تطبيقات API عامة. تنسيق البيانات. ماذا ستتعلم كيفية إنشاء رسم بياني خطي باستخدام Apps Script. كيفية تصدير الرسوم البيانية إلى عرض شرائح تقديمي جديد. كيفية تقديم الرسائل ومربعات الحوار إلى المستخدم في جداول البيانات. ماذا ستحتاج فهم موضوعات Apps Script الأساسية التي استكشفناها في المقالين السابقين من هذا الدليل. الإلمام الأساسي بمحرر الشيفرات البرمجية Apps Script. الإلمام الأساسي بجداول بيانات Google. الإلمام الأساسي بلغة البرمجة JavaScript وصنف 'String' الخاص به. الإعداد للعمل قبل المتابعة أنت بحاجة إلى جدول بيانات يحتوي على بعض البيانات كما فعلنا في المقالات السابقة، لا تقلق فقد وفرنا لك جدول بيانات جاهز لاستخدامه في هذا التمرين يمكنك تنزيله ورفعه على حسابك في جوجل درايف باستخدام إحدى الطريقتين اللتين ذكرناها في المقال الأول، ويجب أن تبدو الورقة على هذا النحو مع بعض المعلومات الأساسية حول أسعار صرف الدولار الأمريكي المختلفة في تواريخ مختلفة: افتح محرر النصوص البرمجية لـ Apps Script بالنقر على "الإضافات" ثم اختيار "برمجة تطبيقات جوجل"، ثم انقر على كلمة "مشروع بلا عنوان" الموجودة أعلى يمين النافذة لتغيير اسم المشروع إلى "Dates and USD Exchange Rates"، ثم اضغط على زر "إعادة تسمية". احذف الشيفرة البرمجية الموجودة بالمحرر واستبدلها بالشيفرة البرمجية التالية: /** دالة خاصة يتم تشغيلها عند فتح جدول البيانات أو إعادة تحميله * وتستخدم لإضافة قائمة مخصصة إلى جدول البيانات * */ function onOpen() { // Get the Ui object. var ui = SpreadsheetApp.getUi(); إنشاء قائمة مخصصة // ui.createMenu('عرض مجموعة البيانات') .addItem( "رسم بياني لتواريخ وأسعار صرف الدولار الأمريكي", "createEmbeddedLineChart") .addItem("تصدير الرسوم البيانية إلى شرائح جوجل","exportChartsToSlides") .addToUi(); } أعتقد أنه أصبح لديك الخبرة الكافية التي تمكنك من فهم ما ستنفذه هذه الشيفرة البرمجية من المقالات السابقة من هذه السلسلة، نعم بالفعل ستعمل هذه الشيفرة البرمجية على إنشاء قائمة مخصصة باسم "عرض مجموعة البيانات" التي تحتوي بداخلها على العنصر "رسم بياني لتواريخ وأسعار صرف الدولار الأمريكي" والعنصر "تصدير الرسوم البيانية إلى شرائح جوجل". الآن بحصولك على جدول بيانات ومشروع Apps Script فأنت على استعداد لبدء المقال، انتقل إلى القسم التالي من هذا المقال للتعرف على الرسوم البيانية والمحفزات التي يحركها الوقت. إنشاء رسم بياني في جداول البيانات باستخدام Apps Script افترض أنك تريد تصميم رسم بياني معين لتصور مجموعة بيانات، يمكنك بالفعل استخدام Apps Script لإنشاء الرسوم البيانية وتعديلها وإدراجها في جداول بيانات جوجل، وعندما تضمن رسم بياني داخل جدول بيانات، فإنه يسمى "رسم بياني مضمن". وتُستخدم الرسوم البيانية لتصور سلسلة بيانات واحدة أو أكثر، وبالنسبة للرسوم البيانية المضمنة فهي تأتي بالبيانات التي تعرضها عادةً من داخل جدول البيانات، وعادةً ما يؤدي تحديث البيانات في جدول البيانات إلى تحديث الرسم البياني تلقائيًا. ويمكنك استخدام Apps Script لإنشاء رسوم بيانية مخصصة ومضمنة من البداية، أو لتحديث الرسوم البيانية الحالية، ويقدم هذا القسم من المقال أساسيات إنشاء الرسوم البيانية المضمنة في جداول البيانات باستخدام Apps Script وخدمة جداول البيانات. وبسبب هذه القيود غالبًا ما يكون من المفيد استخدام Apps Script لإنشاء رسوم بيانية أو للتعديل على رسوم بيانية أولًا، ثم ضبط التنسيق لهذه الرسوم البيانية يدويًا في جداول البيانات، نعم قد لا تتمكن من أتمتة كل عملية متعلقة بالرسم البياني في Apps Script ولكن يمكنك أتمتة قدر كبير منها. التطبيق في نسختك من جدول البيانات تعرض مجموعة البيانات "التواريخ وأسعار صرف الدولار الأمريكي" أسعار الصرف (مقابل 1 دولار أمريكي) للعملات المختلفة في تواريخ مختلفة، وستكون مهمتك تنفيذ دالة Apps Script التي تنشئ مخططًا لتصوير جزء من هذه البيانات. لتنفيذ ذلك، افتح المشروع الذي أنشأناه في Apps Script باسم "Dates and USD Exchange Rates"، ثم أضف الدالة التالية إلى نهاية النص البرمجي: /** إنشاء وإدراج رسم بياني * مضمنًا في الورقة النشطة * */ function createEmbeddedLineChart() { var sheet = SpreadsheetApp.getActiveSheet(); var chartDataRange = sheet.getRange( 'مجموعة بيانات التواريخ وأسعار صرف الدولار الأمريكي!A2:F102'); var hAxisOptions = { slantedText: true, slantedTextAngle: 60, gridlines: { count: 12 } }; var lineChartBuilder = sheet.newChart().asLineChart(); var chart = lineChartBuilder .addRange(chartDataRange) .setPosition(5, 8, 0, 0) .setTitle('أسعار صرف الدولار الأمريكي') .setNumHeaders(1) .setLegendPosition(Charts.Position.RIGHT) .setOption('hAxis', hAxisOptions) .setOption("useFirstColumnAsDomain", true) .build(); sheet.insertChart(chart); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية تنفذ الشيفرة البرمجية التي أضفتها الدالة المرتبطة بعنصر القائمة المخصصة المسمى "رسم بياني لتواريخ وأسعار صرف الدولار الأمريكي" لإنشاء رسم بياني خطي أساسي، دعنا نراجع هذه الشيفرة البرمجية. تحدد الأسطر الأولى المتغيرات الثلاثة التالية: أولًا، المتغير Sheet وهو يمثل المرجع للصفحة النشطة الحالية. ثانيا، المتغير chartDataRange وهو يمثل نطاق البيانات الذي نريد تصويره عبر الرسم البياني، واستخدمنا أسلوب التدوين A1 لتحديد النطاق الذي يغطي الخلايا من "A2" إلى "F102" في الورقة المسماة "مجموعة بيانات التواريخ وأسعار صرف الدولار الأمريكي"، فمن خلال تحديد اسم الورقة نتأكد من أن عنصر القائمة المخصصة سوف يعمل حتى إذا كانت هناك ورقة مختلفة نشطة، ويعني البدء من الصف "2" أننا نضمن رؤوس الأعمدة بالنطاق وأننا سنرسم فقط أحدث 100 تاريخ (صفوف). ثالثًا، المتغير hAxisOptions وهو يمثل كائن JavaScript أساسي يتضمن بعض معلومات الإعداد التي تستخدمها التعليمات البرمجية لتكوين مظهر المحور الأفقي، على وجه التحديد يعمل على تعيين التسميات النصية للمحور الأفقي عند زاوية ميل 60 درجة، ثم يعمل على تعيين عدد خطوط الشبكة العمودية على "12" خط. يعمل السطر التالي على إنشاء "كائن منشئ الرسم البياني الخطي"، وتُنشأ الرسوم البيانية المضمنة في Apps Script باستخدام "منشيء نمط التصميم" وهو خارج نطاق هذا الدليل، لكن ما يهمك معرفته هو أن خدمة جداول البيانات توفر العديد من الأصناف EmbeddedChartBuilder. لإنشاء رسم بياني تعمل التعليمات البرمجية أولاً على إنشاء "كائن منشئ رسم بياني مضمن"، وتستخدم توابعه لتحديد إعدادات الرسم البياني، ثم تستدعي التابع ()build لإنشاء "كائن منشئ رسم بياني مضمن" النهائي، ولا تعمل تعليماتك البرمجية على تعديل "كائن منشئ رسم بياني مضمن" مباشرةً، إذ تدار كافة تكوين الرسم البياني من خلال أصناف Builder. توفر خدمة جدول البيانات الصنف الأب EmbeddedChartBuilder بالإضافة إلى أصناف ابن متعددة للمنشئ مثل EmbeddedLineChartBuilder، وتسمح الأصناف الابن لـ Apps Script بتوفير توابع لتهيئة منشئ الرسم البياني التي تنطبق فقط على أنواع معينة من الرسوم البيانية، على سبيل المثال: يوفر الصنف EmbeddedPieChartBuilder التابع ()set3D وهو يعمل فقط مع الرسوم البيانية الدائرية. السطر رقم "35" في شيفرتك البرمجية يعمل على إنشاء "كائن منشئ رسم بياني خطي" من خلال المتغير lineChartBuilder. تستدعي الشيفرة البرمجية التابع ()Sheet.newChart لإنشاء كائن "EmbeddedChartBuilder"، ثم يستخدم ()EmbeddedChartBuilder.asLineChart لتعيين نوع المنشئ إلى "EmbeddedLineChartBuilder"، ثم تنشئ الشيفرة البرمجية الرسم البياني باستخدام "الرسم البياني الخطي"، وهذا الجزء من الشيفرة البرمجية مجرد سلسلة من استدعاءات التابع لتحديد إعدادات الرسم البياني، متبوعة باستدعاء ()build لإنشاء الرسم البياني، وإليك ما تفعله استدعاءات التابع: الاستدعاء ()addRange الذي يأخذ معامل واحد فقط وهو "النطاق"، ليحدد نطاق البيانات الذي يعرضه الرسم البياني. الاستدعاء ()setPositionيحدد مكان وضع الرسم البياني في الورقة، وهذا التابع يأخذ أربع معاملات، هم: الأول "موضع ارتكاز الصف" والثاني "موضع ارتكاز العمود" والثالث "الإزاحة X" والرابع "الإزاحة Y"، وفي حالتنا أدرجت الشيفرة البرمجية الزاوية العلوية اليسرى للرسم البياني في الخلية "H5". الاستدعاء ()setTitle الذي يأخذ معامل واحد فقط وهو "العنوان"، ليحدد عنوان الرسم البياني. الاستدعاء ()setNumHeaders الذي يأخذ معامل واحد فقط وهو "عدد الرؤوس"، ليحديد عدد الصفوف أو الأعمدة في نطاق البيانات التي يجب معاملتها كرؤوس، وهنا تستخدم الشيفرة البرمجية الصف الأول في نطاق البيانات كرأس، مما يعني أن النص الموجود في هذا الصف يُستخدم كعناوين لسلسلة البيانات الفردية في الرسم البياني. الاستدعاء ()setLegendPosition الذي يأخذ معامل واحد فقط وهو "الموضع"، ليُحرك وسيلة إيضاح الرسم البياني إلى الجانب الأيمن من الرسم البياني، ويستخدم هذا التابع Charts.Position كمعامل. الاستدعاء ()setOption الذي يأخذ معاملين، هما: الأول "الخيار" والثاني "القيمة"، وذلك ليحدد خيارات الرسم البياني المعقدة، وفي حالتنا تُعين الشيفرة البرمجية خيار hAxis على كائن hAxisOptions، وهناك عدة خيارات يمكنك ضبطها باستخدام هذا التابع، ولقد وُثقت الخيارات والقيم الممكنة لكل نوع رسم بياني في معرض API الرسوم البيانية. الاستدعاء ()build ينشئ ويعيد كائن EmbeddedChart باستخدام الإعدادات المذكورة أعلاه. أخيرًا، تستدعي الشيفرة البرمجية ()Sheet.insertChart الذي يأخذ معامل واحد فقط وهو "الرسم البياني"، لوضع الرسم البياني المدمج في الورقة النشطة. النتائج يمكنك رؤية دالة إنشاء رسمك البياني الخطي وهي تعمل عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "التواريخ وأسعار صرف الدولار الأمريكي" ثم انقر على القائمة المخصصة "عرض مجموعة البيانات" في شريط القوائم، ثم اختر منها القائمة الفرعية "رسم بياني لتواريخ وأسعار صرف الدولار الأمريكي". إذا ظهر لك مربع حوار "لم يتم التحقق من هذا التطبيق" فاتبع الخطوات التي تعلمتها في المقالات السابقة لإعطاء الإذن للماكرو لكي يعمل. يجب أن تبدو النتائج كما يلي: تهانينا، لقد أنشأت رسمًا بيانيًا خطيًا مضمّنًا باستخدام برمجة التطبيقات Apps Script، وسوف يعلمك القسم التالي كيفية تصدير رسمك البياني إلى العروض التقديمية من جوجل. تصدير الرسم البياني إلى العروض التقديمية تتمثل إحدى نقاط القوة العظيمة في Apps Script في أنه يسمح لك بنقل البيانات بسهولة من أحد تطبيقات جوجل إلى آخر، وذلك لأن معظم هذه التطبيقات تحتوي على خدمة Apps Script، فكما تحتوي جداول بيانات جوجل على "خدمة جداول البيانات"، أيضًا يحتوي بريد Gmail على "خدمة Gmail"، ويحتوي محرر مستندات جوجل على "خدمة المستندات"، ويحتوي Google Slides على "خدمة العروض التقديمية"، ومع كل هذه الخدمات المضمنة يمكنك استخراج البيانات من أحد هذه التطبيقات ومعالجتها ثم كتابة النتيجة في تطبيق آخر. وأنت في هذا القسم من المقال ستتعلم كيفية تصدير كل رسم بياني مضمن في جدول بيانات جوجل إلى عرض تقديمي جديد من Google Slides، وسترى أيضًا طريقتين لعرض الرسائل المخصصة للمستخدم في جداول البيانات. التطبيق هنا ستعمل على إنشاء الدالة المرتبطة بعنصر القائمة المخصصة المسمى "تصدير الرسوم البيانية إلى شرائح جوجل"، لذا افتح المشروع الذي أنشأناه في Apps Script باسم "Dates and USD Exchange Rates"، ثم أضف الدالة التالية إلى نهاية النص البرمجي: /** إنشاء عرضًا تقديميًا للرسوم البيانية * ثم تصدير جميع الرسوم البيانية المضمنة في جدول البيانات إلى هذا العرض التقديمي * رسم بياني واحد لكل شريحة * */ function exportChartsToSlides() { var ss = SpreadsheetApp.getActiveSpreadsheet(); إحضار قائمة بجميع الرسوم البيانية المضمنة // في جدول البيانات هذا // var charts = []; var sheets = ss.getSheets(); for (var i = 0; i < sheets.length; i++) { charts = charts.concat(sheets[i].getCharts()); } إذا لم يكن هناك أي رسوم بيانية // اعرض رسالة للمستخدم تخبره بذلك // وارجع دون القيام بأي شيء آخر // if (charts.length == 0) { ss.toast('لا توجد رسوم بيانية لتصديرها!'); return; } إنشاء عرض شرائح // وإزالة عنوان الشريحة الافتراضية // var presentationTitle = " العرض التقديمي لـ" + "" + ss.getName(); var slides = SlidesApp.create(presentationTitle); slides.getSlides()[0].remove(); إضافة الرسوم البيانية إلى العرض التقديمي ، رسم بياني واحد لكل شريحة // var position = {left: 40, top: 30}; var size = {height: 340, width: 430}; for (var i = 0; i < charts.length; i++) { var newSlide = slides.appendSlide(); newSlide.insertSheetsChart( charts[i], position.left, position.top, size.width, size.height); } إنشاء مربع حوار وعرضه لإعلام المستخدم // بمكان العثور على العرض التقديمي الجديد // var slidesUrl = slides.getUrl(); var html = "<p>ابحث عنه في مجلدك الرئيسي على جوجل درايف:</p>" + "<p><a href=\"" + slidesUrl + "\" target=\"_blank\">" + presentationTitle + "</a></p>"; SpreadsheetApp.getUi().showModalDialog( HtmlService.createHtmlOutput(html) .setHeight(120) .setWidth(350), "إنشاء عرض تقديمي!" ); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية قد تكون هذه الشيفرة البرمجية أقصر مما كنت تتوقع، دعنا نراجع ما تفعله من خلال تقسيمها إلى خمسة أقسام: 1. الحصول على الرسوم البيانية تبحث الأسطر القليلة الأولى في جدول البيانات النشط للعثور على جميع الرسوم البيانية المضمنة، ثم تجميعها في مصفوفة رسوم بيانية، وتستخدم هذه الأسطر التابع ()Spreadsheet.getSheets والتابع ()Sheet.getCharts للحصول على قوائم بالأوراق والرسوم البيانية، ويُستخدم التابع ()Array.concat من جافا سكريبت لإلحاق قائمة الرسوم البيانية من كل ورقة إلى المتغير charts. 2. التحقق من وجود رسوم بيانية لتصديرها تتحقق الشيفرة البرمجية من وجود أي رسوم بيانية للتصدير، ونريد بذلك تجنب عمل عرض تقديمي فارغ، لذلك إذا لم تكن هناك رسوم بيانية، فإن الشيفرة البرمجية ستعمل على إنشاء رسالة باستخدام التابع ()Spreadsheet.toast الذي يأخذ معامل واحد فقط وهو "الرسالة"، وهو عبارة عن مربع حوار "نظرة خاطفة" صغير ينبثق في الركن الأيسر السفلي من جداول البيانات، ويبقى لبضع ثوانٍ ثم يختفي: فإذا لم يكن هناك رسوم بيانية لتصديرها، فإن الشيفرة البرمجية تنشئ رسالة وتخرج دون عمل أي شيء آخر، وإذا كانت هناك رسوم بيانية لتصديرها، فسوف تستكمل الشيفرة البرمجية خطوات إنشاء العرض التقديمي. 3. إنشاء عرض تقديمي أُنشئ المتغير presentationTitle للاحتفاظ باسم ملف العرض التقديمي الجديد، ويستند اسم ملف العرض التقديمي على اسم جدول البيانات بالإضافة للسلسلة النصية "العرض التقديمي"، ثم تستدعي الشيفرة البرمجية تابع خدمة الشرائح (اسم ملف العرض التقديمي) SlidesApp.create لإنشاء عرض تقديمي. تنشئ الشيفرة البرمجية عرض تقديمي جديد بشريحة واحدة فارغة، لكننا لا نريد ذلك في عرضنا التقديمي، لذلك فإن الشيفرة البرمجية تزيله باستخدام ()Presentation.getSlides و ()Slide.remove. 4. تصدير الرسوم البيانية في القسم التالي من الشيفرة البرمجية يُحدد موضع وحجم كائنات JavaScript لتعيين مكان وضع الرسوم البيانية المستوردة في الشريحة وتعيين حجم الرسم البياني يكون بالبكسل، وذلك لأن العناصر التي توضع داخل شرائح العرض تتطلب مواضع وأحجام محددة. من خلال حلقة التكرار For تطوف الشيفرة البرمجية على الرسوم البيانية المخزنة في المتغير charts، ثم تنشئ شريحة جديدة لكل رسم بياني باستخدام ()Presentation.appendSlide، ثم إضافة الشريحة إلى نهاية العرض التقديمي، ثم تستخدم التابع ()Slide.insertSheetsChart الذي يأخذ خمس معاملات، هم: الأول "مصرد الرسم البياني" والثاني "موقع اليسار" والثالث "الموقع العلوي" والرابع "العرض" والخامس "الارتفاع"، وذلك لاستيراد الرسم البياني إلى الشريحة بالموقع والحجم المحددين. 5. مشاركة موقع ملف العرض التقديمي أخيرًا، تحتاج الشيفرة البرمجية إلى إخبار المستخدم بمكان ملف العرض التقديمي الجديد، ويفضل أن يكون ذلك باستخدام رابط يمكنه النقر عليه لفتحه، ولتنفيذ ذلك تستخدم الشيفرة البرمجية خدمة HTML في Apps Script لإنشاء مربع حوار مشروط مخصص، ومربعات الحوار المشروطة (المعروفة أيضًا باسم مربعات الحوار المخصصة في Apps Script) هي نوافذ تظهر على واجهة جداول البيانات، وعند عرضها تمنع مربعات الحوار المخصصة المستخدم من التفاعل مع جداول البيانات. ولإنشاء مربع حوار مخصص تحتاج التعليمات البرمجية إلى شيفرة HTML التي تحدد محتوياته، ففي المتغير HTML وفَّرت محتويات مربع الحوار المخصص التي تتمثل في: فقرة قصيرة باستخدام الوسم <P>. ارتباط تشعبي يحتوي على عنوان ملف العرض التقديمي المخزن في المتغير presentationTitle، وهو مرتبط بعنوان URL للعرض التقديمي المقدم من ()Presentation.getUrl. يستخدم الارتباط التشعبي أيضًا السمة "target="_blank وذلك لفتح العرض التقديمي في علامة تبويب مستعرض جديدة، وليس داخل مربع الحوار. تُحلل شيفرة HTML في الكائنHtmlOutput بواسطة التابع (HtmlService.createHtmlOutput(html، ويسمح الكائنHtmlOutput للشيفرة البرمجية بتعيين حجم مربع الحوار المخصص باستخدام ()HtmlOutput.setHeight الذي يأخذ معامل واحد فقط وهو "قيمة الارتفاع"، و ()HtmlOutput.setWidth الذي يأخذ معامل واحد فقط وهو "قيمة العرض". بمجرد إنشاء الكائن htmlOutput، تستخدم الشيفرة البرمجية التابع (Ui.showModalDialog(htmlOutput, title لعرض مربع الحوار بالعنوان المحدد. النتائج الآن بعد أن ربطت عنصر القائمة المخصصة المسمى "تصدير الرسوم البيانية إلى شرائح جوجل" بالدالة ()exportChartsToSlides، يمكنك رؤية نتائج عملك عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "التواريخ وأسعار صرف الدولار الأمريكي" ثم انقر على القائمة المخصصة "عرض مجموعة البيانات" في شريط القوائم، ثم اختر منها القائمة الفرعية "رسم بياني لتواريخ وأسعار صرف الدولار الأمريكي" وذلك لإنشاء رسم بياني داخل ورقة جدول البيانات. انقر مرة أخرى على القائمة المخصصة "عرض مجموعة البيانات" في شريط القوائم، ثم اختر منها القائمة الفرعية "تصدير الرسوم البيانية إلى شرائح جوجل". إذا ظهر لك مربع حوار "لم يتم التحقق من هذا التطبيق" فاتبع الخطوات التي تعلمتها في المقال السابقة لإعطاء الإذن للماكرو لكي يعمل. يجب أن ترى السكربت يعالج طلبك ويعرض مربع الحوار المخصص. لفتح عرض الشرائح الجديد انقر على رابط "عرض التواريخ وأسعار صرف الدولار الأمريكي"، ويجب أن تبدو النتائج كما يلي: تهانينا، يمكنك الآن تصدير الرسوم البيانية التي أنشأتها في جداول البيانات إلى عرض تقديمي في شرائح جوجل، كما يمكنك أيضًا كتابة شيفرة برمجية لإنشاء رسائل ومربعات حوار مخصصة موجهة للمستخدم. خاتمة وإلى هنا نكون قد وصلنا إلى نهاية دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، يمكنك الآن استخدام المبادئ التي درستها في هذا الدليل لتوسيع تجربة استخدامك لجداول البيانات واستكشاف إمكانيات Apps Script. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا المقال السابق: تنسيق البيانات داخل جداول بيانات جوجل باستخدام Apps Script أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script كيفية استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Scrip

مرحبًا بك في المقال الخامس من دليل تعلم أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، فبعد إكمالك لهذا المقال سوف يصبح لديك المعرفة في كيفية تنسيق بيانات جدول البيانات في Apps Script، وكتابة دوال مخصصة لإنشاء جداول بيانات منظمة مليئة بالبيانات المنسقة التي جُلبت من واجهة برمجة تطبيقات عامة API. هذا هو المقال الرابع في دليل تعلم أساسيات برمجة التطبيقات مع جداول بيانات جوجل، وقبل البدء تأكد من إكمال المقالات السابقة: أساسيات برمجة التطبيقات Apps Script. جداول البيانات والأوراق والنطاقات. العمل مع البيانات. استدعاء واجهة برمجة تطبيقات API عامة. ماذا ستتعلم كيفية تطبيق عمليات تنسيق جداول بيانات جوجل المختلفة في Apps Script. كيفية تحويل قائمة كائنات JSON وسماتها إلى ورقة منظمة من البيانات باستخدام Apps Script. ماذا ستحتاج فهم موضوعات Apps Script الأساسية التي استكشفناها في المقالين السابقين من هذا الدليل. الإلمام الأساسي بمحرر الشيفرات البرمجية Apps Script. الإلمام الأساسي بجداول بيانات Google. الإلمام الأساسي بلغة البرمجة JavaScript وصنف 'String' الخاص به. الإعداد للعمل قبل المتابعة أنت بحاجة إلى جدول بيانات يحتوي على بعض البيانات كما فعلنا في المقالات السابقة، لا تقلق فقد وفرنا لك جدول بيانات جاهز لاستخدامه في هذا التمرين، نزله وارفعه على حسابك في درايف باستخدام إحدى الطريقتين اللتين وضحناهما في المقال الأول، ويجب أن تبدو الورقة على هذا النحو مع بعض المعلومات الأساسية حول أول ثلاثة أجزاء من فيلم حرب النجوم: افتح محرر النصوص البرمجية لـ Apps Script بالنقر على "الإضافات" ثم اختيار "محرر تطبيقات جوجل"، وبعدها انقر على عنوان مشروع برمجة التطبيقات وغيره من "مشروع بلا عنوان" إلى "Data Formatting"، ثم انقر على زر "إعادة تسمية" لحفظ تغيير العنوان. الآن بحصولك على جدول بيانات ومشروع Apps Script فأنت على استعداد لبدء المقال، انتقل إلى القسم التالي من هذا المقال للتعرف على التنسيق الأساسي في Apps Script. إنشاء قائمة مخصصة يمكنك تطبيق العديد من طرائق التنسيق الأساسية في Apps Script على جداول البيانات الخاصة بك، وتوضح التمارين التالية بعض هذه الطرائق لمساعدتك في التحكم في إجراءات التنسيق الخاصة بك، لذلك سوف نعمل على إنشاء قائمة مخصصة بالعناصر التي ستحتاج إليها، لقد شرحنا عملية إنشاء القوائم المخصصة في المقال السابق "العمل مع البيانات"، ولكننا سنلخصها هنا مرة أخرى. التطبيق دعنا نبدأ في إنشاء قائمة مخصصة باتباع الخطوات التالية: أولًا، استبدل الشيفرة البرمجية في مشروع Apps Script الذي أسميناه "Data Formatting" بما يلي: /** دالة خاصة يتم تشغيلها عند فتح جدول البيانات أو إعادة تحميله * وتستخدم لإضافة قائمة مخصصة إلى جدول البيانات * */ function onOpen() { الحصول على كائن واجهة المستخدم الخاص بجدول البيانات // var ui = SpreadsheetApp.getUi(); إنشاء وإضافة القائمة المخصصة وعناصرها إلى شريط القوائم // ui.createMenu('تنسيقات سريعة') .addItem('تنسيق رأس الصف', 'formatRowHeader') .addItem('تنسيق رأس العمود', 'formatColumnHeader') .addItem('تنسيق البيانات', 'formatDataset') .addToUi(); } ثانيًا، احفظ مشروع نصك البرمجي. ثالثًا، في محرر Apps Script حدد اسم الدالة "onOpen" من قائمة الدوال، ثم انقر على الزر "Run"، سيعمل هذا الإجراء على تشغيل الدالة ()onOpen لإنشاء القائمة المخصصة بجدول البيانات دون الحاجة إلى إعادة تحميل جدول البيانات. مراجعة الشيفرة البرمجية دعنا نراجع هذه الشيفرة البرمجية لفهم كيفية عمل الدالة ()onOpen. يستخدم السطر الأول التابع()getUi للحصول على كائن "Ui" يمثل واجهة المستخدم لجدول البيانات النشط الذي يرتبط به هذا النص البرمجي أو السكربت. تعمل الأسطر الثلاثة التالية على إنشاء قائمة مخصصة باسم "تنسيقات سريعة" ثم إضافة ثلاثة عناصر داخل هذه القائمة باسم "تنسيق رأس الصف" و "تنسيق رأس العمود" و "تنسيق البيانات"، ثم إضافة هذه القائمة المخصصة إلى واجهة جدول البيانات، ونفذنا ذلك باستخدام ثلاث توابع متتالية على النحو التالي: أولاً، التابع ()createMenu والذي يأخذ معامل واحد فقط وهو "اسم القائمة المخصصة". ثانيًا، التابع ()addItem والذي يأخذ معاملين، الأول "اسم العنصر داخل القائمة المخصصة"، والثاني "اسم الدالة بالإنجليزية". ثالثًا، التابع ()addToUi وهو لا يأخذ أي معاملات. ينشيء التابع ()addItem اتصالاً بين تسمية العنصر الموجود داخل القائمة المخصصة مثل (تنسيق رأس الصف) ودالة Apps Script المرتبطة بهذا العنصر formatRowHeader (التي لم نوفرها بعد) لتشغيلها. النتائج اذهب إلى جداول بيانات جوجل الذي نتدرب عليه "تنسيق البيانات" ثم انقر على القائمة المخصصة "تنسيقات سريعة" لعرض عناصر هذه القائمة. ويؤدي النقر على أي من هذه العناصر إلى حدوث خطأ وذلك نظرًا لأنك لم تنفذ الدالة المقابلة لكل عنصر منهم، لذلك دعنا نفعل ذلك في القسم التالي من هذا المقال. تنسيق رؤوس الصفوف غالبًا ما تحتوي مجموعات البيانات في جداول البيانات على رأس صف لتحديد البيانات في كل عمود، ومن الجيد تنسيق رأس الصف لفصله بصريًا عن باقي البيانات في جدول البيانات. في المقال الأول من هذا الدليل أنشأنا ماكرو لرأس الصف وضبطت الشيفرة البرمجية الخاصة بها، لكن هنا سنعمل على تنسيق رأس الصف من البداية باستخدام Apps Script، وسيؤدي تنسيق رأس الصف الذي ستنشئه إلى جعل نص الرأس غامقًا، ولون الخلفية باللون الأزرق الداكن والأخضر، ولون النص باللون الأبيض، وإضافة بعض الخطوط الحدودية للخلايا. التطبيق لتنفيذ عملية التنسيق ستستخدم نفس توابع خدمة جدول البيانات التي استخدمتها من قبل، بالإضافة أيضًا إلى بعض توابع التنسيق الخاصة بالخدمة، فقط افتح المشروع الذي أنشأناه في Apps Script باسم "Data Formatting"، ثم أضف الدالة التالية إلى نهاية النص البرمجي: /** دالة تعمل على تنسيق الصف العلوي من الورقة باستخدام نمط رأس الصف الخاص بنا * */ function formatRowHeader() { الحصول على الورقة النشطة الحالية ونطاق الصف العلوي // var sheet = SpreadsheetApp.getActiveSheet(); var headerRange = sheet.getRange(1, 1, 1, sheet.getLastColumn()); تطبيق هذه التنسيقات على الصف العلوي // نص أبيض غامق وخلفية زرقاء وخضراء // وحدود سوداء صلبة حول الخلايا // headerRange .setFontWeight('bold') .setFontColor('#ffffff') .setBackground('#007272') .setBorder( true, true, true, true, null, null, null, SpreadsheetApp.BorderStyle.SOLID_MEDIUM); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية مثل العديد من مهام التنسيق تكون الشيفرة البرمجية المنفذة في Apps Script واضحة ومباشرة. يستخدم أول سطرين توابع رأيتها من قبل للحصول على مرجع للورقة النشطة الحالية من خلال المتغير sheet، والصف العلوي للورقة من خلال المتغير headerRange. يحدد التابع ()Sheet.getRange الصف العلوي بما في ذلك الأعمدة التي تحتوي على بيانات فقط، وهذا التابع يأخذ أربع معاملات، هم: الأول "رقم الصف" والثاني "رقم العمود" والثالث "عدد الصفوف" والرابع "عدد الأعمدة". يعمل التابع ()Sheet.getLastColumn على إرجاع الفهرس الخاص بالعمود الأخير الذي يحتوي على بيانات في الورقة، وفي مثالنا إنه العمود "E" المسمى "الرابط". تستدعي باقي الشيفرة البرمجية ببساطة توابع Range لتطبيق خيارات التنسيق على جميع الخلايا في المتغير headerRange، وللحفاظ على سهولة قراءة الشيفرة البرمجية نستخدم تسلسل التابع لاستدعاء كل تابع تنسيق واحدة تلو الأخرى كما يلي: بالنسبة للتابع ()Range.setFontWeight الذي يأخذ معامل (وزن الخط)، يعمل على ضبط قيمة وزن الخط إلى غامق. أما التابع ()Range.setFontColor الذي يأخذ معامل (لون الخط)، يعمل على تعيين لون الخط إلى الأبيض. والتابع ()Range.setBackground الذي يأخذ معامل (لون الخلفية)، يعمل على ضبط لون الخلفية على الأزرق الداكن والأخضر. وأخيرًا التابع ()setBorder يعمل على وضع حدًا أسودًا خالصًا حول خلايا النطاق، وهذا التابع له عدة معاملات (أعلى - يسار - أسفل - يمين - عمودي - أفقي - لون - نمط) لذلك دعنا نراجع ما يفعله كل معامل منهم: تخبر المعاملات الأربعة الأولى هنا (جميعها مضبوطة على "true") أنه يجب إضافة الحد أعلى وأسفل وإلى يسار ويمين النطاق. توجّه المعاملتان الخامسة والسادسة (مضبوطتان على "null") برمجة التطبيقات مباشرة لتجنب تغيير أي خطوط حد ضمن النطاق المحدد. يشير المعامل السابعة (مضبوطة على "null") إلى أن لون الحد يجب أن يكون افتراضيًا باللون الأسود. أخيرًا يحدد المعامل الأخير نوع نمط الحدود المراد استخدامه، مأخوذ من الخيارات التي يوفرها SpreadsheetApp.BorderStyle. النتائج يمكنك رؤية دالة التنسيق الخاصة بك وهي تعمل عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "تنسيق البيانات" ثم انقر على القائمة "تنسيقات سريعة" في شريط القوائم، ثم اختر منها القائمة الفرعية "تنسيق رأس الصف". إذا ظهر لك مربع حوار "لم يتم التحقق من هذا التطبيق" فاتبع الخطوات التي تعلمتها في المقالات السابقة لإعطاء الإذن للماكرو لكي يعمل. يجب أن تبدو النتائج كما يلي: تهانينا، لقد أتممت الآن مهمة التنسيق لرؤوس الصفوف تلقائيًا، يطبق القسم التالي نفس الأسلوب لإنشاء نمط تنسيق مختلف لرؤوس الأعمدة. تنسيق رؤوس الأعمدة إذا كان بإمكانك إنشاء رأس صف مخصص فيمكنك إنشاء رأس عمود مخصص أيضًا، وتزيد عملية تنسيق رؤوس الأعمدة من قابلية القراءة للبيانات، فعلى سبيل المثال: يمكنك تحسين العمود المسمى "العنوان" في جدول البيانات الذي تتمرن عليه بخيارات التنسيق التالية: تحويل النص إلى عريض. تحويل النص إلى مائل. إضافة حدود للخلية. إدراج ارتباطات تشعبية باستخدام محتويات العمود المسمى "الرابط"، وبمجرد إضافة هذه الارتباطات التشعبية يمكنك إزالة العمود المسمى "الرابط" للمساعدة في تنظيف الورقة. في القسم التالي من هذا المقال ستعمل على إنشاء الدالة ()formatColumnHeader لتنفيذ هذه التنسيقات على العمود الأول في الورقة، وللمساعدة في جعل الشيفرة البرمجية أسهل قليلاً في القراءة سوف ننفذها في دالتين بدلاً من دالة واحدة. التطبيق لإضافة دالة تعمل على أتمتة تنسيق رأس العمود، فقط اتبع الخطوات التالية: أولًا، في مشروع Apps Script الذي باسم "Data Formatting" أضف الدالة التالية إلى نهاية النص البرمجي: /** تنسيق رؤوس العواميد الخاصة بالورقة النشطة * */ function formatColumnHeader() { var sheet = SpreadsheetApp.getActiveSheet(); الحصول على العدد الإجمالي للصفوف في نطاق البيانات // بدون تضمين رؤوس الصفوف // var numRows = sheet.getDataRange().getLastRow() - 1; الحصول على نطاق رؤوس الأعمدة // var columnHeaderRange = sheet.getRange(2, 1, numRows, 1); تطبيق تنسيق النص وإضافة حدود // columnHeaderRange .setFontWeight('bold') .setFontStyle('italic') .setBorder( true, true, true, true, null, null, null, SpreadsheetApp.BorderStyle.SOLID_MEDIUM); استدعاء صنف مساعد لتحويل محتويات العمود الأول إلى رابط تشعبي // مضمن بالروابط الموجودة داخل عمود "العنوان" // hyperlinkColumnHeaders_(columnHeaderRange, numRows); } ثانيا، أضف الدالتين التاليتين إلى نهاية النص البرمجي: /** دالة مساعدة تربط محتويات العمود الأول بمحتويات العمود "الرابط" * ثم تقوم الدالة بعد ذلك بإزالة العمود "الرابط" * * * @param {object} headerRange هو نطاق عنوان العمود المراد تحديثه * @param {number} numRows هو عدد رؤوس الأعمدة */ function hyperlinkColumnHeaders_(headerRange, numRows) { الحصول على رقم فهرس عمود "العنوان" وعمود "الرابط" // var headerColIndex = 1; var urlColIndex = columnIndexOf_('الرابط'); الخروج إذا كان عمود "الرابط" مفقودًا // if(urlColIndex == -1) return; الحصول على قيم خلية "العنوان" و "الرابط" // var urlRange = headerRange.offset(0, urlColIndex - headerColIndex); var headerValues = headerRange.getValues(); var urlValues = urlRange.getValues(); تحديث القيم بعمود "العنوان" إلى قيم ذات روابط تشعبية // for(var row = 0; row < numRows; row++){ headerValues[row][0] = '=HYPERLINK("' + urlValues[row] + '","' + headerValues[row] + '")'; } headerRange.setValues(headerValues); حذف عمود "الرابط" لتنظيف الورقة // SpreadsheetApp.getActiveSheet().deleteColumn(urlColIndex); } /** * دالة مساعدة تمر عبر رؤوس جميع الأعمدة * وتعيد فهرس العمود بالاسم المحدد في الصف 1 * وفي حالة عدم وجود عمود بهذا الاسم * ترجع هذه الدالة القيمة -1 * إذا كان هناك أعمدة متعددة لها نفس الاسم في الصف 1 * فسيتم إرجاع فهرس أول عمود تم اكتشافه * * * @param {string} colName هو الاسم المراد العثور عليه في رؤوس الأعمدة * * @return إرجاع فهرس هذا العمود في الورقة النشطة أو القيمة -1 إذا لم يتم العثور على الاسم * */ function columnIndexOf_(colName) { الحصول على أسماء الأعمدة الحالية // var sheet = SpreadsheetApp.getActiveSheet(); var columnHeaders = sheet.getRange(1, 1, 1, sheet.getLastColumn()); var columnNames = columnHeaders.getValues(); حلقة تكرار خلال كل عمود لإرجاع رقم فهرس العمود // // colName إذا كانت قيمة الصف 1 لهذا العمود تطابق for(var col = 1; col <= columnNames[0].length; col++) { if(columnNames[0][col-1] === colName) return col; } إرجاع القيمة -1 إذا كان العمود المسمى colName غير موجود // return -1; } أخيرًا، احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية دعنا نراجع الشيفرة البرمجية للدوال الثلاث: 1. الدالة ()formatColumnHeader نعم توقعك صحيح، فالأسطر القليلة الأولى من هذه الدالة تحدد المتغيرات التي تشير إلى الورقة والنطاق الذي نهتم به. يعمل المتغير Sheet على تخزين الورقة النشطة. يعمل المتغير numRows على حساب عدد الصفوف الموجودة في رأس العمود وحفظها، وتطرح الشيفرة البرمجية "1" حتى لا يشتمل عدد الصفوف على رأس العمود المسمى "العنوان". يعمل المتغير columnHeaderRange على تخزين النطاق الذي يغطي رأس العمود. تشرع الشيفرة البرمجية في تنفيذ تنسيقات الحدود والكتابة على نطاق رأس العمود، تمامًا كما هو الحال في الدالة ()formatRowHeader، الجديد في هذه الدالة أننا استخدمنا التابع ()Range.setFontStyle لجعل النص مائلًا. تعد إضافة الارتباطات التشعبية إلى عمود الرأس عملية معقدة، لذا فإن الدالة ()formatColumnHeader تستدعي التابع ()_hyperlinkColumnHeaders لتولي هذه المهمة، وهو تابع يأخذ معاملين الأول "نطاق رأس العمود" والثاني "عدد الصفوف"، ويساعد هذا الإجراء في الحفاظ على الشيفرة البرمجية منظمة وقابلة للقراءة. 2. الدالة ()_hyperlinkColumnHeaders تأخذ هذه الدالة معاملين الأول "نطاق الرأس" والثاني "عدد الصفوف"، وتحدد هذه الدالة أولاً فهارس العمود الخاصة بالرأس (من المفترض أن يكون الفهرس رقم 1) والعمود المسمى "الرابط"، فتعمل على استدعاء التابع ()_columnIndexOf للحصول على فهرس العمود المسمى "الرابط"، وفي حالة عدم عثوره عليه ينهي التابع عمله دون تعديل أي بيانات. تحصل الدالة على نطاق جديد من خلال المتغير urlRange يغطي عناوين الروابط المقابلة لصفوف رأس العمود، وينفذ هذا الإجراء باستخدام التابع ()Range.offset الذي يأخذ معاملين الأول "إزاحة الصف" والثاني "إزاحة العمود"، وذلك لضمان أن النطاقين سيكونان بالحجم نفسه، ثم يسترد المتغير headerValues والمتغير urlValues القيم الموجودة في رأس العمود، والخلايا بالعمود المسمى "الرابط". تنفذ الدالة بعد ذلك حلقة التكرار For لقيمة كل خلية في رأس العمود ثم تستبدلها بصيغة جداول بيانات ()HYPERLINK= باستخدام محتويات رأس العمود والخلايا بالعمود المسمى "الرابط"، ثم يلي ذلك إدراج قيم الرأس المعدلة في الورقة باستخدام التابع ()Range.setValues. أخيرًا، وللمساعدة في الحفاظ على الورقة نظيفة من خلال التخلص من المعلومات الزائدة عن الحاجة، يُستدعى التابع ()Sheet.deleteColumn الذي يأخذ معامل واحد وهو "موضع العمود"، لإزالة العمود المسمى "الرابط" بالكامل. 3. الدالة ()_columnIndexOf تأخذ هذه الدالة معامل واحد فقط وهو "اسم العمود"، وتبحث هذه الدالة في الصف الأول من الورقة عن اسم محدد، وتستخدم الأسطر الثلاثة الأولى توابع رأيتها بالفعل للحصول على قائمة بأسماء رؤوس الأعمدة من الصف رقم "1" بجدول البيانات، ثم تُخزن هذه الأسماء في المتغير columnNames. تعمل الدالة بعد ذلك على مراجعة كل اسم بالترتيب، فإذا عثرت على اسم يطابق الاسم الذي تبحث عنه، فإنها تتوقف وتعيد رقم فهرس العمود، أما إذا وصلت إلى نهاية قائمة الأسماء دون العثور على الاسم الذي تبحث عنه، فإنها ترجع الرقم "-1" للإشارة إلى عدم العثور على الاسم. النتائج يمكنك رؤية دالة التنسيق الخاصة بك وهي تعمل عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "تنسيق البيانات" ثم انقر على القائمة "تنسيقات سريعة" في شريط القوائم، ثم اختر منها القائمة الفرعية "تنسيق رأس الصف". يجب أن تبدو النتائج كما يلي: تهانينا، لقد أتممت الآن مهمة التنسيق لرؤوس الأعمدة تلقائيًا، يطبق القسم التالي كيفية تنسيق البيانات. تنسيق البيانات الآن بعد أن أصبح لديك رؤوس الصفوف والأعمدة منسقة، دعنا ننشئ دالة تعمل على تنسيق بقية البيانات في الورقة الخاصة بك، وسنستخدم خيارات التنسيق التالية: تناوب ألوان خلفية الصف (صف بلون أبيض وآخر بلون رمادي). تغيير صيغة التاريخ. تطبيق حدود الخلية. ضبط جميع مقاسات الأعمدة والصفوف تلقائيًا لسهولة قراءة البيانات بداخلهم. ولتنفيذ ذلك سنعمل على إنشاء الدالة ()formatDataset، بالإضافة إلى دالة مساعدة لتطبيق هذه التنسيقات على بيانات الورقة الخاصة بك. التطبيق لإضافة دالة تعمل على أتمتة تنسيق البيانات، فقط اتبع الخطوات التالية: أولًا، في مشروع Apps Script الذي باسم "Data Formatting" أضف الدالة التالية إلى نهاية النص البرمجي: /** * تنسيق بيانات الورقة باستثناء رؤوس الصفوف والأعمدة * تطبيق الحدود وينسق عمود "تاريخ العرض" * وضبط الأعمدة والصفوف تلقائيًا * */ function formatDataset() { الحصول على الورقة النشطة ونطاق البيانات // var sheet = SpreadsheetApp.getActiveSheet(); var fullDataRange = sheet.getDataRange(); تطبيق خطوط مرئية من الألوان المتناقضة على البيانات // باستثناء رؤوس الصفوف والأعمدة // تطبيق خطوط مرئية من الألوان المتناقضة فقط إذا لم يكن النطاق يحتوي عليها بالفعل // var noHeadersRange = fullDataRange.offset( 1, 1, fullDataRange.getNumRows() - 1, fullDataRange.getNumColumns() - 1); if (! noHeadersRange.getBandings()[0]) { النطاق لا يحتوي بالفعل على خطوط مرئية من الألوان المتناقضة // لذلك من الآمن تطبيقه // noHeadersRange.applyRowBanding( SpreadsheetApp.BandingTheme.LIGHT_GREY, false, false); } استدعاء الدالة المساعدة لتطبيق تنسيق التاريخ // على العمود المسمى "تاريخ العرض" // formatDates_( columnIndexOf_('تاريخ العرض') ); عيّن حدًا حول كل البيانات // تغيير حجم الأعمدة والصفوف لتناسب البيانات // fullDataRange.setBorder( true, true, true, true, null, null, null, SpreadsheetApp.BorderStyle.SOLID_MEDIUM); sheet.autoResizeColumns(1, fullDataRange.getNumColumns()); sheet.autoResizeRows(1, fullDataRange.getNumRows()); } ثانيًا، أضف الدالة المساعدة التالية في نهاية مشروع البرنامج النصي بعد الدالة ()formatDataset. /** الصنف المساعد الذي يطبق تنسيق التاريخ * شهر، يوم، سنة (اسم اليوم من الأسبوع) * على العمود المشار إليه في الورقة النشطة * * * @param {number} colIndex فهرس العمود المطلوب تنسيقه * */ function formatDates_(colIndex) { اخرج إذا كان فهرس العمود المحدد هو -1 // مما يشير إلى أن العمود المطلوب تنسيقه غير موجود في الورقة // if (colIndex < 0) return; قم بتعيين تنسيق التاريخ لعمود "تاريخ العرض" // باستثناء رؤوس الصفوف // var sheet = SpreadsheetApp.getActiveSheet(); sheet.getRange(2, colIndex, sheet.getLastRow() - 1, 1) .setNumberFormat("mmmm dd, yyyy (dddd)"); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية دعنا نراجع الشيفرة البرمجية لهاتين الدالتين: 1. دالة ()formatDataset تتبع هذه الدالة نمطًا مشابهًا لدوال التنسيق السابقة التي نفذتها، فهي تحتوي على المتغير Sheet لتخزين الورقة النشطة، والمتغير fullDataRange لتخزين نطاق البيانات. أما المتغير noHeadersRange يستخدم التابع ()Range.offset الذي يأخذ أربع معاملات، هي: الأول "إزاحة الصف" والثاني "إزاحة العمود" والثالث "عدد الصفوف" والرابع "عدد الأعمدة"، ويعمل هذا التابع على إنشاء نطاق يغطي جميع البيانات الموجودة في الورقة، باستثناء رؤوس الأعمدة والصفوف. تتحقق الشيفرة البرمجية بعد ذلك مما إذا كان هذا النطاق الجديد يحتوي على خطوط مرئية من الألوان المتناقضة (الأبيض والرمادي بالتناوب) في خلفية الخلية باستخدام التابع ()Range.getBandings، ويعد هذا أمرًا ضروريًا لأن Apps Script تظهر خطأ إذا حاولت تطبيق هذا الأمر في نطاق يوجد به خطوط مرئية من الألوان المتناقضة بالفعل. في حالة عدم وجود خطوط مرئية من الألوان المتناقضة في النطاق الجديد، تضيف الدالة خطًا مرئيًا رماديًا فاتحًا باستخدام التابع ()Range.applyRowBanding الذي يأخذ ثلاث معاملات، هي: الأول "سمة لون الخط" والثاني "إظهار الرأس" والثالث "إظهار التذييل"، وبخلاف ذلك تُكمل الدالة عملها. في الخطوة التالية نستدعي ()_formatDates الذي يأخذ معامل واحد فقط وهو "رقم فهرس العمود"، وتعمل على تنسيق التواريخ في العمود المسمى "تاريخ العرض" وحُدد هذا العمود باستخدام ()columnIndexOf الذي يأخذ معامل واحد فقط وهو "اسم العمود"، وهو تابع استخدمته من قبل. أخيرًا، نتمم هذا التنسيق عن طريق إضافة حدود الخلايا كما فعلنا من قبل، وتغيير حجم كل عمود وصف تلقائيًا لملاءمة البيانات التي تحتوي عليها باستخدام التابع ()Sheet.autoResizeColumns الذي يأخذ معامل واحد فقط وهو "موضع العمود"، والتابع ()Sheet.autoResizeRows الذي يأخذ معامل واحد فقط وهو "موضع الصف". 2: دالة ()_formatDates تأخذ هذه الدالة معامل واحد وهو "رقم فهرس العمود"، وتعمل هذه الدالة على تطبيق تنسيق تاريخ محدد على العمود المسمى "تاريخ العرض"، وذلك باستخدام رقم فهرس العمود المقدم من الدالة، وعلى وجه التحديد تُنسق قيم التاريخ هكذا: "شهر، يوم ، سنة (اسم اليوم من الأسبوع)". تتحقق الدالة أولاً من صلاحية رقم فهرس العمود المقدم (هل هو 0 أو أكبر) فإذا لم يكن كذلك فإنها تعود دون فعل أي شيء، ويمنع هذا الإجراء الأخطاء التي قد تحدث، مثل إذا لم تكن الورقة تحتوي على عمود باسم "تاريخ العرض". بمجرد التحقق من صحة فهرس العمود، تحصل الدالة على النطاق الذي يغطي هذا العمود (باستثناء رأس الصف) ثم تستخدم ()Range.setNumberFormat لتطبيق التنسيق. النتائج يمكنك رؤية دالة التنسيق الخاصة بك وهي تعمل عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "تنسيق البيانات" ثم انقر على القائمة "تنسيقات سريعة" في شريط القوائم، ثم اختر منها القائمة الفرعية "تنسيق البيانات". يجب أن تبدو النتائج كما يلي: تهانينا، لقد أتممت مهمة تنسيق أخرى تلقائيًا، الآن بعد أن توفرت لديك أدوات التنسيق هذه دعنا نضيف المزيد من البيانات لتطبيقها عليها. إحضار وتنسيق بيانات من API لقد تعلمت في هذا المقال كيف يمكنك استخدام Apps Script كوسيلة بديلة لتنسيق جدول البيانات الخاص بك، والآن ستتعلم كيفية كتابة شيفرة برمجية تعمل على سحب البيانات من واجهة برمجة تطبيقات عامة API، ثم تُدرجها في جدول البيانات الخاص بك، ثم تنسيقها لتتمكن من قراءتها. في المقال السابق تعلمت كيفية سحب البيانات من واجهة برمجة التطبيقات API، وستستخدم نفس الأساليب في هذا التمرين، سوف نعمل مع واجهة برمجة تطبيقات عامة اسمها Star Wars API والمعروفة اختصارًا بـ SWAPI لملء جدول البيانات الخاص بك، وعلى وجه التحديد ستستخدم واجهة برمجة التطبيقات هذه للحصول على معلومات حول الشخصيات الرئيسية التي ظهرت في أفلام Star Wars الثلاثة الأصلية. ستعمل الشيفرة البرمجية على استدعاء الـ API للحصول على كمية كبيرة من بيانات JSON، ثم تحليل الاستجابة، ثم وضع البيانات في ورقة جدول بيانات جديدة، ثم تنسيق الورقة. التطبيق في هذا القسم ستضيف بعض العناصر للقائمة المخصصة "تنسيقات سريعة"، يستدعي كل عنصر منهم سكريبت مجمّع يمرر متغيرات خاصة بهذا العنصر إلى الدالة الرئيسية ()_createResourceSheet. لذلك أنت تحتاج إلى إنشاء هذه الدالة بالإضافة إلى ثلاث دوال مساعدة لها، فالدوال المساعدة تعمل على عزل الأجزاء المقسمة منطقيًا للمهمة، كما تساعد في الحفاظ على الشيفرة البرمجية قابلة للقراءة. ولتنفيذ ذلك اتخذ الإجراءات التالية: أولًا، في محرر Apps Script حدث الدالة ()onOpen في مشروع النص البرمجي المسمى "Data Formatting" لمطابقة ما يلي: /** وظيفة خاصة يتم تشغيلها عند فتح جدول البيانات أو إعادة تحميله * تستخدم لإضافة قائمة مخصصة إلى جدول البيانات * */ function onOpen() { الحصول على كائن واجهة المستخدم لجدول البيانات // var ui = SpreadsheetApp.getUi(); إنشاء وإضافة قائمة خاصة وعناصرها إلى شريط القوائم // ui.createMenu('تنسيقات سريعة') .addItem('تنسيق رأس الصف', 'formatRowHeader') .addItem('تنسيق رأس العمود', 'formatColumnHeader') .addItem('تنسيق البيانات', 'formatDataset') .addSeparator() .addSubMenu(ui.createMenu('أبطال ثلاثية حرب النجوم') .addItem('الجزء الرابع', 'createPeopleSheetIV') .addItem('الجزء الخامس', 'createPeopleSheetV') .addItem('الجزء السادس', 'createPeopleSheetVI') ) .addToUi(); } احفظ مشروع نصك البرمجي. ثانيًا، في محرر Apps Script حدد اسم الدالة "onOpen" من قائمة الدوال، ثم انقر على الزر "Run" لتشغيل الدالة حتى تنفذ الشيفرة البرمجية لإضافة العناصر الجديدة داخل القائمة المخصصة "تنسيقات سريعة". ثالثًا، أنشئ ملف Apps Script جديد، وذلك بالنقر على أيقونة (+) الموجودة أعلى يمين النافذة وبجوار كلمة "الملفات"، ثم اختر "نص برمجي". رابعًا، أعط اسمًا لمف النص البرمجي الجديد "API" ثم اضغط على زر "Enter" من لوحة المفاتيح حتى يُلحق Apps Script تلقائيًا امتداد "gs." إلى اسم ملف النص البرمجي. خامسًا، استبدل الشيفرة البرمجية في ملف "API.gs" الجديد بما يلي: /** الدالة الغالفة التي تمرر المعاملات * لإنشاء ورقة موارد تصف الشخصيات من الجزء الرابع * */ function createPeopleSheetIV() { createResourceSheet_('characters', 1, "الجزء الرابع"); } /** الدالة الغالفة التي تمرر المعاملات * لإنشاء ورقة موارد تصف الشخصيات من الجزء الخامس * */ function createPeopleSheetV() { createResourceSheet_('characters', 2, "الجزء الخامس"); } /** الدالة الغالفة التي تمرر المعاملات * لإنشاء ورقة موارد تصف الشخصيات من الجزء السادس * */ function createPeopleSheetVI() { createResourceSheet_('characters', 3, "الجزء السادس"); } /** إنشاء ورقة منسقة مليئة بالمعلومات التي يحددها المستخدم * من خلال Star Wars API * فإذا كانت الورقة التي تحتوي على هذه البيانات موجودة * فسيتم استبدال الورقة بمعلومات الـ API * * * @param {string} resourceType نوع المصدر * @param {number} idNumber رقم التعريف الخاص بالفيلم * @param {number} episodeNumber رقم الجزء الخاص بالفيلم يستخدم هذا فقط في اسم الورقة * */ function createResourceSheet_( resourceType, idNumber, episodeNumber) { إحضار بيانات الفيلم الأساسية من الـ API // var filmData = fetchApiResourceObject_( "https://swapi.dev/api/films/" + idNumber); استخراج عناوين URL لواجهة برمجة التطبيقات لكل مورد // حتى تتمكن الشيفرة من استدعاء واجهة برمجة التطبيقات للحصول على مزيد من البيانات حول كل منها على حدة // var resourceUrls = filmData[resourceType]; إحضار كل مورد من الـ API على حدة // ثم دفعهم إلى قائمة كائنات جديدة // var resourceDataList = []; for(var i = 0; i < resourceUrls.length; i++){ resourceDataList.push( fetchApiResourceObject_(resourceUrls[i]) ); } الحصول على المفاتيح المستخدمة للإشارة إلى كل جزء من البيانات داخل الموارد // ويُفترض أن تكون المفاتيح متطابقة لكل كائن // نظرًا لأنها جميعها من نفس نوع المورد // var resourceObjectKeys = Object.keys(resourceDataList[0]); إنشاء الورقة بالاسم المناسب // وتصبح الورقة النشطة تلقائيًا بعد إنشائها // var resourceSheet = createNewSheet_( "شخصيات " + episodeNumber); إضافة بيانات الـ API إلى الورقة الجديدة // باستخدام كل مفتاح كائن كرأس عمود // fillSheetWithData_(resourceSheet, resourceObjectKeys, resourceDataList); تنسيق الورقة الجديدة باستخدام نفس الأنماط التي تطبقها عناصر قائمة المخصصة "تنسيقات سريعة" // وتعمل كل هذه التوابع على الورقة النشطة // التي تم إنشاؤها للتو // formatRowHeader(); formatColumnHeader(); formatDataset(); } سادسًا، أضف الدوال المساعدة التالية إلى نهاية ملف مشروع النص البرمجي "API.gs": /** الدالة المساعدة التي تسترد كائن JSON * الذي يحتوي على استجابة من واجهة برمجة تطبيقات عامة * * * @param {string} url عنوان الرابط لكائن واجهة برمجة التطبيقات الذي يتم جلبه * @return {object} resourceObject كائن جيسون الذي تم جلبه من طلب الـ URL إلى الـ API * */ function fetchApiResourceObject_(url) { تقديم طلب إلى الـ API والحصول على رد // var response = UrlFetchApp.fetch(url, {'muteHttpExceptions': true}); تحليل وإرجاع الاستجابة ككائن JSON // var json = response.getContentText(); var responseObject = JSON.parse(json); return responseObject; } /** الدالة المساعدة التي تقوم بإنشاء ورقة * أو إرجاع ورقة موجودة بنفس الاسم * * * @param {string} name اسم الورقة * @return {object} الورقة المنشأة أو الحالية وتحمل الاسم نفسه لتصبح هذه الورقة نشطة * */ function createNewSheet_(name) { var ss = SpreadsheetApp.getActiveSpreadsheet(); إرجاع ورقة موجودة إذا كانت تحمل الاسم المحدد // وتنشيط الورقة قبل إرجاعها // var sheet = ss.getSheetByName(name); if (sheet) { return sheet.activate(); } وإلا أنشيء ورقة جديدة واضبط اسمها وأعدها // والأوراق الجديدة التي تم إنشاؤها بهذه الطريقة // تصبح الورقة النشطة تلقائيًا // sheet = ss.insertSheet(name); return sheet; } /** الدالة المساعدة التي تضيف بيانات الـ API إلى الورقة * ويتم استخدام كل مفتاح كائن كرأس عمود في الورقة الجديدة * * * @param {object} resourceSheet كائن الورقة التي تم تعديلها * @param {object} objectKeys قائمة مفاتيح الموارد * @param {object} resourceDataList قائمة كائنات موارد واجهة برمجة التطبيقات التي تحتوي على بيانات لإضافتها إلى الورقة * */ function fillSheetWithData_( resourceSheet, objectKeys, resourceDataList) { تعيين أبعاد نطاق البيانات التي يتم إضافتها إلى الورقة // var numRows = resourceDataList.length; var numColumns = objectKeys.length; الحصول على نطاق الموارد ومجموعة القيم المرتبطة بها // وإضافة صفًا إضافيًا لرؤوس الأعمدة // var resourceRange = resourceSheet.getRange(1, 1, numRows + 1, numColumns); var resourceValues = resourceRange.getValues(); عمل حلقة تكرار فوق كل قيمة ومفتاح للمورد // واستخراج البيانات ووضعها في مصفوفة قيم الموارد الثنائية // for (var column = 0; column < numColumns; column++) { ضبط رأس العمود // var columnHeader = objectKeys[column]; resourceValues[0][column] = columnHeader; قراءة وضبط كل صف في هذا العمود // for (var row = 1; row < numRows + 1; row++) { var resource = resourceDataList[row - 1]; var value = resource[columnHeader]; resourceValues[row][column] = value; } } إزالة أي بيانات موجودة في الورقة وتعيين القيم الجديدة محلها // resourceSheet.clear() resourceRange.setValues(resourceValues); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية لقد أضفت للتو الكثير من الشيفرات البرمجية، دعنا ننتقل إلى كل دالة على حدة لفهم كيفية عملها: 1. الدالة ()onOpen لقد أضفت هنا بعض العناصر الجديدة للقائمة المخصصة "تنسيقات سريعة"، لقد عينت خط فاصل ثم استخدمت التابع ()Menu.addSubMenu الذي يأخذ معامل واحد فقط، وهو"اسم القائمة الفرعية"، وذلك لإنشاء بنية قائمة متداخلة مع ثلاثة عناصر جديدة، وأضيفت العناصر الفرعية الجديدة باستخدام التابع ()Menu.addItem الذي يأخذ معاملين فقط، وهما: "اسم عنصر القائمة" و "اسم الدالة" ويكون الاسم باللغة الإنجليزية كما نوهنا سابقًا. 2. الدوال الغالفة لعناصر القائمة الفرعية المخصصة جميع عناصر القائمة الفرعية الجديدة تفعل شيئًا مشابهًا، إنهم يحاولون إنشاء ورقة جدول ببيانات سُحبت SWAPI، الاختلاف الوحيد هو أن كل دالة تركز على جزء مختلف من الفيلم. نعم سيكون من الملائم كتابة دالة واحدة فقط لإنشاء ورقة جدول البيانات، من خلال جعل الدالة تقبل معامل لتحديد الفيلم الذي يجب سحب بياناته، لكن المشكلة هنا أن التابع ()Menu.addItem لا يسمح لك بتمرير المعاملات إليه عندما تستدعيه القائمة الفرعية المخصصة، إذن كيف تتجنب كتابة نفس الشيفرة البرمجية ثلاث مرات؟ الجواب هو "الدالة الغالفة wrapper functions" وهي دوال خفيفة يمكنك الاتصال بها لكي تستدعي على الفور دالة أخرى مع ضبط معاملات محددة لها. هنا تستخدم الشيفرة البرمجية ثلاث دوال غالفة: الأولى ()createPeopleSheetIV، والثانية ()createPeopleSheetV، والثالثة ()createPeopleSheetVI، وعناصر القائمة الفرعية مرتبطة بهذه الدوال. فعند النقر على أحد عناصر القائمة الفرعية، تعمل الدالة الغالفة على استدعاء دالة منشئ الورقة الرئيسية على الفور ()_createResourceSheet، لتمرير المعاملات المناسبة لعنصر القائمة الفرعية، وتحديدًا ثلاثة معاملات، هم: "نوع المصدر" و "رقم معرف الفيلم" و "رقم جزء الفيلم"، وينتج عن هذا الإجراء إنشاء ورقة جدول بيانات مليئة ببيانات الشخصيات الرئيسية من أحد أجزاء فيلم "Star Wars". 3. الدالة (createResourceSheet_(‎ هذه هي دالة بناء ورقة جدول البيانات الرئيسية لهذا التمرين، فبمساعدة بعض الدوال المساعدة تحصل على بيانات من SWAPI، ثم تنشئ ورقة جدول بيانات جديدة، ثم تكتب بيانات الواجهة API في الورقة، ثم تنسق الورقة باستخدام الدوال التي أنشأتها في الأقسام السابقة من هذا المقال، وإليك التفاصيل: بدايةً، تستخدم الدالة ()_fetchApiResourceObject التي تأخذ معامل واحد فقط، وهو: "الرابط"، وذلك لتقديم طلب إلى SWAPI لاسترداد معلومات الفيلم الأساسية، وتتضمن استجابة واجهة برمجة التطبيقات SWAPI مجموعة من الروابط التي يمكن أن تستخدمها الشيفرة البرمجية للحصول على مزيد من التفاصيل حول أشخاص محددين (يُعرفون هنا باسم resources) من الأفلام، تجمع الشيفرة البرمجية كل شيء في المصفوفة ResourceUrls. بعد ذلك تستخدم الشيفرة البرمجية ()_fetchApiResourceObject لتكرار استدعاء الـ API لكل رابط في المصفوفة ResourceUrls، وتُخزن النتائج في المصفوفة ResourceDataList، وكل عنصر في هذه المصفوفة هو كائن يصف شخصية مختلفة من الفيلم. تحتوي البيانات التي خُزنت في المصفوفة ResourceDataList على العديد من المفاتيح العامة التي عُينت لمعلومات حول الشخصيات التي مثلت في هذا الفيلم، فعلى سبيل المثال: يرمز المفتاح "name" إلى اسم الشخصية في الفيلم، ونحن نفترض أن أسماء المفاتيح لكل كائن بيانات متطابقة مع نوع البيانات بداخلها، لأنها تهدف إلى استخدام هياكل بيانات مشتركة، ولأننا سوف نحتاج إلى قائمة المفاتيح لاحقًا، لذلك تخزن الشيفرة البرمجية قائمة المفاتيح في المتغير ResourceObjectKeys باستخدام التابع من لغة جافا سكريبت ()Object.keys. بعد ذلك تستدعي دالة البناء الدالة المساعدة ()_createNewSheet التي تأخذ معامل واحد فقط، وهو: "اسم الورقة"، وذلك لإنشاء الورقة التي سوف توضع البيانات الجديدة بداخلها، ويؤدي استدعاء الدالة المساعدة أيضًا إلى تنشيط الورقة الجديدة. بعد إنشاء الورقة تُستدعى الدالة المساعدة ()_fillSheetWithData التي تأخذ ثلاث معاملات، هم: "الورقة الجديدة" و "قائمة مفاتيح الكائنات" و "قائمة كائنات موارد الـ API"، وذلك لإضافة جميع بيانات الـ API إلى الورقة. أخيرًا تُستدعى جميع دوال التنسيق التي أنشأتها مسبقًا لتطبيق نفس قواعد التنسيق على البيانات الجديدة، نظرًا لأن الورقة الجديدة هي الورقة النشطة يمكن للشيفرة البرمجية إعادة استخدام هذه الدوال دون تعديل. 4: الدالة ()fetchApiResourceObject تشبه الدالة المساعدة هذه الدالة المساعدة ()_fetchBookData التي استخدمناها في المقال السابق "العمل مع البيانات"، فهي تأخذ الرابط المحدد ثم تستخدم التابع ()UrlFetchApp.fetch الذي يأخذ معاملين، هما: "الرابط" و "المعاملات"، وذلك للحصول على استجابة، ثم تُحَلل الاستجابة في كائن JSON باستخدام التابع ()HTTPResponse.getContextText وتابع جافا سكريبت (JSON.parse(json، ثم يُرجع كائن JSON الناتج. 5: الدالة ()_createNewSheet هذه الدالة المساعدة بسيطة إلى حدٍ ما، فهي تتحقق أولاً من وجود ورقة بالاسم المحدد في جدول البيانات، فإن وجدته تعمل الدالة على تنشيط الورقة وإعادتها. أما إذا لم تكن الورقة موجودة، تعمل الدالة على إنشائها باستخدام ()Spreadsheet.insertSheet الذي يأخذ معامل واحد فقط، هو: "اسم الورقة"، ثم تنشيطها وإرجاع الورقة الجديدة. 6: الدالة ()_fillSheetWithData هذه الدالة المساعدة مسؤولة عن ملء الورقة الجديدة ببيانات الـ API، فهي تأخذ كمعاملات ( الورقة الجديدة، وقائمة مفاتيح الكائنات، وقائمة كائنات موارد الـ API)، ويمثل كل مفتاح كائن عمودًا في الورقة الجديدة، ويمثل كل كائن مورد صفًا. أولاً تحسب الدالة عدد الصفوف والأعمدة المطلوبة لتقديم بيانات الـ API الجديدة وهو حجم قائمة الموارد والمفاتيح على التوالي، بعد ذلك تحدد الدالة نطاق الإخراج من خلال المتغير ResourceRange لوضع البيانات مع إضافة صف إضافي للاحتفاظ برؤوس الأعمدة، وتحتوي قيم المتغير ResourceValues على مصفوفة ثنائية مستخرجة من المتغير ResourceRange. بعد ذلك تسنخدم الدالة حلقة التكرار For عبر كل مفتاح كائن في قائمة ObjectKeys ثم يُعين المفتاح كرأس للعمود، ثم تمر حلقة تكرار For ثانية عبر كل كائن مورد، ولكل زوج (صف، عمود) تُنسخ معلومات الـ API المقابلة لهما إلى [resourceValues[row][column. تنويه: تذكر أن الصفوف والأعمدة في "جداول البيانات" تبدأ فهرستها بالرقم "1"، بينما مصفوفات جافا سكريبت تبدأ فهرستها بالرقم "0"، وبسبب هذا الاختلاف غالبًا ما نضطر إلى إضافة أو طرح "1" من الفهارس عند البرمجة في Apps Script. بعد ملء المتغير ResourceValues بالبيانات، تُمسح ورقة الوجهة باستخدام ()Sheet.clear في حالة احتوائها على بيانات من نقرات على عنصر القائمة الفرعية. أخيرًا تُكتب القيم الجديدة في الورقة. النتائج يمكنك رؤية نتائج عملك عن طريق تنفيذ ما يلي: إذهب إلى جداول بيانات جوجل الذي نتدرب عليه "تنسيق البيانات" ثم انقر على القائمة "تنسيقات سريعة" في شريط القوائم، ثم اختر منها القائمة الفرعية "أبطال ثلاثية حرب النجوم" ثم اختر من القائمة المنبثقة "الجزء الرابع" . يجب أن تبدو النتائج كما يلي: تهانينا، لقد كتبت الآن شيفرة برمجية لاستيراد البيانات من API إلى جداول البيانات وتنسيقها تلقائيًا، لكن هل لاحظت أن الورقة اتجاه عرضها من اليسار إلى اليمين؟ إن كان الأمر مناسبًا لك فلا بأس، أما إن كنت تريد اتجاه عرض الورقة يكون من اليمين إلى اليسار فكل ما عليك فعله هو إضافة الثلاثة أسطر التالية إلى شيفرتك البرمجية: تحويل اتجاه عرض ورقة جدول البيانات إلى: من اليمين إلى اليسار // const ss = SpreadsheetApp.getActiveSpreadsheet(); ss.getSheets().forEach(s => s.setRightToLeft(true)); نعم، أحيّك على انتباهك معي، أنا بالفعل لم أذكر لك أين تضع هذه الأسطر الثلاثة في شيفرتك البرمجية، لذلك اعتبر هذا الأمر بمثابة تدريب لك، فقط سوف أسهل عليك الأمر وأعطيك تلميح "الدوال الغالفة". الآن أريد منك استخدم هذه الأسطر الثلاثة في شيفرتك البرمجية لتصبح النتيجة النهائية تبدو كما يلي: خاتمة وإلى هنا نكون قد وصلنا إلى نهاية هذا المقال من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه كيفية تطبيق عمليات تنسيق جداول البيانات المختلفة باستخدام Apps Script، وكيفية إنشاء قوائم فرعية باستخدام الدالة ()onOpen، وكيفية تنسيق قائمة كائنات JSON التي جلبناها في ورقة جديدة من البيانات باستخدام Apps Script. وفي المقال القادم سوف نتعلم كيفية استخدام Apps Script لتصور البيانات في مخطط، ثم تصدير هذه المخططات إلى برنامج العروض التقديمية من جوجل. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا المقال السابق: كيفية استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Script أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script

مرحبًا بك في المقال الرابع من دليل تعلم أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، فبعد إكمالك لهذا المقال سوف يصبح لديك المعرفة في كيفية استرداد بيانات لواجهة برمجة تطبيقات API عامة في Apps Script لتحسين تجربة جداول البيانات. وسوف نستمر في العمل مع فئات SpreadsheetApp، و Spreadsheet، و Sheet، و Range التي تعرفنا عليها في المقالات السابقة من هذا الدليل. هذا هو المقال الرابع في دليل تعلم أساسيات برمجة التطبيقات مع جداول بيانات جوجل، وقبل البدء تأكد من إكمال المقالات السابقين: أساسيات برمجة التطبيقات Apps Script. جداول البيانات والأوراق والنطاقات. العمل مع البيانات. ماذا ستتعلم كيفية سحب بيانات كائن JSON ومعالجتها من مصدر API عام. كتابة بيانات الـ API في جدول بيانات ماذا ستحتاج فهم موضوعات Apps Script الأساسية التي استكشفناها في المقالين السابقين من هذا الدليل. الإلمام الأساسي بمحرر الشيفرات البرمجية Apps Script. الإلمام الأساسي بجداول بيانات Google. الإلمام الأساسي بلغة البرمجة JavaScript وصنف 'String' الخاص به. الإعداد للعمل هذا المقال يعتبر استكمالاً للمقال السابق "العمل مع البيانات"، وستتعلم فيه كيفية زيادة تحسين مجموعة البيانات الموجودة داخل جدول البيانات الذي أنشأته باسم "معالجة البيانات والقوائم المخصصة"، فسوف تعمل على ملء الخلايا الفارغة داخل هذا الجدول ببيانات مستمدة من واجهة برمجة تطبيقات عامة API. لذلك سوف نستكمل التدريبات في هذا المقال باستخدام جدول البيانات "معالجة البيانات والقوائم المخصصة"، ومشروع Apps Script الذي أنشأناه باسم "Data Manipulation and Custom Menus" أيضًا، فإن كنت متابع لهذه السلسلة من البداية فليس مطلوب منك عمل أي شيء، فقط استكمل تنفيذ التدريبات الموجودة بهذا المقال باستخدام جدول البيانات "معالجة البيانات والقوائم المخصصة" الذي استخدمته في المقال السابق "العمل مع البيانات". أما إن كنت غير متابع لهذه السلسلة من بدايتها، فأنت قد فاتك ثلاث مقالات فقط من هذه السلسلة، لذلك أنصحك بالاطلاع على هذه المقالات الثلاثة، أو على الأقل الاطلاع على المقال الثالث "العمل مع البيانات" حتى تتمكن من فهم تسلسل هذا المقال وتنفيذ التدريبات المضمنة به. نظرة عامة: الحصول على البيانات من واجهات برمجة التطبيقات العامة API لقد نجحت حتى الآن في تحسين مجموعة البيانات الخاصة بك لإصلاح بعض مشكلات تنسيق العنوان والمؤلف، لكن مجموعة البيانات لا تزال تفتقد بعض المعلومات كما هو موضح أدناه: سوف تحتاج للحصول على البيانات المفقودة إلى مصدر آخر، ويمكنك عمل ذلك في Apps Script عن طريق طلب معلومات من واجهات برمجة التطبيقات الخارجية API التي يمكنها توفير بيانات إضافية. وتعد "واجهات برمجة التطبيقات API" خدمة يمكن للبرامج والسكربتات الاتصال بها لطلب معلومات أو لاتخاذ إجراءات معينة، ونحن في هذا القسم من المقال سنعمل على الاتصال بواجهة برمجة تطبيقات متاحة للجمهور لطلب معلومات الكتب التي يمكنك إدراجها في الخلايا الشاغرة بورقة جدول البيانات الخاصة بك. وسوف يعلمك هذا القسم كيفية: طلب بيانات الكتاب من مصدر خارجي لواجهة برمجة التطبيقات. استخراج معلومات العنوان والمؤلف من البيانات التي تم إرجاعها ووضعها في الخلايا الشاغرة بجدول البيانات الخاص بك. إحضار البيانات الخارجية باستخدام UrlFetch سوف تأخذ الدالة المساعدة ()_fetchBookData معاملًا واحدًا هو رقم ISBN أو الرقم العالمي الموحد للكتاب وهو مكون من 13 رقمًا كمعامل، ثم تتصل بواجهة برمجة التطبيقات العامة "Open Library API" ثم تعيد بيانات حول هذا الكتاب في كائن JSON. التطبيق يمكنك إنشاء هذه الدالة المساعدة بإضافة الدالة التالية إلى نهاية مشروع النص البرمجي في محرر Apps Script: /** دالة مساعدة لاسترداد بيانات الكتب * من واجهة برمجة التطبيقات العامة "Open Library API" * * * @param {number} ISBN - الرقم العالمي الموحد للكتاب الذي تريد العثور عليه * @return {object} بيانات الكتاب بتنسيق جيسون */ function fetchBookData_(ISBN){ الاتصال بواجهة برمجة التطبيقات العامة API // var url = "https://openlibrary.org/api/books?bibkeys=ISBN:" + ISBN + "&jscmd=details&format=json"; var response = UrlFetchApp.fetch( url, {'muteHttpExceptions': true}); تقديم طلبًا إلى API والحصول على استجابة قبل هذه النقطة // var json = response.getContentText(); var bookData = JSON.parse(json); إرجاع البيانات التي نهتم بها فقط // return bookData['ISBN:' + ISBN]; } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية تنقسم هذه الشيفرة البرمجية إلى قسمين رئيسيين: 1. طلب API في السطرين الأولين تتصل الدالة ()_fetchBookData بواجهة برمجة التطبيقات العامة "Open Library API" باستخدام نقطة نهاية عنوان URL لواجهة برمجة التطبيقات API، وخدمة جلب عنوان URL لبرمجة التطبيقات Apps Script. المتغير url هو مجرد عنوان ويب يشير إلى موقع على خوادم Open Library، ويتضمن هذا المتغير ثلاثة معاملات، هي: bibkeys و jscmd و format، تخبر خوادم Open Library بالمعلومات التي تطلبها وكيفية هيكلة الاستجابة، ففي مثالنا أنت تقدم رقم ISBN أو الرقم العالمي للكتاب وتطلب عرض معلومات مفصلة عنه بتنسيق JSON. بمجرد إنشاء سلسلة URL تُرسل الشيفرة البرمجية طلبًا إلى الموقع ويتلقى ردًا، ويحدث ذلك باستخدام التابع (UrlFetchApp.fetch(url, params يرسل طلب معلومات إلى عنوان URL الخارجي الذي تقدمه ويخزن الاستجابة الناتجة في المتغير response بالإضافة إلى عنوان URL، وتعيّن الشيفرة البرمجية المعامل الاختياري "muteHttpExceptions" إلى القيمة "true"، ويعني هذا الإعداد أن الشيفرات البرمجية الخاصة بك لن تتوقف إذا نتج عن الطلب خطأ في واجهة برمجة التطبيقات، وبدلاً من ذلك تُرجع استجابة الخطأ. يُرجع الطلب كائن HTTPResponse يُخزن في المتغير response، ويتضمن الكائن HTTPResponse معرف الاستجابة ورؤوس HTTP ومحتوى الاستجابة الرئيسي، أما المعلومات ذات الأهمية هنا في محتوى JSON الرئيسي، لذلك يجب على الشيفرة البرمجية استخراج ذلك ثم تحليل JSON لتحديد موقع المعلومات المطلوبة وإرجاعها. 2. تحليل استجابة API وإرجاع المعلومات التي تهمك في الأسطر الثلاثة الأخيرة من الشيفرة البرمجية، يعمل التابع ()HTTPResponse.getContentText على إرجاع المحتوى الرئيسي من المتغير response كسلسلة بتنسيق JSON، ثم يعمل التابع (JSON.parse(jsonString على تحويل سلسلة JSON إلى كائن JavaScript إذ يمكن استخراج أجزاء مختلفة من البيانات بسهولة. أخيرًا تعمل الدالة على إرجاع البيانات المقابلة لرقم ISBN أو الترقيم العالمي للكتاب. النتائج الآن بعد أن نفذت الدالة ()_fetchBookData يمكنك استخدامها للمساعدة في ملء الخلايا الشاغرة في جدول البيانات، لكن إن استخدمتها الآن سوف تحصل على رسالة خطأ لأننا لم ننشىء بعد الدالة ()fillInTheBlanks المرتبطة بالقائمة الفرعية المخصصة "ملء الخلايا الفارغة بالعنوان والمؤلف". كتابة بيانات الواجهة API في جدول بيانات يمكنك الآن إنشاء الدالة ()fillInTheBlanks التي تنفذ ما يلي: تحديد بيانات العنوان والمؤلف المفقودة ضمن نطاق البيانات النشط. استرجاع البيانات المفقودة لكتاب معين عن طريق استدعاء Open Library API باستخدام التابع ()_fetchBookData. تحديث قيم العنوان والمؤلف المفقودة في الخلايا الخاصة بهما. التطبيق يمكنك إنشاء هذه الدالة من خلال إضافة الدالة التالية إلى نهاية مشروع النص البرمجي في محرر Apps Script: /** يملأ بيانات العنوان والمؤلف المفقودة * باستخدام استدعاءات Open Library API * */ function fillInTheBlanks(){ تعريف الثوابت التي تحدد رقم فهرس أعمدة "اسم الكتاب" و "المؤلف" و "الرقم العالمي الموحد للكتاب" // في مصفوفة المتغير bookValues أدناه // var TITLE_COLUMN = 0; var AUTHOR_COLUMN = 1; var ISBN_COLUMN = 2; الحصول على معلومات الكتب الموجودة في الورقة النشطة // وتوضع البيانات داخل المصفوفة // var dataRange = SpreadsheetApp.getActiveSpreadsheet() .getDataRange(); var bookValues = dataRange.getValues(); فحص كل صف من البيانات باستثناء رؤوس الصفوف // إذا كان رقم ISBN موجودًا وكان اسم الكتاب أو المؤلف مفقودًا // فاستخدم التابع (fetchBookData_ (isbn // لاسترداد البيانات المفقودة من Open Library API // ثم املأ عمود "اسم الكتاب" أو "المؤلف" المفقودين ببياناتهم عند العثور عليهم // for(var row = 1; row < bookValues.length; row++){ var isbn = bookValues[row][ISBN_COLUMN]; var title = bookValues[row][TITLE_COLUMN]; var author = bookValues[row][AUTHOR_COLUMN]; if(isbn != "" && (title === "" || author === "") ){ الاتصال فقط بواجهة برمجة التطبيقات إذا كان لديك رقم ISBN // وكان اسم الكتاب أو المؤلف مفقودًا // var bookData = fetchBookData_(isbn); في بعض الأحيان لا تقوم واجهة برمجة التطبيقات بإرجاع المعلومات المطلوبة // في هذه الحالة لا تحاول تحديث الصف // if (!bookData || !bookData.details) { continue; } قد لا تُرجع واجهة برمجة التطبيقات عنوانًا // لذا قم بملئها فقط إذا كانت الاستجابة تحتوي على عنوان // وإذا كان عمود "اسم الكتاب" فارغًا في الورقة // if(title === "" && bookData.details.title){ bookValues[row][TITLE_COLUMN] = bookData.details.title; } قد لا تُرجع واجهة برمجة التطبيقات اسم المؤلف // لذا قم بملئها فقط إذا كانت الاستجابة تحتوي على اسم المؤلف // وإذا كان عمود "المؤلف" فارغًا في الورقة // if(author === "" && bookData.details.authors && bookData.details.authors[0].name){ bookValues[row][AUTHOR_COLUMN] = bookData.details.authors[0].name; } } } أدخل قيم بيانات الكتاب المحدثة في جدول البيانات // dataRange.setValues(bookValues); } احفظ مشروع النص البرمجي الخاص بك. مراجعة الشيفرة البرمجية تنقسم هذه الشيفرة البرمجية إلى ثلاثة أقسام: 1. قراءة معلومات الكتاب الموجودة تحدد الأسطر الثلاثة الأولى من الدالة الثوابت التي تساعد في جعل الشيفرة البرمجية أكثر قابلية للقراءة. وفي الأسطر الثلاثة التالية يُستخدم المتغير bookValues للاحتفاظ بنسخة محلية من بيانات الكتاب، ستعمل الشيفرة البرمجية على قراءة المعلومات من المتغير bookValues، واستخدام الـ API لملء المعلومات المفقودة، ثم كتابة هذه القيم مرة أخرى في جدول البيانات. 2. إحضار المعلومات المفقودة تمر حلقة التكرار For في كل صف بالمتغير bookValues للعثور على العناوين أو المؤلفين المفقودة، وذلك لتقليل عدد مرات استدعاء الواجهة API لتحسين كفاءة الشيفرة البرمجية، فلا يستدعى الـ API إلا إذا كان ما يلي صحيحًا: أن تحتوي الخلية بالعمود "الرقم العالمي الموحد للكتاب" على قيمة. أن تكون الخلية بعمود "اسم الكتاب" أو عمود "المؤلف" فارغة. فإذا تحقق الشرطان فإن الشيفرة البرمجية تستدعي واجهة التطبيقات البرمجية API باستخدام الدالة ()_fetchBookData وتُخزن النتيجة في المتغير bookData ليصبح لديك المعلومات المفقودة التي تريد إدراجها في ورقة جدول البيانات. المهمة الوحيدة المتبقية هي إضافة المعلومات بالمتغير bookData في جدول البيانات الخاص بك، ومع ذلك قد يواجهك سوء حظ بعدم احتواء Open Library API على المعلومات التي تطلبها، أو قد تواجه أحيانًا مشكلة أخرى تمنعها من توفير تلك المعلومات، فإذا افترضت أن كل طلب تقدمه لواجهة برمجة التطبيقات سينجح، فلن تكون شيفرتك البرمجية قوية بما يكفي للتعامل مع الأخطاء غير المتوقعة. وللتأكد من أن الشيفرات البرمجية الخاصة بك يمكنها معالجة أخطاء الـ API يجب أن تتحقق الشيفرة البرمجية من أن استجابة الـ API صالحة قبل محاولة استخدامها، فإنها تُجري فحصًا بسيطًا للتحقق من وجود bookData و bookData.details قبل محاولة القراءة منها، إذا كان أي منهما مفقودًا فهذا يعني أن واجهة برمجة التطبيقات لا تحتوي على البيانات التي تريدها، وفي هذه الحالة يخبر الأمر continue الشيفرة البرمجية بتخطي هذا الصف من جدول البيانات. نعم قد لا تتمكن من ملء الخلايا الشاغرة، ولكن على الأقل لن يتعطل النص البرمجي الخاص بك. 3. إعادة كتابة المعلومات المحدثة في الورقة يحتوي الجزء الأخير من الشيفرة البرمجية على فحوصات مماثلة للتحقق من أن واجهة برمجة التطبيقات (API) تعرض العنوان ومعلومات المؤلف، فتعمل الشيفرة البرمجية على تحديث مصفوفة bookValues فقط إذا كانت الخلية بعمود "اسم الكتاب" وعمود "المؤلف" فارغة، وكانت واجهة برمجة التطبيقات API تُرجع قيمة يمكنك وضعها هناك. تخرج جملة التكرار For بعد فحص جميع الصفوف في ورقة جدول البيانات، والخطوة الأخيرة هي إعادة كتابة مصفوفة bookValues المحدّثة إلى جدول البيانات باستخدام التابع ()Range.setValues. النتائج يمكنك الآن رؤية تأثيرات الدالة ()fillInTheBlanksوهي تعمل إذ ستمكنك من إكمال تنظيم بيانات الكتب الخاصة بك، فقط اذهب إلى القائمة المخصصة "قائمة الكتب" واختر منها القائمة الفرعية "ملء الخلايا الفارغة بالعنوان والمؤلف" ومن المفترض أن تكون النتيجة لديك كما في الصورة التالية: خاتمة نكون إلى هنا قد وصلنا إلى نهاية هذا المقال من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه كيفية استدعاء واجهات برمجة التطبيقات العامة API باستخدام خدمة جلب عناوين URL، وأخيرًا كيفية تحليل بيانات كائن JSON المستردة من مصدر API عام. وفي المقال القادم سوف نتعمق أكثر في كيفية تنسيق البيانات داخل جدول بيانات. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script

مرحبًا بك في المقال الثالث من دليل تعلم أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، فبعد إكمالك لهذا المقال سوف يصبح لديك المعرفة في كيفية استخدام معالجة البيانات، والقوائم المخصصة، واسترداد بيانات لواجهة برمجة تطبيقات API عامة في Apps Script لتحسين تجربة جداول البيانات. وسوف نستمر في العمل مع فئات SpreadsheetApp، و Spreadsheet، و Sheet، و Range التي تعرفنا عليها في المقال السابق من هذا الدليل. ماذا ستتعلم كيفية استيراد البيانات من جدول بيانات شخصي أو مشترك في Google Drive. كيفية إنشاء قائمة مخصصة باستخدام الدالة ()onOpen. كيفية تحليل ومعالجة قيم سلسلة البيانات في خلايا ورقة جدول بيانات جوجل. كيفية سحب بيانات كائن JSON ومعالجتها من مصدر API عام. ماذا ستحتاج فهم موضوعات Apps Script الأساسية التي استكشفناها في المقاين السابقين من هذا الدليل. الإلمام الأساسي بمحرر الشيفرات البرمجية Apps Script. الإلمام الأساسي بجداول بيانات Google. الإلمام الأساسي بلغة البرمجة JavaScript وصنف 'String' الخاص به. نزل جدول البيانات المرفق في المقال الذي سنعمل عليه وافتحه عبر درايف برفعه مباشرة أو نسخ محتوى إلى جدول سابق لديك كما شرحنا طريقة استيراد الملف في المقال الأول من هذه السلسلة. الإعداد للعمل تتطلب التدريبات في هذا المقال وجود جدولين بيانات للعمل من خلالها. فالجدول الأول عبارة عن فهرس لمكتبة تحتوي على بيانات اسم الكتاب واسم المؤلف والرقم العالمي الموحد للكتاب، وستكون وظيفة هذا الجدول كقاعدة بيانات فقط لاستيراد هذه البيانات منه، لا تقلق لقد وفرنا لك هذا الجدول بالفعل ويمكنك الحصول عليه وتنزيله من المرفقات الخاصة بهذا المقال، ثم إعادة رفعه على حسابك بجوجل درايف بأحد الطريقتان اللتان ذكرناهما في المقال الأول من هذه السلسلة. والجدول الثاني سيكون جدول فارغ ستقوم أنت بإنشائه، وستكون وظيفة هذا الجدول الاتصال بجدول قاعدة البيانات لاستيراد البيانات التي بداخله ثم تنفيذ التدريبات الخاصة بهذا المقال عليه. ولإنشاء جدول البيانات هذا اتبع الخطوات التالية: أولاً، إنشاء جدول بيانات في Google Drive، ويمكنك عمل ذلك من واجهة جوجل درايف عن طريق النقر على زر "+ جديد" أعلى يمين النافذة، ثم النقر على "جداول بيانات Google"، ويؤدي هذا الإجراء إلى إنشاء وفتح جدول البيانات الجديد، وحفظه في مجلد Drive الخاص بك. ثانيًا، انقر على عنوان جدول البيانات وغيره من "جدول بيانات بدون عنوان" إلى "معالجة البيانات والقوائم المخصصة"، يجب أن تبدو الورقة الخاصة بك كما يلي: ثالثًا، افتح محرر النصوص البرمجية لـ Apps Script بالنقر على "الإضافات" ثم اختيار "محرر تطبيقات جوجل". رابعًا، انقر على عنوان مشروع برمجة التطبيقات وغيره من "مشروع بلا عنوان" إلى "Data Manipulation and Custom Menus"، ثم انقر على زر "إعادة تسمية" لحفظ تغيير العنوان. الآن بحصولك على جدول بيانات ومشروع Apps Script فارغين فأنت على استعداد لبدء المقال، انتقل إلى القسم التالي من هذا المقال للبدء في التعرف على القوائم المخصصة. نظرة عامة: استيراد البيانات باستخدام عنصر قائمة مخصص يمنحك Apps Script القدرة على تعيين القوائم المخصصة التي يمكن أن تظهر في جداول بيانات جوجل، ويمكنك أيضًا استخدام القوائم المخصصة في "مستندات جوجل"، و "العروض التقديمية من جوجل" و "نماذج جوجل"، وعند تحديد عنصر قائمة مخصص تنشىء لها تسمية نصية وتربطها بدالة Apps Script في مشروع النص البرمجي الخاص بك، ويمكنك بعد ذلك إضافة القائمة المخصصة إلى واجهة المستخدم لكي تظهر في جداول بيانات جوجل. وعندما ينقر المستخدم على عنصر قائمة مخصص تعمل دالة Apps Script التي ربطتها بهذا العنصر على تنفيذ الشيفرة البرمجية الموجودة داخل هذه الدالة،و هذه طريقة سريعة لتشغيل دوال Apps Script دون الحاجة إلى فتح محرر الشيفرة البرمجية، كما يسمح لمستخدمي جدول البيانات الآخرين بتنفيذ الشيفرات البرمجية الخاصة بك دون الحاجة إلى معرفة أي شيء عن كيفية عمل القائمة المخصصة أو كيفية عمل Apps Script، فبالنسبة لهم هو مجرد عنصر قائمة آخر. ويتم تعيين عناصر القائمة المخصصة في دالة التشغيل البسيطة ()onOpen والتي ستتعرف عليها في القسم التالي. الدالة ()onOpen توفر المشغلات البسيطة في Apps Script طريقة لتشغيل شيفرة Apps Script معينة استجابةً لظروف أو أحداث معينة، وعند إنشاء مشغل فإنك تحدد الحدث الذي يتسبب في إطلاق هذا المشغل وتوفر له دالة Apps Script التي يتم تشغيلها لهذا الحدث. فالدالة ()onOpen مثال على مشغل بسيط من السهل إعداده، كل ما عليك فعله هو كتابة دالة في Apps Script باسم ()onOpen ليعمل Apps Script على تشغيلها في كل مرة تفتح فيها أو تُعيد تحميل جدول البيانات المرتبط بهذه الدالة: /** دالة خاصة يتم تشغيلها عند فتح جدول البيانات لأول مرة أو إعادة تحميله * تُستخدم ()onOpen لإضافة عناصر قائمة مخصصة إلى جدول البيانات * */ function onOpen() { /* ... */ } التطبيق دعنا نبدأ في إنشاء قائمة مخصصة، استبدل الشيفرة البرمجية في مشروع Apps Script الذي أسميناه "Data Manipulation and Custom Menus" بما يلي: /** دالة خاصة يتم تشغيلها عند فتح جدول البيانات لأول مرة أو إعادة تحميله * تُستخدم ()onOpen لإضافة عناصر قائمة مخصصة إلى جدول البيانات * */ function onOpen() { var ui = SpreadsheetApp.getUi(); ui.createMenu('قائمة الكتب') .addItem('تحميل قائمة الكتب', 'loadBookList') .addToUi(); } احفظ مشروع نصك البرمجي. مراجعة الشيفرة البرمجية دعنا نراجع هذه الشيفرة البرمجية لفهم كيفية عمل الدالة ()onOpen. يستخدم السطر الأول التابع()getUi للحصول على كائن "Ui" يمثل واجهة المستخدم لجدول البيانات النشط الذي يرتبط به هذا النص البرمجي أو السكربت. تعمل الأسطر الثلاثة التالية على إنشاء قائمة مخصصة باسم "قائمة الكتب" ثم إضافة عنصر داخل هذه القائمة باسم "تحميل قائمة الكتب"، ثم إضافة هذه القائمة المخصصة إلى واجهة جدول البيانات، ونفذنا ذلك باستخدام ثلاث توابع متتالية على النحو التالي: أولاً: التابع ()createMenu والذي يأخذ معامل واحد فقط وهو "اسم القائمة المخصصة". ثانيًا: التابع ()addItem والذي يأخذ معاملين، الأول "اسم العنصر داخل القائمة المخصصة"، والثاني "اسم الدالة بالإنجليزية". ثالثًا: التابع ()addToUi وهو لا يأخذ أي معاملات. ينشئ التابع ()addItem اتصالًا بين تسمية العنصر الموجود داخل القائمة المخصصة (تحميل قائمة الكتب) ودالة Apps Script المرتبطة بهذا العنصر loadBookList (التي لم نوفرها بعد) لتشغيلها. النتائج من محرر Apps Script انقر على زر "تنفيذ" لتشغيل هذه الدالة لترى هل ستعمل أم لا. اذهب إلى جداول بيانات جوجل ثم أعد تحميل جدول البيانات. أعد فتح محرر النص البرمجي مرة أخرى. بعد إعادة تحميل جدول البيانات، يجب أن تظهر لك قائمة جديدة باسم "قائمة الكتب" في شريط القوائم. من خلال النقر على "قائمة الكتب"، يمكنك رؤية القائمة الفرعية "تحميل قائمة الكتب". في القسم التالي من هذا المقال سوف ننشىء الشيفرة البرمجية للدالة ()loadBookList التي تقدم طريقة واحدة يمكنك من خلالها التفاعل مع البيانات في Apps Script، وهي: قراءة البيانات من جداول البيانات الأخرى. استيراد بيانات جدول البيانات الآن بعد أن أنشأت قائمة مخصصة، يمكنك إنشاء دوال يمكن تشغيلها من خلال النقر فوق عنصر القائمة المخصصة، لكن في الوقت الحالي تحتوي القائمة المخصصة التي أنشأناها "قائمة الكتب" على عنصر قائمة واحد "تحميل قائمة الكتب" والدالة ()loadBookList التي من المفترض أن تعمل عند تحديد عنصر القائمة المخصصة تحميل قائمة الكتب غير موجودة في الشيفرة البرمجية الخاص بك، لذلك عند النقر عليها لفتحها سوف يؤدي هذا الإجراء إلى حدوث خطأ. ويمكنك إصلاح هذا الخطأ عن طريق كتابة الشيفرة البرمجية للدالة ()loadBookList. التطبيق الآن أنت في حاجة إلى أن يملأ عنصر القائمة الجديد جدول البيانات الحالي ببيانات لتتمكن من العمل معها، لذلك يجب عليك توفير الشيفرة البرمجية للدالة ()loadBookList لتتمكن من تنفيذ قراءة بيانات الكتب من جدول بيانات آخر، ثم نسخها في هذا الجدول، افتح المشروع الذي أنشأناه في Apps Script باسم "Data Manipulation and Custom Menus"، ثم أضف الشيفرة البرمجية التالية بعد الدالة ()onOpen: /** دالة خاصة يتم تشغيلها عند الضغط على القائمة المخصصة "تحميل الكتب" * تنشئ قائمة كتب نموذجية مقدمة من فهرس مكتبة وفرناها لك * */ function loadBookList(){ هذا السطر يجلب الورقة النشطة // var sheet = SpreadsheetApp.getActiveSheet(); الحصول على البيانات من جدول بيانات مختلف من Google Drive // باستخدام معرف جدول البيانات // var bookSS = SpreadsheetApp.openById( "spreadsheet-id" ); الحصول على الورقة ونطاق البيانات وقيم جدول البيانات // المخزنة في المتغير bookSS // var bookSheet = bookSS.getSheetByName("فهرس المكتبة"); var bookRange = bookSheet.getDataRange(); var bookListValues = bookRange.getValues(); إضافة هذه القيم إلى الورقة النشطة في جدول البيانات الحالي // سوف يؤدي هذا إلى الكتابة فوق أية قيم موجودة بالفعل // sheet.getRange(1, 1, bookRange.getHeight(), bookRange.getWidth()) .setValues(bookListValues); إعادة تسمية الورقة الوجهة // وتغيير حجم أعمدة البيانات لتسهيل القراءة // sheet.setName("قائمة الكتب"); sheet.autoResizeColumns(1, 3); } احفظ مشروع النص البرمجي الخاص بك. انتبه إلى تبديل قيمة spreadsheet-id الذي يأخذه التابع openById()‎ بمعرّف جدول البيانات المرفق "فهرس المكتبة" بعد رفعه على حسابك بجوجل درايف، وقد شرحنا في المقال الثاني من هذه السلسلة كيفية جلب هذا المعرِّف. مراجعة الشيفرة البرمجية إذًا كيف تعمل هذه الدالة؟ تستخدم الدالة ()loadBookList توابع من أصناف Spreadsheet و Sheet و Range التي تعرفنا عليها في المقال السابق، فمع وضع هذه المفاهيم في الاعتبار يمكنك تقسيم الشيفرة البرمجية للدالة ()loadBookList إلى الأقسام الأربعة التالية: 1. تحديد الورقة الوجهة يُستخدم السطر الأول ()SpreadsheetApp.getActiveSheet للحصول على مرجع إلى كائن الورقة الحالية، ثم تخزينه في المتغير sheet، وهذه هي الورقة التي سيتم نسخ البيانات إليها. 2. تحديد مصدر البيانات تحدد الأسطر القليلة التالية أربعة متغيرات تشير إلى بيانات المصدر التي سوف تقوم باستردادها: يخزن المتغير bookSS مرجعًا لجدول البيانات الذي تقرأ الشيفرة البرمجية البيانات منه، فتعثر الشيفرة البرمجية على جدول البيانات من خلال مُعرف جدول البيانات الخاص به، وفي هذا المثال قدمنا مُعرف جدول بيانات للقراءة منه، وفتحنا جدول البيانات من خلال استخدام التابع (SpreadsheetApp.openById(id. يخزن المتغير bookSheet مرجعًا إلى ورقة داخل المتغير bookSS تحتوي على البيانات التي تريدها، وتحدد الشيفرة البرمجية الورقة المراد قراءتها من خلال اسمها، وهو في مثالنا "فهرس المكتبة". يخزن المتغير bookRange مرجعًا لمجموعة من البيانات في المتغير bookSheet، ويعمل التابع ()Sheet.getDataRange على إرجاع النطاق الذي يحتوي على جميع الخلايا غير الفارغة في الورقة، إنها طريقة سهلة للتأكد من حصولك على نطاق يغطي جميع البيانات في ورقة دون تضمين صفوف وأعمدة فارغة. المتغير bookListValues عبارة عن مصفوفة ثنائية تحتوي على جميع القيم المأخوذة من الخلايا الموجودة في المتغير bookRange، وينشئ التابع ()Range.getValues هذه المصفوفة بقراءة البيانات من الورقة المصدر. 3. نسخ البيانات من المصدر إلى الوجهة ينسخ القسم التالي من الشيفرة البرمجية بيانات المتغير bookListValues في الورقة، ثم يعيد تسمية الورقة أيضًا. يُستخدم التابع ()Sheet.getRange وهو يأخذ أربع معاملات لتحديد مكان نسخ البيانات في الورقة وهم: الأول "صف البداية" والثاني "عمود البداية" والثالث "عدد الصفوف" والرابع "عدد الأعمدة". يُستخدم التابعان ()Range.getHeight و ()Range.getWidth لقياس حجم البيانات وتحديد نطاق الوجهة بنفس الأبعاد. يعمل التابع ()Range.setValues على نسخ قيم المصفوفة الثنائية الخاصة بالمتغير bookListValues في النطاق الوجهة، مما يؤدي إلى الكتابة فوق أي بيانات موجودة بالفعل. 4. تنسيق الورقة الوجهة يُستخدم التابع ()Sheet.setName لتغيير اسم الورقة الوجهة، ونفعل ذلك بكتابة الاسم الذي نريده كمعامل للتابع، وفي مثالنا غيرنا الاسم إلى "قائمة الكتب". ويستخدم السطر الأخير التابع ()Sheet.autoResizeColumns الذي يأخذ معاملين، الأول "عمود البداية" والثاني "عدد الأعمدة"، وذلك لتغيير حجم الأعمدة الثلاثة الأولى في ورقة الوجهة، مما يتيح لك قراءة البيانات الجديدة بسهولة أكبر. النتائج اذهب إلى جداول بيانات جوجل الذي نتدرب عليه "معالجة البيانات والقوائم المخصصة" ثم أعد تحميل جدول البيانات. أعد فتح محرر النص البرمجي مرةً أخرى. بعد إعادة تحميل جدول البيانات، انقر على القائمة "قائمة الكتب" في شريط القوائم، ثم اختر منها القائمة الفرعية "تحميل قائمة الكتب". سوف تعمل الدالة ()loadBookList على جلب البيانات بنجاح. تهانينا، أصبح لديك الآن ورقة بها قائمة بعناوين الكتب والمؤلفين ودور النشر، في القسم التالي من هذا المقال ستتعلم كيفية تعديل البيانات وتحديثها في "قائمة الكتاب" هذه باستخدام معالجة السلاسل النصية والقوائم المخصصة. نظرة عامة: ترتيب البيانات داخل جدول البيانات لديك الآن معلومات الكتاب في الورقة الخاصة بك، فيشير كل صف إلى كتاب معين، ويسرد عنوانه ومؤلفه ودار النشر التي نشرته في أعمدة منفصلة، ومع ذلك يمكنك أيضًا رؤية بعض المشكلات في هذه البيانات الأولية كالتالي: بالنسبة لبعض الصفوف وضع عنوان الكتاب والمؤلف معًا في عمود "اسم الكتاب" مرتبطين إما بفاصلة أو سلسلة نصية "تأليف". تفتقد بعض الصفوف إلى عنوان الكتاب أو مؤلفه. في الأقسام التالية من هذا المقال سوف نعمل على تصحيح هذه المشكلات عن طريق ترتيب البيانات، فسوف نعمل أولاً على إنشاء دوال تقرأ عمود العنوان ثم تقسم النص عند العثور على فاصلة أو كلمة "تأليف"، ثم وضع العنوان واسم المؤلف في الأعمدة الصحيحة. وثانيًا سنكتب شيفرة برمجية تبحث تلقائيًا عن معلومات الكتاب المفقودة باستخدام واجهة برمجة تطبيقات خارجية API، لتضيف هذه المعلومات إلى جدولك. إضافة عناصر القائمة أنت في حاجة إلى إنشاء ثلاثة عناصر قائمة للتحكم في عمليات ترتيب البيانات التي سوف تنفذها. التطبيق دعنا نحدث الدالة ()onOpen لتضمين العناصر الإضافية التي ستحتاجها إلى القائمة المخصصة "قائمة الكتب"، فقط اتبع الخطوات التالية: أولًا، في مشروع Apps Script الذي باسم "Data Manipulation and Custom Menus" حدث الشيفرة البرمجية للدالة ()onOpen لتصبح مطابقة لما يلي: /** دالة خاصة يتم تشغيلها عند فتح جدول البيانات لأول مرة أو إعادة تحميله * تُستخدم ()onOpen لإضافة عناصر قائمة مخصصة إلى جدول البيانات * */ function onOpen() { var ui = SpreadsheetApp.getUi(); ui.createMenu('قائمة الكتب') .addItem('تحميل قائمة الكتب', 'loadBookList') .addSeparator() .addItem( 'افصل العنوان عن المؤلف عند أول فاصلة', 'splitAtFirstComma') .addItem( 'افصل العنوان عن المؤلف عند كلمة "تأليف"', 'splitAtLastBy') .addSeparator() .addItem( 'ملء الخلايا الفارغة بالعنوان والمؤلف', 'fillInTheBlanks') .addToUi(); } احفظ مشروع نصك البرمجي. ثانيًا، في محرر النص البرمجي Apps Script حدد اسم الدالة "onOpen" من قائمة الدوال، ثم انقر على زر "Run"، سوف يعمل هذا الإجراء على تشغيل الدالة ()onOpen لإعادة إنشاء قائمة جدول البيانات، وذلك حتى لا تضطر إلى إعادة تحميل جدول البيانات. في هذه الشيفرة البرمجية الجديدة تنشئ التابع ()Menu.addSeparator لعمل فاصل أفقي في القائمة المخصصة للحفاظ على مجموعات عناصر القائمة ذات الصلة منظمة، ثم إضافة عناصر القائمة الجديدة تحتها. النتائج اذهب إلى جداول بيانات جوجل الذي نتدرب عليه "معالجة البيانات والقوائم المخصصة"، ثم انقر على القائمة المخصصة "قائمة الكتب" من شريط القوائم لعرض عناصر القائمة المخصصة الجديدة. يؤدي النقر على هذه العناصر الجديدة إلى حدوث خطأ نظرًا لأنك لم تنشئ دوالها المقابلة، لذلك دعنا نفعل ذلك في القسم التالي. تقسيم النص على محدد الفاصلة تحتوي مجموعة البيانات التي جلبتها في جدول البيانات على بضع خلايا دُمج فيها المؤلف والعنوان بطريقة غير صحيحة في خلية واحدة باستخدام فاصلة. يُعد تقسيم السلاسل النصية إلى أعمدة منفصلة مهمة شائعة في جدول البيانات، وتوفر جداول بيانات جوجل الدالة ()SPLIT التي تقسم السلاسل النصية إلى أعمدة، ومع ذلك غالبًا ما تواجه مجموعات البيانات مشكلات لا يمكن حلها بسهولة باستخدام الدوال المضمنة في جداول البيانات، وفي مثل هذه الحالات يمكنك كتابة شيفرة برمجية في Apps Script لتنفيذ العمليات المعقدة اللازمة لتنظيم بياناتك. ابدأ في تنظيم بياناتك عن طريق تنفيذ الدالة التي تسمى ()splitAtFirstComma، فهي تفصل بين المؤلف والعنوان ثم تضعهم في خلايا كل منهما عند العثور على الفاصلة. ويجب أن تتخذ الدالة ()splitAtFirstComma الخطوات التالية: الحصول على النطاق الذي يمثل الخلايا المحددة حاليًا. التحقق مما إذا كانت الخلايا الموجودة في النطاق تحتوي على فاصلة أم لا. عند العثور على الفاصلات تُقسم الدالة السلسلة النصية إلى سلسلتين فرعيتين فقط في موقع الفاصلة الأولى هكذا: [العنوان]، [المؤلف] في حالتنا. تعيين السلاسل الفرعية كمحتويات جديدة لخلية العنوان وخلية المؤلف. التطبيق لتنفيذ هذه الخطوات لن تكتفي باستخدام نفس التوابع التي استخدمتها من قبل، ولكنك ستحتاج أيضًا إلى استخدام JavaScript لمعالجة بيانات السلسلة النصية، فقط أضف في محرر Apps Script الدالة التالية إلى نهاية مشروع النص البرمجي: /** دالة خاصة يتم تشغيلها عند الضغط على القائمة المخصصة "افصل العنوان عن المؤلف عند أول فاصلة" * عن طريق تقسيم عمود العنوان عند الفاصلة الأولى إن وجدت * */ function splitAtFirstComma(){ الحصول على النطاق النشط (المحدد حاليًا) // var activeRange = SpreadsheetApp.getActiveRange(); var titleAuthorRange = activeRange.offset( 0, 0, activeRange.getHeight(), activeRange.getWidth() + 1); الحصول على القيم الحالية لخلايا عمود العنوان المحدد // هذه مصفوفة ثنائية الاتجاه // var titleAuthorValues = titleAuthorRange.getValues(); تحديث القيم حيث توجد الفواصل // يفترض أن وجود الفاصلة يشير إلى نمط "العنوان، الفاصلة، المؤلف" // for (var row = 0; row < titleAuthorValues.length; row++){ var indexOfFirstComma = titleAuthorValues[row][0].indexOf("، "); if(indexOfFirstComma >= 0){ في حالة العثور على فاصلة // يتم تقسيم القيم وتحديثها بالمصفوفة // var titlesAndAuthors = titleAuthorValues[row][0]; تحديث قيمة العنوان بالمصفوفة // titleAuthorValues[row][1] = titlesAndAuthors.slice(indexOfFirstComma + 2); تحديث قيمة المؤلف بالمصفوفة // titleAuthorValues[row][0] = titlesAndAuthors.slice(0, indexOfFirstComma); } } وضع القيم المحدثة مرة أخرى في جدول البيانات // titleAuthorRange.setValues(titleAuthorValues); } احفظ بعدها مشروع النص البرمجي الخاص بك. مراجعة الشيفرة البرمجية دعنا نراجع الشيفرة البرمجية الجديدة التي تتكون من ثلاثة أقسام رئيسية: 1. استرجاع قيم العنوان المميزة تحدد الأسطر الثلاثة الأولى ثلاثة متغيرات تشير إلى البيانات الحالية في الورقة: يمثل المتغير activeRange النطاق الذي حدده المستخدم حاليًا عند استدعاء الدالة ()splitAtFirstComma. يمثل المتغير titleAuthorRange نطاقًا جديدًا يغطي نفس الخلايا مثل المتغير activeRange، ولكنه يتضمن أيضًا عمودًا إضافيًا إلى اليسار، وتحتاج الشيفرة البرمجية إلى هذا النطاق الموسع لأنه يحتاج إلى مكان لوضع المؤلف الذي يعثر عليه في عمود العنوان. يمثل المتغير titleAuthorValues مصفوفة ثنائية من البيانات المستخرجة من المتغير titleAuthorRange باستخدام التابع ()Range.getValues. 2. فحص كل عنوان وتقسيم النص عند أول فاصلة يُعثر عليها يفحص القسم التالي القيم الموجودة في المتغير titleAuthorValues للعثور على الفواصل، ولتنفيذ ذلك يستخدم حلقة التكرار For بلغة البرمجة JavaScript لفحص كل القيم في العمود الأول من المتغير titleAuthorValues، وعندما يعثر على سلسلة فرعية فاصلة (" ،") باستخدام التابع ()indexOf من لغة JavaScript، تعمل الشيفرة البرمجية على تنفيذ ما يلي: نسخ قيمة السلسلة النصية للخلية إلى المتغير titleAndAuthors. تحديد موقع الفاصلة باستخدام التابع ()indexOf من لغة JavaScript. استدعاء التابع ()slice من لغة JavaScript مرتين للحصول على السلسلة الفرعية قبل الفاصلة المحدِّد والسلسلة الفرعية بعد الفاصلة المحدِّد. تُنسخ السلاسل الفرعية مرة أخرى إلى المصفوفة الثنائية داخل المتغير titleAuthorValues، ثم الكتابة فوق القيم الموجودة في هذا الموضع. 3. نسخ القيم الجديدة مرة أخرى إلى الورقة بمجرد فحص جميع قيم خلية العنوان تنسخ المصفوفة المحدثة titleAuthorValues مرة أخرى إلى جدول البيانات باستخدام التابع ()Range.setValues. النتائج يمكنك الآن رؤية تأثيرات الدالة ()splitAtFirstCommaوهي تعمل، فقط حدد أحد الخلايا التي يوجد بها عنوان الكتاب واسم المؤلف مفصول بينهما بفاصلة، ثم اذهب إلى القائمة المخصصة "قائمة الكتب" واختر منها القائمة الفرعية "افصل العنوان عن المؤلف عند أول فاصلة" ومن المفترض أن تكون النتيجة لديك كما في الصورة التالية: تحديد خلية واحدة تحديد عدة خلايا: تهانينا، لقد أنشأت الآن دالة في Apps Script تعالج البيانات في جداول البيانات، في القسم التالي سنعمل على تنفيذ دالة التقسيم الثانية. تقسيم النص على المحدد "تأليف" بالنظر إلى البيانات الأصلية بالجدول، يمكنك رؤية مشكلة أخرى في هذه البيانات وهي اجتماع عنوان الكتاب واسم المؤلف في نفس الخلية ويفصل بينهما كملة "تأليف" هكذا: [العنوان] تأليف [المؤلف]. التطبيق يمكنك حل هذه المشكلة باستخدام نفس الأسلوب الذي انتهجته في القسم السابق من هذا المقال، فالدالة ()splitAtLastBy لها وظيفة مماثلة للدالة ()splitAtFirstComma الاختلاف الحقيقي الوحيد هو أنها تبحث عن نمط نص مختلف، فقط نفذ هذه الدالة من خلال إضافة ما يلي في نهاية مشروع النص البرمجي في محرر Apps Script: /** دالة خاصة يتم تشغيلها عند الضغط على القائمة المخصصة "افصل العنوان عن المؤلف عند كلمة تأليف" * عن طريق تقسيم عمود العنوان عند كلمة "تأليف" الأخيرة إن وجدت * */ function splitAtLastBy(){ احصل على النطاق النشط (المحدد حاليًا) // var activeRange = SpreadsheetApp.getActiveRange(); var titleAuthorRange = activeRange.offset( 0, 0, activeRange.getHeight(), activeRange.getWidth() + 1); الحصول على القيم الحالية لخلايا عمود العنوان المحدد // هذه مصفوفة ثنائية الاتجاه // var titleAuthorValues = titleAuthorRange.getValues(); تحديث القيم حيث توجد السلسلة النصية "تأليف" // يفترض أن وجود كلمة "تأليف" يشير إلى نمط "العنوان، تأليف، المؤلف" // for(var row = 0; row < titleAuthorValues.length; row++){ var indexOfLastBy = titleAuthorValues[row][0].lastIndexOf(" تأليف "); if(indexOfLastBy >= 0){ في حالة العثور على كلمة "تأليف" // يتم تقسيم القيم وتحديثها بالمصفوفة // var titlesAndAuthors = titleAuthorValues[row][0]; تحديث قيمة العنوان بالمصفوفة // titleAuthorValues[row][0] = titlesAndAuthors.slice(0, indexOfLastBy); تحديث قيمة المؤلف بالمصفوفة // titleAuthorValues[row][1] = titlesAndAuthors.slice(indexOfLastBy + 7); } } وضع القيم المحدثة مرة أخرى في جدول البيانات // titleAuthorRange.setValues(titleAuthorValues); } احفظ مشروع النص البرمجي الخاص بك. مراجعة الشيفرة البرمجية هناك بعض الاختلافات الرئيسية بين هذا الشيفرة البرمجية لهذه الدالة ودالة ()splitAtFirstComma كما يلي: أولاً، نحن نبحث عن السلسلة النصية "تأليف" كمحدد سلسلة بدلاً من الفاصلة "،". ثانيًا، هنا نستخدم التابع ()lastindexOf من لغة JavaScript. بدلاً من التابع ()indexOf، وهذا يعني أنه إذا كانت هناك عدة سلاسل نصية "تأليف" في الخلية فمن المفترض أن تكون جميع السلاسل النصية "تأليف" جزءًا من العنوان وستعمل الشيفرة البرمجية على تقسيم النص عند كلمة "تأليف الأخيرة"، على سبيل المثال "كيفية تأليف كتاب تأليف مصطفى أمان" سوف تعتبر الشيفرة البرمجية كلمة "تأليف الأولى من ضمن عنوان الكتاب وتقسم النص بداية من كلمة "تأليف" الثانية. ثالثًا، بعد تقسيم السلسلة النصية، تُعيَّن السلسلة النصية الأولى كعنوان والثانية كمؤلف. النتائج يمكنك الآن رؤية تأثيرات الدالة ()splitAtLastByوهي تعمل، فقط حدد أحد الخلايا التي يوجد بها عنوان الكتاب واسم المؤلف مفصول بينهما بكلمة "تأليف"، ثم اذهب إلى القائمة المخصصة "قائمة الكتب" واختر منها القائمة الفرعية "افصل العنوان عن المؤلف عند كلمة تأليف" وأخبرنا في التعليقات بالنتيجة التي حصلت عليها. تهانينا، يمكنك الآن استخدام Apps Script لقراءة بيانات السلسلة النصية وتعديلها في ورقة جدول البيانات، واستخدام القوائم المخصصة لتنفيذ أوامر Apps Script المختلفة. خاتمة نكون إلى هنا قد وصلنا إلى نهاية هذا المقال من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه كيفية استيراد البيانات من جدول بيانات جوجل، كيفية إنشاء قائمة مخصصة من خلال الدالة ()onOpen، كيفية تحليل ومعالجة قيم بيانات سلسلة نصية. وفي المقال القادم سوف نتعلم كيفية زيادة تحسين مجموعة البيانات هذه عن طريق ملء الخلايا الفارغة ببيانات مستمدة من واجهة برمجة تطبيقات عامة API. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script

مرحبًا بك في المقال الثاني من دليل تعلم أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل، ففي المقال السابق ركزنا على مفاهيم محرر السكربت ووحدات الماكرو والدوال المخصصة، أما في هذا الدرس سوف نتعمق في خدمة جداول البيانات التي يمكنك استخدامها لقراءة البيانات وكتابتها ومعالجتها في جداول بيانات Google. هذا هو الدرس الثاني في دليل تعلم أساسيات برمجة التطبيقات مع جداول بيانات جوجل، وقبل البدء تأكد من إكمال المقال الأول: وحدات الماكرو والدوال المخصصة. ماذا ستتعلم كيف تُمَثَّل جداول البيانات والأوراق والنطاقات في برمجة التطبيقات Apps Script. كيفية الوصول إلى جدول البيانات النشط (المفتوح) وإنشائه وإعادة تسميته باستخدام صنف SpreadsheetApp و Spreadsheet. كيفية تغيير اسم الورقة، واتجاه العمود/ الصف للنطاق باستخدام صنف Sheet. كيفية تحديد مجموعة من الخلايا أو نطاق من البيانات وتنشيطها ونقلها وفرزها باستخدام صنف Range. ماذا ستحتاج فهم موضوعات Apps Script الأساسية التي استكشفناها في الدرس السابق من هذا الدليل. الإلمام الأساسي بمحرر السكربت Apps Script. الإلمام الأساسي بجداول بيانات Google. الإلمام الأساسي بلغة البرمجة JavaScript وصنف String الخاص به. ما هي خدمة جداول البيانات؟ خدمة جداول البيانات تشتمل على أربع أصناف أساسية، هي: SpreadsheetApp، و Spreadsheet، و Sheet، و Range، ويصف هذا القسم من المقال هذه الأصناف وفيم تُستخدم من أجله. الصنف SpreadsheetApp قبل الخوض في الأصناف Spreadsheet، و Sheet، و Range يجب عليك مراجعة الصنف الأب SpreadsheetApp، فتبدأ العديد من السكربتات باستدعاء توابع الصنف SpreadsheetApp، إذ يمكنها توفير نقطة الوصول الأولية إلى ملفات Google Sheets، فيمكنك التفكير في SpreadsheetAppباعتباره الصنف الرئيسي لخدمة جداول البيانات، بالطبع لن نستكشف صنفSpreadsheetApp بالتفصيل هنا، ومع ذلك يمكنك العثور لاحقًا في هذا الدرس على أمثلة وتمارين لمساعدتك على فهم هذا الصنف. جداول البيانات والأوراق وأصنافهما جداول البيانات Spreadsheet: كمصطلح فإن جدول البيانات هو عبارة عن ملف جداول بيانات Google مخزن في Google Drive يحتوي على بيانات منظمة حسب الصفوف والأعمدة، ويشار إلى جدول البيانات أحيانًا باسم "جدول بيانات Google"، وهي الطريقة نفسها التي يُشار بها إلى المستند باسم "مستند Google". ويمكنك استخدام الصنف Spreadsheet للوصول إلى بيانات ملف جداول بيانات جوجل وتعديلها، ويمكنك أيضًا استخدام هذا الصنف لعمليات أخرى على مستوى الملف، مثل: إضافة العناوين. الورقة Sheet: تمثل الصفحة الفردية لجدول البيانات، ويشار إليها أحيانًا باسم "علامة تبويب"، ويمكن أن يحتوي كل جدول بيانات على ورقة واحدة أو أكثر. ويمكنك استخدام الصنف Sheet للوصول إلى البيانات والإعدادات على مستوى الورقة وتعديلها، مثل: نقل صفوف أو أعمدة البيانات. بالإضافة إلى الاسم، تحتوي جداول البيانات أيضًا على معرّف نصي (سلسلة نصية عشوائية فريدة)، هذا المعرّف موجود في عنوان URL لجدول البيانات، كما تحتوي كل ورقة في جدول البيانات أيضًا على معرّف رقمي (سلسلة رقمية عشوائية فريدة) لتلك الورقة، هذا المعرّف موجود في عنوان URL لجدول البيانات، وتنسيق المعرفين كالتالي: ويمكنك رؤية كلا المعرفين في مثال URL التالي: https://docs.google.com/spreadsheets/d/1xW0pLog0mQFVU5QCob1AHPxR7WEt1/edit#gid=3614239 لذلك، نظرًا لأن معرفات جداول البيانات والأوراق فريدة وأسماء جداول البيانات ليست كذلك، فمن الأفضل استخدام المعرفات لتحديد جداول البيانات والأوراق كلما أمكن ذلك، فعلى سبيل المثال: يمكن أن يكون لديك جداول بيانات متعددة بنفس الاسم في Google Drive، لكن باستخدام التابع (SpreadsheetApp.openById(id لفتح جداول البيانات الخاصة بك يمكنك من تجنب تحرير الملف الخطأ عن طريق الخطأ إن استعملت التابع getSheetByName(sheet_name)‎. باختصار، يعمل الصنف Spreadsheet على مجموعة الأوراق وتحديد ملف جداول بيانات جوجل في Google Drive، ويعمل الصنف Sheet على أوراق فردية داخل جدول بيانات. الصنف Range تتطلب معظم عمليات معالجة البيانات (على سبيل المثال: قراءة بيانات الخلية أو كتابتها أو تنسيقها) تحديد الخلايا التي تنطبق عليها العملية، لذلك يمكنك استخدام الصنف Range لتحديد مجموعات معينة من الخلايا داخل الورقة، ويمكنك تحديد النطاقات حسب أرقام الصفوف والأعمدة ، أو باستخدام تدوين A1. تعمل العديد من توابع الأصناف على إرجاع الكائن النشط للصنف المطلوب، فعلى سبيل المثال: يؤدي تشغيل ()SpreadsheetApp.getActiveSpreadsheet إلى إرجاع جدول البيانات النشط أو الحالي للمستخدم، وبالحصول على جدول البيانات النشط يمكنك تطبيق العمليات على جدول البيانات هذا، وبالمثل يمكن لتابع مثل ()Sheet.activate تغيير الكائن النشط. باختصار، تنشيط ورقة أو نطاق أو خلية يعادل النقر فوق تلك الورقة أو النطاق أو الخلية في واجهة جداول بيانات جوجل، وبالتالي نقل تركيز المؤشر إلى هذا الموقع. يعرض باقي هذا الدرس أمثلة على السكربتات التي تعمل مع هذه الأصناف وتوابعها. الإعداد للعمل قبل المتابعة أنت بحاجة إلى جدول بيانات يحتوي على بعض البيانات، لا تقلق فقد وفرنا لك جدول بيانات جاهز &nbsp;حول أسعار الأفوكادو يمكنك تنزيله، ثم إعادة رفعه بإحدى الطريقتين اللتين ذكرناها في المقال الأول من هذه السلسلة. يوضح لك القسم التالي من هذا المقال كيفية استخدام الصنف Spreadsheet لتحسين جدول البيانات الذي نتدرب عليه. الوصول إلى جداول البيانات وتعديلها في هذا القسم يمكنك التعرف على كيفية استخدام الصنف SpreadsheetApp والصنف Spreadsheet للوصول إلى جداول البيانات وتعديلها، وعلى وجه التحديد تعلمك هذه التمارين كيفية إعادة تسمية جدول بيانات وتكرار الأوراق داخل جدول بيانات. نعم قد تبدو هذه العمليات بسيطة، لكنها غالبًا ما تكون جزءًا من سير عمل أكبر وأكثر تعقيدًا، فبمجرد أن تفهم كيفية أتمتة هذه المهام باستخدام نص الشيفرة البرمجية أو السكربت، سيكون من الأسهل تعلم كيفية أتمتة العمليات الأكثر تفصيلًا. إعادة تسمية جدول البيانات النشط لنفترض أنك تريد تغيير الاسم الافتراضي لجدول البيانات الذي نتدرب عليه من "نسخة من جدول بيانات بدون عنوان" إلى عنوان يعكس بطريقة أفضل الغرض من جدول البيانات هذا، ويمكنك عمل بذلك باستخدام الصنف SpreadsheetApp والصنف Spreadsheet باتباع الخطوات التالية: أولاً، في محرر السكربت استبدل كتلة التعليمات البرمجية الافتراضية ()myFunction بالتعليمة البرمجية التالية: function renameSpreadsheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); mySS.rename("أسعار الأفوكادو"); } ثانيًا، احفظ شيفرتك البرمجية بالنقر على أيقونة "حفظ". ثالثًا، لإعادة تسمية مشروع Apps Script انقر على كلمة "مشروع بلا عنوان" من أعلى يمين النافذة، ثم اكتب اسم "Avocado Prices" كاسم للمشروع الجديد، ثم انقر على "إعادة تسمية". رابعًا، لتشغيل شيفرتك البرمجية، حدد الدالة renameSpreadsheet من قائمة الدوال، ثم انقر على زر "تنفيذ" من أعلى النافذة. خامسًا: أعطِ تفويضًا للماكرو باتباع الإرشادات التي تظهر على الشاشة، انقر أولاً على زر "مراجعة الأذونات". فإذا تلقيت رسالة "لم تثبت جوجل ملكية هذا التطبيق"، فانقر على ارتباط "خيارات متقدمة"، ثم انقر على ارتباط "الانتقال إلى Avocado Prices (غير آمنة)". وفي الشاشة التالية انقر على زر "سماح". سادسًا، بمجرد تنفيذ الدالة يجب أن يتغير اسم ملف جدول البيانات الخاص بك. لنلق نظرة على الشيفرة البرمجية التي أدخلتها: التابع ()getActiveSpreadsheet يعمل على إرجاع كائن يمثل جدول البيانات النشط؛ أي نسخة من جدول بيانات التمرين، وخزن كائن جدول البيانات هذا في المتغير mySS ويؤدي استدعاء (rename(newName في المتغير mySS إلى تغيير اسم ملف جدول البيانات في Google Drive إلى "أسعار الأفوكادو". ونظرًا لأن متغير mySS أصبح مرجعًا لجدول البيانات النشط، يمكنك جعل شيفرتك البرمجية أنظف وأكثر كفاءة عن طريق استدعاء توابع Spreadsheet من خلال المتغير mySS بدلًا من تكرار استدعاء ()getActiveSpreadsheet. تكرار الورقة النشطة في جدول البيانات الحالي لديك ورقة واحدة فقط، يمكنك استدعاء التابع ()Spreadsheet.duplicateActiveSheet لعمل نسخة من هذه الورقة باتباع الخطوات التالية: بداية، أضف الدالة الجديدة التالية أسفل الدالة ()renameSpreadsheet الموجودة بالفعل في مشروع Apps Script الذي أنشأته كالتالي: function duplicateAndOrganizeActiveSheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); var duplicateSheet = mySS.duplicateActiveSheet(); } احفظ شيفرتك البرمجية بالنقر على أيقونة "حفظ"، بعد ذلك، ومن أجل تشغيل شيفرتك البرمجية، عليك أن تحدد الدالة duplicateAndOrganizeActiveSheet من قائمة الدوال، ثم النقر على زر "تنفيذ" من أعلى النافذة. ارجع إلى جداول البيانات لمشاهدة إضافة علامة تبويب جديدة أو ورقة مكررة باسم "نسخة من الورقة1" إلى جدول البيانات. لنلق نظرة على الشيفرة البرمجية التي أدخلتها: في هذه الدالة الجديدة يُنشئ التابع ()duplicateActiveSheet ورقة مكررة وينشطها ثم يعيدها إلى جدول البيانات، وتُخزن هذه الورقة الناتجة في المتغير duplicateSheet، لكن الشيفرة البرمجية لم تفعل أي شيء مع هذا المتغير حتى الآن. في القسم التالي من هذا المقال، ستستخدم الصنف Sheet لإعادة تسمية وتنسيق الورقة التي كررناها. تنسيق الورقة باستخدام الصنف Sheet يوفر الصنف Sheet توابع تسمح لنَصْ الشيفرة البرمجية بقراءة الأوراق وتحديثها، في هذا القسم من الدرس يمكنك التعرف على كيفية تغيير اسم الورقة وعرض العمود باستخدام توابع من الصنف Sheet. لاحظ أن الصنف Spreadsheet والصنف Sheet يشتركان في عدة توابع خاصة بورقة محددة، مثل: (Spreadsheet.deleteColumn(columnPosition (Sheet.deleteColumn(columnPosition فعندما تستدعي (Spreadsheet.deleteColumn(columnPosition فإن هذا التابع يزيل الأعمدة المحددة من الورقة النشطة حاليًا (المفتوحة) داخل جدول البيانات النشط. ويمكنك الحصول على نفس النتيجة عن طريق استدعاء ()getActiveSheet، ومن ثمة بعد ذلك استدعاء (Sheet.deleteColumn(columnPosition، لكن الصنف Spreadsheet يوفر لك الوقت. تغيير اسم الورقة إعادة تسمية الأوراق أمر بسيط مثل إعادة تسمية جدول البيانات التي استخدمنا فيها التابع ()renameSpreadsheet، فكل ما عليك فعله هو استدعاء تابع واحد لتنفيذ هذه العملية كما يلي: أولًا، في جداول البيانات الذي نتدرب عليه باسم "أسعار الأفوكادو" انقر على التبويبة أو الورقة التي باسم "الورقة1" لتنشيطها. ثانيًا، في محرر Apps Script عَدِّل الشيفرة البرمجية للدالة ()duplicateAndOrganizeActiveSheet لكي تتطابق ما يلي: function duplicateAndOrganizeActiveSheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); var duplicateSheet = mySS.duplicateActiveSheet(); // تغيير اسم الورقة الجديدة. duplicateSheet.setName("_الورقة" + duplicateSheet.getSheetId()); } ثالثًا، احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ"، ثم انقر على زر "تنفيذ" من أعلى النافذة. رابعًا، ارجع إلى جداول البيانات لمشاهدة إضافة علامة تبويب جديدة أو ورقة مكررة وإعادة تسميتها وتنشيطها عند تشغيل الدالة: لنلق نظرة على الشيفرة البرمجية التي أدخلتها: يعمل التابع (setName(name على تغيير اسم الورقة المكررة باستخدام التابع ()getSheetID وذلك للحصول على رقم المعرف الفريد لهذه الورقة، ثم يربط عامل التشغيل (+) المعرف الرقمي للورقة بنهاية السلسلة النصية التي حددناها لاسم الورقة المكررة وهي "الورقة_". تعديل أعمدة وصفوف الورقة يمكنك أيضًا استخدام الصنف Sheet لتنسيق جدول البيانات، فعلى سبيل المثال: يمكنك تحديث وظيفة التابع ()duplicateAndOrganizeActiveSheet لتغيير حجم أعمدة الورقة المكررة وإضافة صفوف مجمدة كما يلي: في جداول البيانات الذي نتدرب عليه باسم "أسعار الأفوكادو" انقر على التبويبة أو الورقة التي باسم "الورقة1" لتنشيطها ثم عدِّل في محرر Apps Script الشيفرة البرمجية للدالة ()duplicateAndOrganizeActiveSheet لكي تتطابق ما يلي: function duplicateAndOrganizeActiveSheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); var duplicateSheet = mySS.duplicateActiveSheet(); // تغيير اسم الورقة الجديدة. duplicateSheet.setName("_الورقة" + duplicateSheet.getSheetId()); // تنسيق الورقة الجديدة. duplicateSheet.autoResizeColumns(1, 5); duplicateSheet.setFrozenRows(2); } احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ"، ثم انقر على زر "تنفيذ" من أعلى النافذة. بعدها، ارجع إلى جداول البيانات لمشاهدة إضافة علامة تبويب جديدة أو ورقة مكررة وإعادة تسميتها وتنشيطها وتنسيقها عند تشغيل الدالة. لنلق نظرة على الشيفرة البرمجية التي أدخلتها: autoResizeColumns(startColumn, numColumns) يعمل هذا التابع على تغيير حجم أعمدة الورقة لسهولة القراءة، كما يعمل التابع (setFrozenRows(rows على تجميد العدد المحدد من الصفوف (اثنان في المثال الذي معنا) مما يُبقي صفوف الرأس مرئية أثناء قيام القارئ بالتمرير لأسفل في جدول البيانات. في القسم التالي سوف تتعرف على النطاقات ومعالجة البيانات الأساسية. إعادة ترتيب البيانات باستخدام الصنف Range يوفر الصنف Range وتوابعه معظم خيارات معالجة البيانات وتنسيقها في خدمة جداول البيانات، لذلك سوف نقدم في هذا القسم من الدرس معالجة البيانات الأساسية باستخدام النطاقات، إذ ستركز هذه التمارين على كيفية استخدام النطاقات في Apps Script. وسوف نتعمق خلال الدروس القادمة من هذا الدليل في معالجة البيانات وتنسيقها. نطاقات النقل يمكنك تنشيط نطاقات البيانات ونقلها باستخدام توابع الأصناف بالإضافة إلى التدوين أو التأشير A1، وهو اختصار لتحديد مجموعات معينة من الخلايا داخل جداول البيانات، فإذا كنت بحاجة إلى التعرف عليها بنفسك يمكنك التحقق من هذا الوصف لترميز A1. دعنا نعمل على تحديث التابع ()duplicateAndOrganizeActiveSheet لنقل بعض البيانات داخل الجدول الذي نتدرب عليه كما يلي: في جداول البيانات الذي نتدرب عليه باسم "أسعار الأفوكادو" انقر على التبويبة أو الورقة التي باسم "الورقة1" لتنشيطها ثم عدِّل في محرر Apps Script الشيفرة البرمجية للدالة ()duplicateAndOrganizeActiveSheet لكي تتطابق ما يلي: function duplicateAndOrganizeActiveSheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); var duplicateSheet = mySS.duplicateActiveSheet(); // تغيير اسم الورقة الجديدة. duplicateSheet.setName("_الورقة" + duplicateSheet.getSheetId()); // تنسيق الورقة الجديدة. duplicateSheet.autoResizeColumns(1, 5); duplicateSheet.setFrozenRows(2); نقل العمود F إلى العمود C // var myRange = duplicateSheet.getRange("F2:F"); myRange.moveTo(duplicateSheet.getRange("C2")); } احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ"، ثم انقر على زر "تنفيذ" من أعلى النافذة. بعدها، ارجع إلى جداول البيانات لمشاهدة إضافة علامة تبويب جديدة أو ورقة مكررة وإعادة تسميتها وتنشيطها وتنسيقها ونقل محتويات العمود "F" إلى العمود "C" عند تشغيل الدالة. لنلق نظرة على الشيفرة البرمجية التي أدخلتها: يعمل التابع (getRange(a1Notation على تحديد نطاق البيانات المراد نقلها، وذلك من خلال استخدام طريقة التدوين A1، فقد أدخلنا "F2: F" كمعامل للتابع لتحديد العمود "F" (باستثناء الخلية F1)، فإذا كان النطاق المحدد موجودًا فإن التابع (getRange(a1Notation يُرجع مثيل هذا "النطاق" ويخزنه في متغير myRange ليسهل عملية استخدامه مرة أخرى. وبمجرد تحديد النطاق يأخذ التابع (moveTo(target محتويات المتغير myRange سواء كانت قيم أو تنسيقات لينقلها، وتحدد الوجهة (العمود C) باستخدام طريقة التدوين A1، فقد أدخلنا "C2" كمعامل للتابع لتحديد العمود "C"، وهنا قد تستعجب من أننا حددنا خلية واحدة وليس العمود بالكامل كما فعلنا بالسطر السابق، ولكي نزيل استعجابك عند نقل البيانات لا تحتاج إلى مطابقة الأحجام مع نطاقات الهدف والوجهة، لأن Apps Script بكل بساطة يعمل على تراصف القيم بنفس ترتيبها داخل الخلايا. نطاقات الفرز يتيح لك الصنف Range قراءة مجموعات الخلايا وتحديثها وتنظيمها، فعلى سبيل المثال: يمكنك فرز نطاق بيانات باستخدام التابع (Range.sort(sortSpecObj كما يلي: بداية، في جداول البيانات الذي نتدرب عليه باسم "أسعار الأفوكادو" انقر على التبويبة أو الورقة التي باسم "الورقة1" لتنشيطها ثم عدِّل في محرر Apps Script الشيفرة البرمجية للدالة ()duplicateAndOrganizeActiveSheet لكي تتطابق ما يلي: function duplicateAndOrganizeActiveSheet() { var mySS = SpreadsheetApp.getActiveSpreadsheet(); var duplicateSheet = mySS.duplicateActiveSheet(); // تغيير اسم الورقة الجديدة. duplicateSheet.setName("_الورقة" + + duplicateSheet.getSheetId()); // تنسيق الورقة الجديدة. duplicateSheet.autoResizeColumns(1, 5); duplicateSheet.setFrozenRows(2); نقل العمود F إلى العمود C // var myRange = duplicateSheet.getRange("F2:F"); myRange.moveTo(duplicateSheet.getRange("C2")); فرز جميع البيانات باستخدام العمود C (معلومات السعر) // myRange = duplicateSheet.getRange("A3:D55"); myRange.sort(3); } احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ"، ثم انقر على زر "تنفيذ" من أعلى النافذة. بعدها، ارجع إلى جداول البيانات لمشاهدة إضافة علامة تبويب جديدة أو ورقة مكررة وإعادة تسميتها وتنشيطها وتنسيقها ونقل محتويات العمود "F" إلى العمود "C" وفرز جميع البيانات الموجودة في الجدول باستخدام معلومات السعر في العمود "C" عند تشغيل الدالة. لنلق نظرة على الشيفرة البرمجية التي أدخلتها: يعمل التابع (getRange(a1Notation على تحديد نطاق جديد يغطي الخلايا "A3:D55" (الجدول بأكمله باستثناء رؤوس الأعمدة)، ثم تستدعي الشيفرة البرمجية التابع (sort(sortSpecObj لفرز الجدول، ثم أدخلنا المُعامل (3) وهي رقم العمود المطلوب الفرز وفقًا له، فيعمل التابع على فرز النطاق إذ تنتقل قيم العمود المشار إليه من الأدنى إلى الأعلى (قيم تصاعدية). ويمكن أن يؤدي التابع (sort(sortSpecObj مهام فرز أكثر تعقيدًا، لكنك لست بحاجة إليها هنا، ويمكنك عرض جميع التوابع المختلفة التي يمكنك من خلالها استدعاء نطاقات الفرز من خلال الوثائق المرجعية لتوابع الفرز. خاتمة وإلى هنا نكون قد وصلنا إلى نهاية هذا الدرس من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه كيف تُمَثَّل جداول البيانات والأوراق والنطاقات في Apps Script، كما تعرفنا على بعض الاستخدامات الأساسية للأصناف SpreadsheetApp، و Spreadsheet، و Sheet، و Range. وسوف نتعمق في الدرس القادم أكثر في كيفية قراءة البيانات وكتابتها وتعديلها داخل جدول بيانات. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل إنشاء وتصميم جداول بيانات جوجل Google Sheets

تواصل Google عملها في مهمة تسهيل الحياة اليومية على المستخدمين، فبعد أن أتاحت التطبيقات المختلفة التي لا غِنى عنها، مثل: بريد Gmail، والمستندات، وجداول البيانات، والعروض التقديمية، وذلك لمساعدة الأفراد والشركات في إنجاز أعمالهم كلها من مكان واحد ودون عناء، فقد أتاحت أيضًا أداة تُعد من أكثر أدوات الإنتاجية فعالية وهي "برمجة التطبيقات Apps Script"، فهي تتيح لك إنشاء إضافات فعالة لتطبيقات Google باستخدام مقتطفات من شيفرة JavaScript، فبضعة دقائق من كتابة الشيفرة البرمجية تمكنك من تشكيل تطبيقات جوجل إلى أدوات مخصصة لعملك. فعلى سبيل المثال: سوف تتمكن من إرسال رسائل شكر بالبريد الإلكتروني تلقائيًا باستخدام بريد Gmail، أو إضافة جهات اتصال جديدة تلقائيًا من جدول بيانات إلى جهات اتصال جوجل. ومن خلال هذا الدليل سوف نتعلم سويًّا أساسيات Apps Script وكيفية استخدامها لتحسين تجربتك في استخدام جداول بيانات جوجل. ما هو Apps Script؟ يُعد Apps Script نظامًا أساسيًا سريعًا لتطوير التطبيقات يمنحك القدرة على أتمتة المهام الخاصة بك وتخصيصها وتوسيعها. باستخدام Apps Script، يمكنك توفير الوقت والجهد من خلال تبسيط العمل الشاق أو المعقد داخل حزمة تطبيقات جوجل، وتتضمن ميزات Apps Script ما يلي: تتيح لك الخدمات المضمنة في Apps Script قراءة بيانات تطبيق Google Workspace وتحديثها ومعالجتها وذلك باستخدام "السكربت Script". يمكنك إنشاء نصوص برمجية باستخدام محرر السكربت في Apps Script وذلك من خلال المتصفح، فليست هناك حاجة لتثبيت أو تشغيل برنامج تحرير الشيفرات البرمجية. يمكنك تصميم واجهات مستخدم لتطبيقات Google Workspace مما يتيح لك تشغيل هذه التطبيقات مباشرة باستخدام عناصر القائمة ومربعات الحوار والأشرطة الجانبية. جداول البيانات يمكنك استخدام Apps Script مع جداول بيانات جوجل لتوفير الوقت والجهد، مما يسمح للنصوص بالتفاعل مع ملفات جداول بيانات جوجل والبيانات التي تحتوي عليها، ويمكنك استخدام هذه الخدمة لأتمتة مهام جدول البيانات الشائعة التالية: إنشاء أو تعديل جدول البيانات. قراءة وتحديث بيانات الخلية والصيغ والتنسيق. إنشاء أزرار وقوائم مخصصة. استيراد وتصدير البيانات من تطبيقات جوجل الأخرى أو من مصادر خارجية. المشاركة والتحكم في الوصول إلى جداول البيانات. ماذا ستتعلم يغطي هذا الدليل جميع الموضوعات التي ستحتاج إليها لبدء استخدام Apps Script مع جداول بيانات جوجل، وهي على النحو التالي: أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل. التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script. العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script. كيفية استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Script. تنسيق البيانات داخل جداول بيانات جوجل باستخدام Apps Script. الرسوم البيانية وعرضها في شرائح جوجل من خلال Apps Script. وعلى وجه التحديد، سوف يركز هذا الدليل على مفهومين أساسيين، وهما: وحدات الماكرو Macros: وهي عبارة عن سلسلة من الإجراءات المسجلة داخل جداول بيانات جوجل، وبمجرد تسجيلها يمكنك تشغيلها لتكرار هذه الإجراءات لاحقًا باستخدام عنصر قائمة أو مفتاح اختصار، ويمكنك إنشاء وتحديث وحدات الماكرو الخاصة بك في كل من "جداول بيانات جوجل" و "محرر السكربت Apps Script". الدوال المخصصة Custom Functions: في محرر السكربت يمكنك أيضًا إنشاء دوال مخصصة، وذلك على غرار الدوال المضمنة التي توفرها جداول البيانات، مثل: SUM أو AVERAGE، ويمكنك استخدام Apps Script لكتابة دوالك المخصصة لعمليات بسيطة ومتخصصة، وبمجرد إنشاؤها يمكنك استدعاء هذه الدوال في "جداول البيانات" كما تفعل مع أي دالة مضمنة، ويمكنك أيضًا استخدام الدوال المخصصة في صيغ الخلايا التي تكتبها وتجمعها مع دوال أخرى حسب الحاجة. ماذا ستحتاج الإلمام الأساسي بلغة البرمجة جافا سكريبت. الإلمام الأساسي بجداول بيانات جوجل. إنشاء ماكرو في جداول البيانات عادةً عند العمل في جداول البيانات قد تدخل في حلقة من الإجراءات المتكررة، مثل: نسخ قيم الخلية، التنسيق، إنشاء الصيغ، وما إلى ذلك، والتي يمكن أن تصبح إجراءات مملة وقد يؤدي كثرة تكرارها إلى حدوث أخطاء. ولأتمتة الإجراءات المتكررة هذه، توفر "جداول بيانات جوجل" خدمة وحدات ماكرو التي تتيح لك "تسجيل" سلسلة من الإجراءات في ورقة جدول البيانات، ثم باستخدام وحدة ماكرو مسجلة يمكنك تكرار نفس الإجراءات في أي مكان آخر في جدول البيانات بضغطة بسيطة على مفتاح الاختصار. لذلك في هذا القسم من دليل "أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل"، ستتعلم كيفية إنشاء وحدة ماكرو في "جداول البيانات"، وفي القسم التالي ستتعلم كيفية إنشاء وحدات الماكرو باستخدام Apps Script. قبل أن تبدأ قبل المتابعة أنت بحاجة إلى جدول بيانات يحتوي على بعض البيانات، لا تقلق فقد وفرنا لك جدول بيانات.zip جاهز. نزله، وبعد تنزيله واستخراجه من الملف المضغوط يمكنك تنفيذ أحد هذين الحلين: الحل الأول أن تنسخ البيانات الموجودة بملف مايكروسوفت إكسل الذي حملته من المقالة وذلك من خلال الضغط على مفتاحي Ctrl + A من لوحة المفاتيح لتحديد جميع البيانات بالملف. ثم الذهاب إلى حسابك في جوجل درايف لإنشاء جدول بيانات جوجل، وذلك من خلال إما الضغط على زر "جديد" الموجود أعلى يمين النافذة، أو من خلال النقر على زر الفأرة الأيمن ومن القائمة التي ستظهر اختر منها "جدول بيانات Google". وبعد أن يفتح الجدول تلصق به هذه البيانات التي أخذتها من ملف مايكروسوف إكسيل، وافتراضيًا يكون أسلوب عرض البيانات من اليسار إلى اليمين، ويمكنك تعديلها بالضغط على زر "ورقة من اليمين إلى اليسار" كما هو موضح بالصورة التالية. وفي النهاية أعطي اسمًا من اختيارك لهذا الجدول وذلك من خلال النقر على كلمة "جدول بيانات بدون عنوان" الموجودة أعلى يمين النافذة، ولكن ننصحك بأن تعطيه نفس اسم ملف التدريب حتى لا تتشتت أثناء الشرح. الحل الثاني أن تذهب مباشرة إلى حسابك في جوجل درايف وفي أي مكان خالي انقر بزر الفأرة الأيمن، ومن القائمة التي ستظهر اختر منها "تحميل ملف". ومن النافذة التي ستظهر لك حدد الملف من المسار الذي حملته فيه ثم اضغط على زر "Open" ليتم رفعه إلى حسابك على جوجل درايف. الآن انتبه من أمر هام، فالملف الذي رفعته هو بتنسيق "مايكروسوفت إكسيل" وبالتلي لن تجد به القائمة "إضافات" التي تمكنك من إضافة الشيفرات البرمجية لـ Apps Script لذلك يجب علينا تحويل هذا الملف إلى "جدول بيانات جوجل"، وذلك من خلال النقر على القائمة "ملف" ثم اختيار "الحفظ بتنسيق جدول بيانات Google". سوف يفتح لك الملف بتنسيق جدول بيانات جوجل في تبويبة جديدة، ويمكنك الآن حذف الملف الذي بتنسيق مايكروسوفت اكسل حتى لا يحدث لك ارتباك بين الملفين أثناء تنفيذ التدريبات. ذ سنطبق هذه العملية مع كل الجداول في هذا المقال طبعًا والمقالات اللاحقة لذا لن نكررها لاحقًا في مقالات السلسلة. أصبح الجدول الذي سنطبق عليه المقال جاهزًا حتى تتابع معنا ولا بأس من اختيار جدول آخر من اختيارك لتطبيق ما تريد. طريقة إنشاء ماكرو الآن بعد أن أصبح لديك جدول بيانات للعمل معه، يمكنك تسجيل ماكرو في جداول بيانات جوجل، ففي هذا المثال سوف ننشىء ماكرو يعمل على تنسيق صف الرأس لبياناتك، فقط ما عليك سوى اتباع هذه الخطوات: أولًا، انقر فوق الخلية "A1" لوضع المؤشر في صف الرأس لبياناتك. ثانيًا، من شريط القوائم بأعلى جدول البيانات حدد "الإضافات"، ثم اختر منها "وحدات الماكرو"، ثم اختر منها "تسجيل ماكرو". وبمجرد بدء عملية التسجيل سوف تتذكر "جداول بيانات جوجل" كل إجراء تتخذه داخل جدول البيانات، مثل: تمييز الخلايا، إضافة البيانات، التبديل إلى أوراق مختلفة، التنسيق وما إلى ذلك، وتصبح هذه الإجراءات "الشيفرة البرمجية Script" التي تتكرر بمجرد حفظ الماكرو وتنشيطه لاحقًا. ثالثًا، في مربع حوار الماكرو حدد "استخدام المراجع ذات الصلة". رابعًا، حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1". خامسًا، أعد تلوين لون التعبئة للصف العلوي من الأبيض إلى أي لون تريده. سادسًا، أعد تلوين لون نص الصف العلوي من الأسود إلى أي لون تريده. سابعًا، لتغميق النص اضغط على مفتاحي Ctrl + B من لوحة المفاتيح، أو مفتاحي Cmd + B في نظام macOS. ثامنًا، لتجميد الصف العلوي حدد القائمة "عرض"، ثم اختر منها "تجميد"، ثم اختر منها "صف واحد". أخيرًا، انقر على "حفظ" في مربع حوار الماكرو، سيطلب منك مربع حوار جديد تسمية الماكرو، أدخل أي اسم تريده لكن يُفضل أن يكون ذا دلالة على وظيفته، كما يُفضل أن تكون التسمية بالإنجليزية، على سبيل المثال: "تنسيق الصف الرئيسي" أو "HeaderFormat"، ثم انقر على "حفظ". أصبح لديك الآن ماكرو مخصص لتنسيق الصف الرئيسي، وذلك باستخدام واجهة مستخدم جداول البيانات. استخدام الماكرو الخاص بك يمكنك تطبيق الماكرو الجديد في "جداول البيانات" باتباع الإرشادات التالية: أولًا، في جدول البيانات الحالي انقر على (+) الموجودة أسفل يمين النافذة، وذلك لإضافة ورقة جديدة. ثانيا، في الورقة الجديدة أضف بعض النصوص ابتداءً من الخلية A1 إلى الخلية C2. ثالثًا، حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1". رابعًا، لتطبيق الماكرو على المنطقة المحددة، انقر على "الإضافات"، ثم اختر منها "وحدات الماكرو"، ثم اختر منها الاسم الذي أعطيته لوحدة الماكرو أثناء حفظه، وفي المثال الذي معنا سيكون باسم "تنسيق الصف الرئيسي". خامسًا، سوف يطلب منك جدول البيانات إعطاء الإذن لوحدة الماكرو لكي تتمكن من تنفيذ الشيفرة البرمجية، فقط اضغط على زر "متابعة". سادسًا، كرر الخطوة 4 لتشغيل الماكرو مرة أخرى، وذلك لأن عملية الحصول على إذن له أوقفت عملية التنفيذ. تهانينا، لقد تعلمت كيفية تطبيق وحدات الماكرو في جداول البيانات، ويجب أن يبدو جدول البيانات كما يلي: في الجزء التالي من هذا الدليل ستتعلم كيفية جعل وحدات الماكرو أكثر قوة، إليكم السر: عند تسجيل ماكرو ما تفعله حقًا هو كتابة شيفرة برمجية في Apps Script لكن من خلف الكواليس، فجداول البيانات هي التي تنشئ الشيفرة البرمجية التي تطابق إجراءات الماكرو، لذلك في القسم التالي ستتعلم كيفية تعديل الشيفرة البرمجية مباشرةً باستخدام محرر Apps Script في المتصفح. وحدات الماكرو في محرر السكربت أثناء إنشاء وحدة ماكرو تحفظ "جداول بيانات جوجل" إجراءاتك كدالة Apps Script، وعند تطبيق الماكرو تستدعي "جداول بيانات جوجل" دالة Apps Script لتطبيق هذه الإجراءات بالترتيب نفسه. محرر السكربت الآن بعد أن أنشأت وحدة ماكرو، يمكنك إلقاء نظرة على الشيفرة البرمجية الخاصة به، ولعرض الشيفرة البرمجية لهذا الماكرو انقر على "الإضافات"، ثم اختر منها "برمجة تطبيقات جوجل" لفتح محرر شيفرات البرمجة لـ Apps Script من خلال المتصفح. يتيح لك محرر السكربت كتابة التعليمات البرمجية في Apps Script وتشغيل تلك النصوص البرمجية على خوادم جوجل. تحليل الشيفرات البرمجية لوحدات الماكرو gs. أنشأت جداول البيانات ملف السكربت "macros.gs" عند تسجيل وحدة الماكرو، وملئه بدالة Apps Script التي تسمى HeaderFormat، وهو نفس الاسم الذي كتبناه أثناء حفظ وحدة الماكرو في الخطوة التاسعة من خطوات "إنشاء ماكرو"، لكن في حالة كتابة اسم الماكرو باللغة العربية ستظهر لك دالة Apps Script باسم MyFunction، لذلك أكرر عليك باستخدم التسميات الإنجليزية. انظر إلى الصورة أدناه للتعرف على بنية دالة الماكرو في Apps Script، لكن انتبه إذا سجلت الخطوات بترتيب مختلف عن الذي نفذناه هنا، أو نقرت في جدول البيانات أثناء التسجيل، فقد تبدو الشيفرة البرمجية الخاصة بك مختلفة قليلاً عن هذه. السطر الأول: عبارة عن تعليق توضيحي يؤثر على التفويض، تطلب معظم البرامج النصية من المستخدم بعض الأذونات قبل تشغيلها، وتتحكم هذه الأذونات في ما يسمح المستخدم للبرنامج النصي بتنفيذه، فعندما يكون التعليق OnlyCurrentDoc موجودًا في مشروع شيفرة برمجية، فإن Apps Script تطلب فقط الإذن للوصول إلى جدول البيانات الحالي وتحديثه، لكن بدون هذا التعليق سيطلب Apps Script إذنًا للوصول إلى جميع جداول بيانات المستخدم وتحديثها، لذلك من الأفضل دائمًا تضمين هذا التعليق التوضيحي عندما تعمل مع ملف واحد فقط، ويضيف مسجل الماكرو هذا التعليق تلقائيًا نيابة عنك. /** @OnlyCurrentDoc */ السطر الثاني: عبارة عن تحديد اسم الدالة كما ذكرنا سابقًا، ثم يلي الاسم قوسان لتمرير المُعَامل، لكن دوال الماكرو في Apps Script لا تحتاج إلى أي مُعَامل أو مدخلات، ثم يأتي في نهاية السطر القوس المعقوص الذي يحتوي جسم الدالة. function HeaderFormat() { السطر الثالث: لاحقًا في هذا الدليل سوف نتناول "الأصناف Classes" و "المفاهيم Concepts" التي ينطوي عليها إنشاء الماكرو، لكن في الوقت الحالي يمكنك الاطلاع على أوصاف الشيفرة البرمجية في هذا السطر للحصول على فكرة عامة عن مكوناته ودوره في بناء الماكرو الخاص بك، فعلى سبيل المثال: هنا يُرجع ()getActive. كائنًا يمثل ملف جدول البيانات النشط الحالي في "ورقة البيانات" ويخزنها في متغير اسمه spreadsheet. var spreadsheet = SpreadsheetApp.getActive(); السطرين الرابع والخامس: هذان السطران يتوافقان مع إجراء النقر على الصف الأول لتمييزه، وهذا الإجراء يسمى "التنشيط"، فيخزن السطر الرابع الورقة الحالية في متغير باسم sheet، بينما يحصل السطر الخامس على الصف الأول بالكامل باستخدام الـ Method أو التابع ()getRange. ثم استدعاء التابع ()activate. لتنشيطه، وحدد الصف الأول باستخدام أرقام الصفوف والأعمدة، فالاستدعاء ()spreadsheet.getCurrentCell().getRow يُرجع رقم الصف الحالي، أما الاستدعاء ()sheet.getMaxColumns يُرجع الحد الأقصى لعدد الأعمدة في الورقة. var sheet = spreadsheet.getActiveSheet(); sheet.getRange(spreadsheet.getCurrentCell().getRow(), 1, 1, sheet.getMaxColumns()).activate(); السطر السادس إلى الثامن: الاستدعاء ()getActiveRangeList. يُرجع قائمة بالنطاقات النشطة الحالية في جدول البيانات وهو الصف الأول بالكامل في مثالنا، وتعمل كل من (setBackground(color و (setFontColor(color على تغيير سمات اللون للخلايا في النطاق النشط، أما التابع (setFontWeight(fontWeight يضبط وزن الخط للخلايا في النطاق النشط. spreadsheet.getActiveRangeList().setBackground('#38761d') .setFontColor('#ffffff') .setFontWeight('bold'); السطر التاسع: يجمد هذا السطر الصف الأول من الماكرو. spreadsheet.getActiveSheet().setFrozenRows(1); هذه هي الشيفرة البرمجية التي أنشأتها عندما سجلت الماكرو الخاص بك، لا تقلق بشأن أي مصطلحات أو أساليب غير مألوفة مذكورة أعلاه، يهدف هذا التحليل للنص البرمجي إلى جعلك تفكر في بعض الأفكار التي يركز عليها Apps Script في دالة ماكرو نموذجية. تخصيص وحدات الماكرو باستخدام محرر Apps Script يعرض محرر Apps Script الماكرو الذي أنشأته مسبقًا في جداول بيانات جوجل، فمن خلال ضبط محتويات جسم "الدالة Function" يمكنك تخصيص تعليمات الماكرو لاتخاذ إجراءات مختلفة أو إضافية، وتوضح التمارين التالية طرائق مختلفة للتعامل مع وحدات الماكرو باستخدام محرر السكربت. تغيير الخلايا المستهدفة لنفترض أنك تريد تعديل الماكرو ليؤثر فقط على الأعمدة التسعة الأولى فقط من الصف الأول بدلاً من الصف بأكمله، نعم يمكنك حذف الماكرو وإعادة تسجيله، لكن باستخدام محرر Apps Script يمكنك إجراء هذه التغييرات مباشرة، وإليك طريقة واحدة للقيام بذلك: بدايةً، في محرر السكربت استبدل الاستدعاء ()sheet.getMaxColumns بالعدد "9"، يغير هذا التعديل نطاق الخلايا التي يؤثر عليها الماكرو في جدول البيانات. بعد تنفيذ التعديل ستلاحظ ظهور دائرة برتقالية بجوار "وحدات الماكرو gs." مما يشر إلى وجود تعديلات غير محفوظة، احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ". خذ نسخة جديدة من جدول البيانات "أفضل 10 أفلام لعام 2022" ثم طبق عليه وحدة الماكرو. تغيير الألوان بوحدة الماكرو لمساعدتك في تصميم نظام ألوان وحدات الماكرو أو العناصر الأخرى في "جداول البيانات"، يمكن لـ Apps Script تعديل لون تعبئة خلفية النطاق أو لون النص، اعمل من خلال الإرشادات التالية لتتعلم كيف يمكنك تخصيص ألوان الماكرو: بدايةً، افتح جدول البيانات "أفضل 10 أفلام لعام 2022"، ثم حدد الصف الأول عن طريق النقر على الخلية التي اسمها "1"، واستبدل في محرر السكربت نظام الألوان الستة عشري للخلفية من 38761d# إلى afeeee#. احفظ الشيفرة البرمجية الخاص بك بالنقر على أيقونة "حفظ"، ثم حدد من قائمة الدوال اسم الدالة التي نعمل عليها وهي HeaderFormat، ثم انقر على الزر "Run". ستجد أن جدول البيانات أُعيد تلوين الخلفية لأول 10 أعمدة في الصف الأول بلون فيروزي مخصص، واستنادًا لما تعلمته سوف أترك لك مهمة تغيير لون النص بالصف الأول من اللون الأبيض إلى اللون الأسود. في القسم التالي من هذا الدليل ستتمكن من عرض طريقة أخرى تساعدك بها Apps Script في العمل مع جداول بيانات جوجل، وهي: الدوال المخصصة. أكتب نصك البرمجي الأول: الدوال المخصصة مثل معظم تطبيقات جداول البيانات، تحتوي جداول بيانات جوجل على العديد من الدوال المضمنة مثل '()SUM=' التي تتيح إجراء عمليات حسابية سريعة على بيانات جدول البيانات، والدوال المخصصة هي ببساطة دالة تحددها باستخدام Apps Script، وبمجرد تحديد دالة مخصصة يمكنك استخدامها في أي مكان في جدول البيانات تمامًا مثل الدالة المضمنة. ويوضح لك هذا القسم كيفية إنشاء دالة مخصصة في Apps Script تقوم بإجراء تحويل نقدي. إنشاء ملف نصي باستخدام نفس جدول البيانات الذي نعمل عليه "أفضل 10 أفلام لعام 2022"، اتبع هذه الإرشادات لمعرفة كيفية إنشاء نَص برمجي جديد، والذي يمكنك استخدامه في النهاية لإنشاء أول دالة مخصصة لك: أولًا، افتح محرر السكربت كما تعلمنا. ثانيًا، بجوار القائمة "الملفات" انقر على الأيقونة (+) لإضافة ملف، ثم اختر منها "نص برمجي". ثالثًا، سمّ ملف الشيفرة البرمجية الجديد "ChangeCurrency"، ثم اضغط على مفتاح "Enter" من لوحة المفاتيح، وستلاحظ أن Apps Script يُلحق تلقائيًا الامتداد "gs." لاسم ملف الشيفرة البرمجية. الآن بعد أن أنشأت ملف شيفرة برمجية لدالة مخصصة، يمكنك ملؤه بالشيفرة البرمجية. تحويل الدولار الأمريكي إلى جنيه مصري لنفترض أنك أردت تعديل بيانات "أعلى 10 أفلام من حيث إجمالي الدخل لعام 2022" لتظهر القيم بالدولار الأمريكي والجنيه المصري، فباستخدام الدوال المخصصة يمكنك عمل ذلك بسهولة، يوضح التمرين التالي كيفية إنشاء دالة مخصصة لتحويل قيم الدولار إلى قيم الجنيه المصري رياضيًا. لكن قبل أن تتمكن من كتابة أول دالة مخصصة لك، عَدِّل مجموعة البيانات الخاصة بك للسماح للدالة بإظهار مخرجات مناسبة، ولفعل هذا نفذ الآتي. في جداول البيانات "أفضل 10 أفلام لعام 2022" انقر بزر الفأرة الأيمن على العمود "G"، ومن القائمة التي ستظهر انقر على "إدراج عمود واحد لليسار". حدد الخلية "H1" ثم أعطها هذا الاسم "الإيرادات عالميًا بالجنيه المصري". الآن أصبح لديك عمود يمكنه تخزين نتائج دالة تحويل العملة المخصصة، بعد ذلك يمكنك استخدام محرر السكربت لإنشاء أول دالة مخصصة لك. اذهب بعدها إلى المحرر وحدد الملف النصي الذي أنشأته باسم "ChangeCurrency.gs" واحذف الشيفرة البرمجية الموجودة بداخله واستبدله بالشيفرة البرمجية التالية: /** تحول الدولار الأمريكي إلى جنيه مصري * * * @param {number} dollars إجمالي الإيرادات بالدولار الأمريكي * @return {number} EGPs إجمالي المبلغ المحول إلى الجنيه المصري * @customfunction دالة مخصصة */ function USDTOEGP(dollars){ var EGP = dollars * 18.31; return EGP; } هذه هي الشيفرة البرمجية التي سوف تحول الدولار الأمريكي إلى الجنيه المصري، الآن جرب الإرشادات أدناه وشاهد كيف يمكنك تشغيل دالة مخصصة في جدول البيانات. احفظ بعد ذلك الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ" ثم اذهب إلى جدول البيانات "أفضل 10 أفلام لعام 2022"، ثم حدد الخلية "H2"، واكتب في شريط المعادلات هذه المعادلة (USDTOEGP(G2=، ثم اضغط على زرار "Enter" من لوحة المفاتيح. ولتطبيق هذه المعادلة على باقي الخلايا في العمود، اتبع التالي: حرك بعد ذلك مؤشر الفأرة إلى الزاوية السفلية اليسرى للخلية "H2" وحدد المربع الأزرق الصغير، ويجب أن يتحول مؤشر الفأرة إلى علامة (+) عند الإشارة إلى المربع الأزرق بعدها اسحب المربع الأزرق للأسفل لتحديد جميع الخلايا. تهانينا، لقد أنشأت أول دالة مخصصة لك تعمل على سرد العمود "H" تحويلات الجنيه المصري لقيم الدولار الأمريكي الموجودة في العمود "G"، وفي القسم التالي تحليل للشيفرة البرمجية لهذه الدالة. تحليل الشيفرة البرمجية للدالة المخصصة ()USDTOEGP أولًا، توضح التعليقات الأولية الغرض من الشيفرة البرمجية: /** تحول الدولار الأمريكي إلى جنيه مصري * * * @param {number} dollars إجمالي الإيرادات بالدولار الأمريكي * @return {number} EGPs إجمالي المبلغ المحول إلى الجنيه المصري * @customfunction دالة مخصصة */ تُستخدم كتل التعليقات مثل هذه في البرمجة لشرح المهمة التي تنفذها الشيفرة البرمجية، ففي هذا التعليق يمكنك تحديد جزأين من التعليقات به: الأول وصف الدالة (تحويل الدولارات إلى جنيهات)، والثاني التعليقات التوضيحية التي تصف معاملات الدالة ونوع الإرجاع. فعندما تكتب التعليقات التوضيحية يستخدم برمجة التطبيقات JSDoc لمساعدتك في توثيق وإنشاء تلميحات الإكمال التلقائي لشيفرتك البرمجية. فالتعليق param@: يستخدم لوصف كل مُعَامل تم تمريرها إلى الدالة. والتعليق return@: يستخدم لوصف ما تعيده الدالة. والتعليق customfunction@: يُخطر هذا التعليق جدول البيانات بالإكمال التلقائي لدالتك المخصصة، تمامًا كما تُكمل جداول البيانات تلقائيًا الدوال المضمنة عند إدخال اسمها في خلية، لذلك يجب عليك استخدام هذا التعليق مع أي دالة مخصصة تنشئها. ستلاحظ بالصورة أعلاه أن النص الذي يظهر في نافذة الإكمال التلقائي المنبثقة يتطابق تمامًا مع نص الوصف الذي وضعته في كتلة التعليق، يمكنك جعل دوالك المخصصة أسهل في الاستخدام عن طريق التأكد من أن الأوصاف التي تنشئها مكتوبة جيدًا وكاملة. ثانيًا، تأخذ الدالة ()USDTOEGP متغير رقمي وهي "قيمة العملة بالدولار"، ثم يضربها في سعر الصرف وهو رقم ثابت، ثم يعيد القيمة المحولة إلى الجنيه المصري في المتغير الرقمي EGP، ومُعَامل الإدخال (dollars) هي القيمة المضمنة في الخلية المحددة عند إضافة دالة مخصصة إلى خلية، ففي مثالنا تأتي مبالغ الإدخال بالدولار من العمود "G"، وتوضع قيمة الإخراج EGP في الخلية التي كُتبت بها الدالة بالعمود "H". ويمكن أن تُرجع الدوال المخصصة قيم رقمية أو سلسلة نصية، كما سترى في القسم التالي. إرجاع سلسلة نصية لنفترض أنك أردت أن يشتمل الناتج الرقمي للدالة ()USDTOEGP على بادئة تشير إلى أن العُملة المستخدم هي الجنيه المصري، يمكنك عمل ذلك في Apps Script باستخدام عامل التشغيل (+) كما هو موضح في الإرشادات التالية: أولًا، في محرر السكربت حَدِّث التعليق التوضيحي return@ لإرجاع سلسلة نصية بدلًا من رقم. ثانيًا، تعديل شيفرة الإرجاع return بالشكل التالي: return 'جنيه مصري' + EGP; يضيف عامل التشغيل (+) السلسلة النصية 'جنيه مصري' إلى مقدمة القيمة الرقمية الموجودة في EGP. ثالثًا، احفظ الشيفرة البرمجية الخاصة بك بالنقر على أيقونة "حفظ". أصبحت الآن دالتك المخصصة لا تحول الدولار الأمريكي إلى الجنيه المصري فحسب، بل تضيف أيضًا سلسلة نصية تفيد بنوع العملة المعروضة. خاتمة وإلى هنا نكون قد وصلنا إلى نهاية هذا الدرس من دليل أساسيات برمجة التطبيقات باستخدام جداول بيانات جوجل الذي تعلمنا فيه إنشاء وتعديل وحدات ماكرو والدوال المخصصة، وفي الدرس القادم سوف نتعرف على "الأصناف Classes" والمصطلحات الأساسية لخدمة جداول بيانات Apps Script التي تمكنك من التحكم بدقة في قيم البيانات وعرضها في جداول بيانات جوجل باستخدام Apps Script. نتمنى أن يكون هذا الدليل قد أضاف لكم معلومات جديدة ومفيدة، وفي حالة وجود أي استفسارات لا تترددوا في ذكرها لنا في التعليقات. اقرأ أيضًا إنشاء وتصميم جداول بيانات جوجل Google Sheets