أساسيات "برمجة تطبيقات Google" مع "جداول بيانات Google"، السلسلة 5: إنشاء رسوم بيانية وعرض البيانات في "العروض التقديمية من Google"

أساسيات "برمجة تطبيقات Google" مع "جداول بيانات Google"، السلسلة 5:
إنشاء رسوم بيانية وعرض البيانات في "العروض التقديمية من Google"

لمحة عن هذا الدرس التطبيقي حول الترميز

subjectتاريخ التعديل الأخير: سبتمبر 18, 2024
account_circleتأليف: Google Workspace Developer Relations

1. مقدمة

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

  • كيفية إنشاء رسم بياني خطي باستخدام Apps Script
  • كيفية تصدير الرسومات البيانية إلى عرض تقديمي جديد في "العروض التقديمية من Google"
  • كيفية عرض مربّعات الحوار للمستخدم في "جداول بيانات Google"

قبل البدء

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

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

المتطلبات

  • فهم مواضيع "برمجة تطبيقات Google" الأساسية التي تم استكشافها في دروس البرمجة السابقة ضمن قائمة التشغيل هذه
  • معرفة أساسية بأداة تعديل رموز برمجة التطبيقات
  • معرفة أساسية بـ جداول بيانات Google
  • إمكانية قراءة ترميز A1 في "جداول بيانات Google"
  • معرفة أساسية بلغة JavaScript وفئة String

2. إعداد

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

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

45a3e8814ecb07fc.png

  1. لفتح "محرِّر النصوص البرمجية"، انقر على الإضافات > برمجة تطبيقات Google.

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

9b9caf6c1e9de34b.png

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

3. إنشاء رسم بياني في "جداول بيانات Google" باستخدام "برمجة تطبيقات Google"

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

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

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

التنفيذ

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

يُرجى تنفيذ ما يلي:

  1. في "محرّر برمجة التطبيقات"، أضِف الدالة التالية إلى نهاية النص البرمجي Code.gs لمشروع النص البرمجي، بعد الدالة onOpen():
/**
 * Creates and inserts an embedded
 * line chart into the active sheet.
 */
function createEmbeddedLineChart() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var chartDataRange = sheet.getRange(
    'Dates and USD Exchange Rates dataset!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('USD Exchange rates')
    .setNumHeaders(1)
    .setLegendPosition(Charts.Position.RIGHT)
    .setOption('hAxis', hAxisOptions)
    .setOption("useFirstColumnAsDomain", true)
    .build();
 
  sheet.insertChart(chart);  
}
  1. احفظ مشروع النص البرمجي.

مراجعة الرموز البرمجية

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

تُعدّ السطور الأولى المتغيرات الثلاثة التالية:

  • ‫sheet: مرجع إلى ورقة البيانات النشطة الحالية.
  • chartDataRange: نطاق البيانات الذي نريد عرضه بشكل مرئي تستخدم التعليمة البرمجية تنسيق A1 لتحديد النطاق الذي يغطي الخلايا من A2 إلى F102 في ورقة باسم مجموعة بيانات التواريخ وأسعار صرف الدولار الأمريكي. من خلال تسمية الورقة تحديدًا، نتأكّد من أنّ عنصر القائمة يعمل حتى إذا كانت ورقة مختلفة نشطة لأنّ النطاق يغطي دائمًا موضع البيانات. يعني البدء من الصف 2 أنّنا سنضمّن عناوين الأعمدة وسنرسم بيانيًا فقط أحدث 100 تاريخ (صف).
  • ‫hAxisOptions: هو كائن JavaScript أساسي يتضمّن بعض معلومات الإعدادات التي يستخدمها الرمز البرمجي لضبط مظهر المحور الأفقي. على وجه التحديد، يتم ضبط تصنيفات النص على المحور الأفقي بزاوية مائلة تبلغ 60 درجة، ويتم ضبط عدد خطوط الشبكة العمودية على 12.

ينشئ السطر التالي عنصر منشئ مخطط خطي. يتم إنشاء المخططات المضمّنة في "برمجة تطبيقات Google" باستخدام نمط تصميم Builder. لا يندرج التفسير الكامل لنمط التصميم هذا ضمن نطاق هذا الدرس البرمجي، لذا عليك حاليًا فهم أنّ خدمة Spreadsheet توفّر عدة فئات EmbeddedChartBuilder. لإنشاء رسم بياني، ينشئ الرمز أولاً عنصرًا مضمّنًا لإنشاء الرسوم البيانية، ويستخدم طُرق هذا العنصر لتحديد إعدادات الرسم البياني، ثم يستدعي الطريقة build() لإنشاء العنصر النهائي EmbeddedChart. لا يعدّل الرمز البرمجي العنصر EmbeddedChart مباشرةً أبدًا، لأنّ جميع إعدادات الرسم البياني تتم إدارتها من خلال فئات أداة الإنشاء.

توفّر خدمة "جداول بيانات Google" فئة أصل EmbeddedChartBuilder وفئات إنشاء فرعية متعددة (مثل EmbeddedLineChartBuilder) موروثة منها. تسمح الفئات الفرعية لخدمة "برمجة التطبيقات" بتوفير طرق إعداد الرسم البياني التي تنطبق فقط على أنواع معيّنة من الرسوم البيانية. على سبيل المثال، يوفّر الصف EmbeddedPieChartBuilder طريقة set3D() التي تنطبق على المخططات الدائرية فقط.

في الرمز، ينشئ هذا السطر متغيّر عنصر الإنشاء lineChartBuilder:

var lineChartBuilder = sheet.newChart().asLineChart();

يستدعي الرمز البرمجي الطريقة Sheet.newChart() لإنشاء عنصر EmbeddedChartBuilder، ثم يستخدم EmbeddedChartBuilder.asLineChart() لضبط نوع أداة الإنشاء على EmbeddedLineChartBuilder.

بعد ذلك، تنشئ التعليمات البرمجية الرسم البياني باستخدام lineChartBuilder. هذا الجزء من الرمز هو مجرد سلسلة من استدعاءات الطرق لتحديد إعدادات الرسم البياني، متبوعة باستدعاء build() لإنشاء الرسم البياني. كما رأيت في دروس البرمجة السابقة، تستخدم التعليمات البرمجية تسلسل استدعاء الدوال للحفاظ على سهولة قراءة التعليمات البرمجية. في ما يلي ما تفعله استدعاءات الطُرق:

  • addRange(range): تحدّد نطاق البيانات الذي يعرضه الرسم البياني.
  • setPosition(anchorRowPos, anchorColPos, offsetX, offsetY): تحدّد مكان وضع الرسم البياني في ورقة البيانات. في هذا المثال، يُدرج الرمز الزاوية العلوية اليسرى من الرسم البياني في الخلية H5.
  • setTitle(title): تضبط عنوان الرسم البياني.
  • setNumHeaders(headers): حدِّد عدد الصفوف أو الأعمدة في نطاق البيانات التي يجب التعامل معها كعناوين. في هذه الحالة، تستخدم التعليمة البرمجية الصف الأول في نطاق البيانات كعناوين، ما يعني أنّ النص في هذا الصف يُستخدَم كتصنيفات لسلسلة البيانات الفردية في الرسم البياني.
  • setLegendPosition(position): ينقل وسيلة الإيضاح الخاصة بالرسم البياني إلى الجانب الأيسر من الرسم البياني. تستخدِم هذه الطريقة التعداد Charts.Position كمعلَمة.
  • setOption(option, value): تضبط هذه السمة خيارات المخطط المعقّد. في هذا المثال، يضبط الرمز الخيار hAxis على العنصر hAxisOptions. تتوفّر عدة خيارات يمكنك ضبطها باستخدام هذه الطريقة. تم توثيق الخيارات والقيم المحتملة لكل نوع رسم بياني في معرض الرسوم البيانية لواجهة برمجة التطبيقات Charts API. على سبيل المثال، يتم توثيق الخيارات التي يمكنك ضبطها للمخططات الخطية ضمن خيارات إعداد المخطط الخطي. الطريقة setOption(option, value) هي موضوع متقدّم، لذا ننصحك بتجنُّب استخدامها إلى أن تصبح أكثر إلمامًا بإنشاء الرسوم البيانية في "برمجة تطبيقات Google".
  • build(): تنشئ هذه الدالة عنصر EmbeddedChart وتعرضه باستخدام الإعدادات المذكورة أعلاه.

أخيرًا، يستدعي الرمز Sheet.insertChart(chart) لوضع الرسم البياني الذي تم إنشاؤه في ورقة البيانات النشطة.

النتائج

يمكنك الاطّلاع على دالة التنسيق أثناء عملها باتّباع الخطوات التالية:

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

يضع النص البرمجي الآن مخططًا جديدًا على يسار بياناتك:

bbf856699b6d2b45.gif

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

4. تصدير الرسوم البيانية إلى "العروض التقديمية من Google"

إحدى الميزات الرائعة في "برمجة التطبيقات" هي أنّها تتيح لك نقل البيانات بسهولة من تطبيق Google Workspace إلى آخر. تتضمّن معظم هذه التطبيقات خدمة مخصّصة في Apps Script، على غرار خدمة جداول البيانات. على سبيل المثال، يتضمّن Gmail خدمة Gmail، ويتضمّن "مستندات Google" خدمة المستندات، ويتضمّن "العروض التقديمية من Google" خدمة العروض التقديمية. باستخدام كل هذه الخدمات المضمّنة، يمكنك استخراج البيانات من تطبيق واحد ومعالجتها وكتابة النتيجة في تطبيق آخر.

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

التنفيذ

في هذا القسم، ستنفّذ الدالة التي يستدعيها عنصر القائمة عرض مجموعة البيانات > تصدير الرسوم البيانية إلى "العروض التقديمية من Google". يُرجى تنفيذ ما يلي:

  1. في "محرّر برمجة التطبيقات"، أضِف الدالة التالية إلى نهاية النص البرمجي Code.gs لمشروع النص البرمجي، بعد الدالة createEmbeddedLineChart():
/**
 * Create a Slides presentation and export
 * all the embedded charts in this spreadsheet
 * to it, one chart per slide.
 */
function exportChartsToSlides() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  
  // Fetch a list of all embedded charts in this
  // spreadsheet.
  var charts = [];
  var sheets = ss.getSheets();
  for (var i = 0; i < sheets.length; i++) {
    charts = charts.concat(sheets[i].getCharts());
  }
  
  // If there aren't any charts, display a toast
  // message and return without doing anything
  // else.
  if (charts.length == 0) {
    ss.toast('No charts to export!');
    return;
  }
  
  // Create a Slides presentation, removing the default
  // title slide.
  var presentationTitle =
    ss.getName() + " Presentation";
  var slides = SlidesApp.create(presentationTitle);
  slides.getSlides()[0].remove();  
  
  // Add charts to the presentation, one chart per slide.
  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);   
  }
  
  // Create and display a dialog telling the user where to
  // find the new presentation.
  var slidesUrl = slides.getUrl();
  var html = "<p>Find it in your home Drive folder:</p>"
      + "<p><a href=\"" + slidesUrl + "\" target=\"_blank\">"
      + presentationTitle + "</a></p>";
  
  SpreadsheetApp.getUi().showModalDialog(
    HtmlService.createHtmlOutput(html)
      .setHeight(120)
      .setWidth(350),
      "Created a presentation!"
  );
}
  1. احفظ مشروع النص البرمجي.

مراجعة الرموز البرمجية

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

‫1: الحصول على الرسوم البيانية

تبحث الأسطر القليلة الأولى في جدول البيانات النشط للعثور على جميع الرسوم البيانية المضمّنة، وتجمعها في المصفوفة charts. تستخدم هذه الأسطر الطريقتَين Spreadsheet.getSheets() وSheet.getCharts() للحصول على قوائم بالجداول والرسوم البيانية. يتم استخدام طريقة JavaScript Array.concat() لإلحاق قائمة الرسوم البيانية من كل ورقة في charts.

‫2: التأكّد من توفّر رسومات بيانية لتصديرها

يتحقّق الرمز ممّا إذا كانت هناك أي رسومات بيانية لتصديرها. نريد تجنُّب إنشاء عرض تقديمي فارغ، لذا إذا لم تكن هناك أي رسومات بيانية، ينشئ الرمز بدلاً من ذلك رسالة تنبيه باستخدام Spreadsheet.toast(message). هذا مربع حوار صغير يظهر في أسفل يسار "جداول بيانات Google"، ويبقى لبضع ثوانٍ ثم يختفي:

db7e87dcb8010bef.gif

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

‫3: إنشاء عرض تقديمي

يتم إنشاء المتغيّر presentationTitle لتخزين اسم ملف العرض التقديمي الجديد. يتم ضبطه كاسم لجدول البيانات، مع إضافة " Presentation" في النهاية. تستدعي التعليمات البرمجية بعد ذلك طريقة خدمة "العروض التقديمية من Google" SlidesApp.create(name) لإنشاء عرض تقديمي.

يتم إنشاء عروض تقديمية جديدة باستخدام شريحة واحدة فارغة. لا نريد أن يظهر ذلك في العرض التقديمي، لذا يزيله الرمز باستخدام Presentation.getSlides() و Slide.remove().

‫4: تصدير الرسوم البيانية

في القسم التالي، يحدّد الرمز position وsize لعناصر JavaScript لتحديد موضع المخططات المستورَدة في الشريحة وحجم المخطط (بالبكسل).

تتكرّر حلقة الرمز البرمجي على كل رسم بياني في قائمة الرسوم البيانية. لكل رسم بياني، يتم إنشاء newSlide باستخدام Presentation.appendSlide()، ما يؤدي إلى إضافة الشريحة إلى نهاية العرض التقديمي. يتم استخدام طريقة Slide.insertSheetsChart(sourceChart, left, top, width, height) لاستيراد الرسم البياني إلى الشريحة مع position وsize المحدّدين.

‫5: مشاركة موقع العرض التقديمي

أخيرًا، يجب أن يوضّح الرمز للمستخدم مكان العرض التقديمي الجديد، ويُفضّل أن يتضمّن رابطًا يمكنه النقر عليه لفتحه. لإجراء ذلك، يستخدم الرمز البرمجي HTML الخدمة في Apps Script لإنشاء مربّع حوار مشروط مخصّص. مربّعات الحوار النمطية (المعروفة أيضًا باسم مربّعات الحوار المخصّصة في "برمجة تطبيقات Google") هي نوافذ تظهر فوق واجهة "جداول بيانات Google". عند عرض مربّعات الحوار المخصّصة، تمنع المستخدم من التفاعل مع "جداول بيانات Google".

لإنشاء مربّع حوار مخصّص، يحتاج الرمز إلى HTML الذي يحدّد محتواه. يتم توفير ذلك في المتغيّر html. يتضمّن المحتوى فقرة قصيرة ورابطًا تشعبيًا. الرابط التشعّبي هو المتغيّر presentationTitle، وهو مرتبط بعنوان URL للعرض التقديمي الذي يوفّره Presentation.getUrl(). يستخدم الارتباط التشعّبي أيضًا السمة target="_blank"، لذا يتم فتح العرض التقديمي في علامة تبويب جديدة في المتصفّح بدلاً من فتحه في مربّع الحوار.

يتم تحليل HTML إلى كائن HtmlOutput باستخدام الطريقة HtmlService.createHtmlOutput(html). يتيح العنصر HtmlOutput للرمز البرمجي ضبط حجم مربّع الحوار المخصّص باستخدام HtmlOutput.setHeight(height) و HtmlOutput.setWidth(width).

بعد إنشاء htmlOutput، يستخدم الرمز البرمجي الطريقة Ui.showModalDialog(htmlOutput, title) لعرض مربّع الحوار مع العنوان المحدّد.

النتائج

بعد تنفيذ عنصر القائمة الثاني، يمكنك الاطّلاع على طريقة عمله. لاختبار الدالة exportChartsToSlides()، اتّبِع الخطوات التالية:

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

51326ceaeb3e49b2.gif

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

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

لقد أكملت التمرين الأخير في هذا الدرس العملي. انتقِل إلى القسم التالي لمراجعة ما تعلّمته.

5. الخاتمة

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

هل كان هذا الدرس التطبيقي العملي مفيدًا؟

ما تعلّمته

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

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

لقد أكملت قائمة التشغيل هذه بنجاح. ومع ذلك، لا يزال هناك المزيد من المعلومات حول Apps Script.

يمكنك الاطّلاع على المراجع التالية:

نتمنى لك تجربة كتابة نصوص برمجية ممتعة.

هل كانت قائمة تشغيل Codelab هذه مفيدة؟

هل تريد الاطّلاع على المزيد من دروس Apps Script البرمجية في المستقبل؟
bug_report الإبلاغ عن خطأ