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

1. مقدمة

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

ما ستتعرَّف عليه

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

قبل البدء

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

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

الأشياء التي تحتاج إليها

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

2. إعداد

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

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

45a3e8814ecb07fc.png

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

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

9b9caf6c1e9de34b.png

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

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

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

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

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

التنفيذ

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

اتّبِع الخطوات التالية:

  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. احفظ مشروع النص البرمجي.

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

يؤدي الرمز الذي أضفته إلى تنفيذ الدالة التي يُطلق عليها عنصر القائمة Chart "Dates and USD Exchange Rates" لإنشاء رسم بياني خطي أساسي. لنراجع الرمز.

توضّح الأسطر الأولى المتغيرات الثلاثة التالية:

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

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

توفّر خدمة جداول البيانات فئة 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. هناك العديد من الخيارات التي يمكنك إعدادها باستخدام هذه الطريقة. تم توثيق الخيارات والقيم المحتملة لكل نوع رسم بياني في معرض الرسوم البيانية لواجهة برمجة تطبيقات المخططات. على سبيل المثال، يتم توثيق الخيارات التي يمكنك تحديدها للرسوم البيانية الخطية ضمن خيارات ضبط المخطط الخطي. طريقة setOption(option, value) هي موضوع متقدم، لذا قد ترغب في تجنُّب استخدامه حتى تصبح أكثر ارتياحًا بشأن إنشاء الرسم البياني في "برمجة التطبيقات".
  • build(): لإنشاء عنصر EmbeddedChart وعرضه باستخدام الإعدادات المذكورة أعلاه.

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

النتائج

يمكنك الاطّلاع على وظيفة التنسيق أثناء تنفيذها عن طريق ما يلي:

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

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

bbf856699b6d2b45.gif

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

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

تتمثّل إحدى أهم ميزات "برمجة التطبيقات" في أنها تسمح لك بنقل البيانات بسهولة من أحد تطبيقات Google Workspace إلى تطبيق آخر. تحتوي معظم هذه التطبيقات على خدمة "برمجة تطبيقات Google" مُخصَّصة، مثل خدمة جداول البيانات. على سبيل المثال، يتضمن 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). هذا مربّع حوار صغير "خادع" يظهر في الجانب السفلي الأيسر من جداول البيانات، ويبقى لبضع ثوانٍ، ثم يختفي:

db7e87dcb8010bef.gif

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

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

تم إنشاء المتغير presentationTitle للاحتفاظ باسم ملف العرض التقديمي الجديد. إنه مُحدد باسم جدول البيانات، مع &quot؛ Presentation&quot؛ متحد في النهاية. يطلب الرمز بعد ذلك طريقة خدمة "العروض التقديمية من 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 برمجة التطبيقاتHTML لإنشاء مربع حوار مشروط مخصَّص. مربّعات حوار نمطية (تُعرف أيضًا باسم مربّعات الحوار المخصّصة في برمجة التطبيقات) هي نوافذ تظهر على واجهة "جداول بيانات 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. احفظ مشروع النص البرمجي في محرِّر "برمجة تطبيقات Google"، إذا لم يسبق لك إجراء ذلك.
  2. افتح جدول البيانات وانقر على عنصر القائمة مشاركة مجموعة البيانات > الرسم البياني "التواريخ ومجموعة بيانات أسعار صرف العملات بالدولار الأمريكي لإنشاء رسم بياني لتصديره. سيظهر الإعلان ثابتًا إلى الخلية H5 في الورقة النشطة.
  3. انقر على عنصر القائمة مشاركة عرض مجموعة البيانات &gt؛ تصدير الرسوم البيانية إلى "العروض التقديمية من Google". وقد تتم مطالبتك بإعادة تفويض النص البرمجي.
  4. من المفترض أن يظهر لك النص البرمجي الذي يعالج الطلب ويعرض مربّع الحوار المخصّص.
  5. لفتح العرض التقديمي الجديد من خلال العروض التقديمية، انقر على الرابط عرض تقديمي حول أسعار صرف العملات وأسعار الدولار الأمريكي:

51326ceaeb3e49b2.gif

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

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

لقد أكملت التدريب النهائي على هذا الدرس التطبيقي حول الترميز. انتقل إلى القسم التالي لمراجعة ما تعلمته.

5. الخلاصة

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

هل وجدت هذا الدرس التطبيقي مفيدًا؟

نعم لا

ما تعلمته

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

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

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

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

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

هل وجدت قائمة الدروس التطبيقية حول الترميز مفيدة؟

نعم لا

هل تريد الاطّلاع على المزيد من الدروس التطبيقية حول ترميز "برمجة التطبيقات" في المستقبل؟

نعم لا