أساسيات "برمجة تطبيقات Google" مع "جداول بيانات Google"، الجزء 2: جداول البيانات والأوراق والنطاقات
لمحة عن هذا الدرس التطبيقي حول الترميز
1. مقدمة
مرحبًا بك في الجزء الثاني من قائمة تشغيل سلسلة دروس "أساسيات برمجة تطبيقات Google" باستخدام "جداول بيانات Google". ركّزت تجربة البرمجة السابقة على مفاهيم محرِّر النصوص البرمجية ووحدات الماكرو والدوال المخصّصة. يتناول هذا الدرس العملي خدمة جداول البيانات التي يمكنك استخدامها لقراءة البيانات وكتابتها ومعالجتها في "جداول بيانات Google".
أهداف الدورة التعليمية
- كيفية تمثيل جداول البيانات والأوراق والنطاقات في "برمجة تطبيقات Google"
- كيفية الوصول إلى جدول البيانات النشط (المفتوح) وإنشائه وإعادة تسميته باستخدام الفئتين
SpreadsheetAppوSpreadsheet - كيفية تغيير اسم ورقة واتجاه العمود/الصف لنطاق باستخدام الفئة
Sheet - كيفية تحديد مجموعة من الخلايا أو نطاق من البيانات وتفعيلها ونقلها وفرزها باستخدام الفئة
Range
قبل البدء
هذا هو الدرس العملي الثاني في قائمة تشغيل "أساسيات برمجة تطبيقات Google مع جداول بيانات Google". قبل البدء، تأكَّد من إكمال الدرس العملي الأول: وحدات الماكرو والدوال المخصّصة.
المتطلبات
- فهم مواضيع "برمجة تطبيقات Google" الأساسية التي تم استكشافها في الدرس العملي السابق ضمن قائمة التشغيل هذه
- معرفة أساسية بأداة تعديل رموز برمجة التطبيقات
- معرفة أساسية بـ جداول بيانات Google
- إمكانية قراءة ترميز A1 في "جداول بيانات Google"
- معرفة أساسية بلغة JavaScript وفئة
String
يعرض القسم التالي الفئات الأساسية لخدمة "جداول بيانات Google".
2. مقدمة إلى خدمة جداول البيانات
تتضمّن أربع فئات أساس خدمة "جداول بيانات Google": SpreadsheetApp وSpreadsheet وSheet وRange. يوضّح هذا القسم هذه الفئات واستخداماتها.
فئة SpreadsheetApp
قبل الخوض في تفاصيل جداول البيانات وأوراقها ونطاقاتها، يجب مراجعة الفئة الرئيسية لها: SpreadsheetApp. تبدأ العديد من البرامج النصية باستدعاء طرق SpreadsheetApp، لأنّها يمكن أن توفّر نقطة الوصول الأولية إلى ملفات "جداول بيانات Google". يمكنك اعتبار SpreadsheetApp الفئة الرئيسية في خدمة جداول البيانات. لا يتم تناول الصف SpreadsheetApp بالتفصيل هنا. ومع ذلك، يمكنك العثور في وقت لاحق من هذا الدرس التطبيقي حول الترميز على أمثلة وتمارين لمساعدتك في فهم هذه الفئة.
جداول البيانات والأوراق وفئاتها
في "جداول بيانات Google"، جدول البيانات هو ملف "جداول بيانات Google" (مخزّن في Google Drive) يحتوي على بيانات منظَّمة حسب الصفوف والأعمدة. يُشار أحيانًا إلى جدول البيانات باسم "جدول بيانات Google"، بالطريقة نفسها التي يُشار بها إلى المستند باسم "مستند Google".
يمكنك استخدام فئة Spreadsheet للوصول إلى بيانات ملف "جداول بيانات Google" وتعديلها. يمكنك أيضًا استخدام هذه الفئة لإجراء عمليات أخرى على مستوى الملف، مثل إضافة متعاونين.
تمثّل الورقة** الصفحة الفردية من جدول بيانات، ويُشار إليها أحيانًا باسم "علامة تبويب". يمكن أن يحتوي كل جدول بيانات على ورقة واحدة أو أكثر. يمكنك استخدام الفئة Sheet** للوصول إلى البيانات والإعدادات على مستوى ورقة البيانات وتعديلها، مثل نقل صفوف أو أعمدة البيانات.
باختصار، تعمل الفئة Spreadsheet على مجموعة أوراق البيانات وتحدّد ملف "جداول بيانات Google" في Google Drive. تعمل الفئة Sheet على أوراق فردية ضمن جدول بيانات.
فئة النطاق
تتطلّب معظم عمليات معالجة البيانات (مثل قراءة بيانات الخلايا أو كتابتها أو تنسيقها) تحديد الخلايا التي تنطبق عليها العملية. يمكنك استخدام الفئة Range لاختيار مجموعات محدّدة من الخلايا ضمن ورقة. تمثّل مثيلات هذه الفئة نطاقًا، أي مجموعة من خلية واحدة أو أكثر من الخلايا المتجاورة في ورقة. يمكنك تحديد النطاقات من خلال أرقام الصفوف والأعمدة أو باستخدام نظام التسمية A1.
تعرض بقية الدرس العملي أمثلة على النصوص البرمجية التي تعمل مع هذه الفئات وطرقها.
3. إعداد
قبل المتابعة، تحتاج إلى جدول بيانات يتضمّن بعض البيانات. لقد أتحنا لك نموذجًا: انقر على هذا الرابط لنسخ ورقة البيانات، ثم انقر على إنشاء نسخة.
يتم وضع نسخة من جدول البيانات النموذجي لتستخدمها في مجلد Google Drive وتسميتها "نسخة من جدول بيانات بلا عنوان". استخدِم جدول البيانات هذا لإكمال تمارين هذا الدرس العملي.
للتذكير، يمكنك فتح "محرّر النصوص البرمجية" من "جداول بيانات Google" من خلال النقر على الإضافات > برمجة تطبيقات Google.
عند فتح مشروع "برمجة تطبيقات Google" في أداة تعديل النصوص البرمجية لأول مرة، تنشئ أداة تعديل النصوص البرمجية مشروع نص برمجي وملف نص برمجي لك.
يوضّح لك القسم التالي كيفية استخدام فئة Spreadsheet لتحسين جدول البيانات هذا.
4. الوصول إلى جداول البيانات وتعديلها
في هذا القسم، يمكنك التعرّف على كيفية استخدام الفئتين SpreadsheetApp و Spreadsheet للوصول إلى جداول البيانات وتعديلها. على وجه التحديد، تعلّمك التمارين كيفية إعادة تسمية جدول بيانات وتكرار الأوراق داخل جدول بيانات.
هذه عمليات بسيطة، ولكنّها غالبًا ما تكون جزءًا من سير عمل أكبر وأكثر تعقيدًا. بعد أن تتمكّن من فهم كيفية أتمتة هذه المهام باستخدام رمز البرنامج النصي، سيسهل عليك تعلُّم كيفية أتمتة العمليات الأكثر تفصيلاً.
إعادة تسمية جدول البيانات النشط
لنفترض أنّك تريد تغيير الاسم التلقائي "نسخة من جدول بيانات بلا عنوان" إلى عنوان يعكس بشكل أفضل الغرض من جدول البيانات. يمكنك إجراء ذلك باستخدام الفئتين SpreadsheetApp و Spreadsheet.
- في أداة تعديل النصوص البرمجية، استبدِل كتلة الرمز
myFunction()التلقائية بالرمز التالي:
function renameSpreadsheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
mySS.rename("2017 Avocado Prices in Portland, Seattle");
}
- لحفظ النص، انقر على "حفظ"
. - لإعادة تسمية مشروع Apps Script، انقر على مشروع بلا عنوان، وأدخِل "أسعار الأفوكادو" كاسم جديد للمشروع، ثم انقر على إعادة تسمية.
- لتشغيل النص البرمجي، اختَر
renameSpreadsheetمن قائمة الدوال وانقر على تشغيل. - امنح الإذن بتشغيل الماكرو باتّباع التعليمات الظاهرة على الشاشة. إذا ظهرت لك الرسالة "لم يتم التحقّق من هذا التطبيق"، انقر على خيارات متقدمة، ثم انقر على الانتقال إلى أسعار الأفوكادو (غير آمن). في الشاشة التالية، انقر على السماح.
بعد تنفيذ الدالة، من المفترض أن يتغيّر اسم ملف جدول البيانات:
لنلقِ نظرة على الرمز الذي أدخلته. تعرض الطريقة getActiveSpreadsheet() عنصرًا يمثّل جدول البيانات النشط، أي نسخة جدول بيانات التمرين التي أنشأتها. يتم تخزين عنصر جدول البيانات هذا في المتغيّر mySS. يؤدي استدعاء rename(newName) على mySS إلى تغيير اسم ملف جدول البيانات في Google Drive إلى "أسعار الأفوكادو في بورتلاند وسياتل لعام 2017".
بما أنّ المتغيّر mySS هو مرجع إلى جدول البيانات، يمكنك جعل الرمز البرمجي أكثر وضوحًا وفعالية من خلال استدعاء طرق Spreadsheet على mySS بدلاً من استدعاء getActiveSpreadsheet() بشكل متكرّر.
إنشاء نسخة طبق الأصل من الورقة النشطة
في جدول البيانات الحالي، لديك ورقة واحدة فقط. يمكنك استدعاء الطريقة Spreadsheet.duplicateActiveSheet() لإنشاء نسخة من ورقة البيانات:
- أضِف الدالة الجديدة التالية أسفل الدالة
renameSpreadsheet()الموجودة في مشروع النص البرمجي:
function duplicateAndOrganizeActiveSheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
var duplicateSheet = mySS.duplicateActiveSheet();
}
- احفظ مشروع النص البرمجي.
- لتشغيل النص البرمجي، اختَر
duplicateAndOrganizeActiveSheetمن قائمة الدوال وانقر على تشغيل.
ارجع إلى "جداول بيانات Google" لترى أنّه تمت إضافة علامة تبويب ورقة جديدة باسم "نسخة من Sheet_Original" إلى جدول البيانات.
في هذه الدالة الجديدة، تنشئ الطريقة duplicateActiveSheet() ورقة البيانات المكرّرة في جدول البيانات وتفعّلها وتعرضها. يتم تخزين ورقة البيانات الناتجة في duplicateSheet، ولكن الرمز لا ينفّذ أي إجراء باستخدام هذا المتغير حتى الآن.
في القسم التالي، ستستخدم الفئة Sheet لإعادة تسمية الورقة المكرّرة وتنسيقها.
5. تنسيق ورقة باستخدام فئة Sheet
يوفر الصف Sheet طرقًا تتيح للنصوص البرمجية قراءة الجداول وتعديلها. في هذا القسم، يمكنك التعرّف على كيفية تغيير اسم ورقة وجداول عرض الأعمدة باستخدام طرق من الفئة Sheet.
تغيير اسم ورقة الجدول
إعادة تسمية الأوراق بسيطة تمامًا مثل إعادة تسمية جدول البيانات في renameSpreadsheet(). يجب إجراء عملية استدعاء واحدة فقط للطريقة.
- في "جداول بيانات Google"، انقر على ورقة
Sheet_Originalلتفعيلها. - في Apps Script، عدِّل الدالة
duplicateAndOrganizeActiveSheet()لتتطابق مع ما يلي:
function duplicateAndOrganizeActiveSheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
var duplicateSheet = mySS.duplicateActiveSheet();
// Change the name of the new sheet.
duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());
}
- احفظ الدالة وشغِّلها.
في "جداول بيانات Google"، يتم إنشاء ورقة بيانات مكرّرة وإعادة تسميتها عند تنفيذ الدالة:
في الرمز البرمجي المُضاف، تغيّر الدالة setName(name) اسم duplicateSheet، وذلك باستخدام getSheetID() للحصول على رقم المعرّف الفريد للورقة. يؤدي عامل التشغيل + إلى ربط رقم تعريف ورقة البيانات بنهاية السلسلة "Sheet_".
تعديل أعمدة وصفوف ورقة جدول
يمكنك أيضًا استخدام الفئة Sheet لتنسيق ورقة البيانات. على سبيل المثال، يمكننا تعديل الدالة duplicateAndOrganizeActiveSheet() لتغيير حجم أعمدة الورقة المكرّرة أيضًا، وإضافة صفوف مجمّدة:
- في "جداول بيانات Google"، انقر على ورقة
Sheet_Originalلتفعيلها. - في Apps Script، عدِّل الدالة
duplicateAndOrganizeActiveSheet()لتتطابق مع ما يلي:
function duplicateAndOrganizeActiveSheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
var duplicateSheet = mySS.duplicateActiveSheet();
// Change the name of the new sheet.
duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());
// Format the new sheet.
duplicateSheet.autoResizeColumns(1, 5);
duplicateSheet.setFrozenRows(2);
}
- احفظ الدالة وشغِّلها.
في "جداول بيانات Google"، يتم إنشاء ورقة بيانات مكررة وإعادة تسميتها وتفعيلها وتنسيقها:
يستخدم الرمز الذي أضفته autoResizeColumns(startColumn, numColumns) لتغيير حجم أعمدة ورقة البيانات لتسهيل قراءتها. تجمّد الطريقة setFrozenRows(rows) عدد الصفوف المحدّد (صفان في هذه الحالة)، ما يحافظ على ظهور صفوف العناوين أثناء تمرير القارئ لأسفل في جدول البيانات.
في القسم التالي، ستتعرّف على النطاقات والمعالجة الأساسية للبيانات.
6. إعادة ترتيب البيانات باستخدام فئة Range
يوفر الصف Range وطرق العرض الخاصة به معظم خيارات معالجة البيانات وتنسيقها في خدمة جداول بيانات Google.
يتناول هذا القسم معالجة البيانات الأساسية باستخدام النطاقات. تركّز هذه التمارين على كيفية استخدام النطاقات في Apps Script، بينما تتناول برامج الترميز الأخرى في قائمة التشغيل هذه تفاصيل أعمق حول معالجة البيانات وتنسيقها.
نقل النطاقات
يمكنك تفعيل نطاقات البيانات ونقلها باستخدام طرق الفئات وترميز A1، وهو اختصار لتحديد مجموعات معيّنة من الخلايا في جداول البيانات. إذا كنت بحاجة إلى إعادة التعرّف على هذا النظام، يمكنك الاطّلاع على وصف نظام التسمية A1.
لنعدّل طريقة duplicateAndOrganizeActiveSheet() لنقل بعض البيانات أيضًا:
- في "جداول بيانات Google"، انقر على ورقة
Sheet_Originalلتفعيلها. - في Apps Script، عدِّل الدالة
duplicateAndOrganizeActiveSheet()لتتطابق مع ما يلي:
function duplicateAndOrganizeActiveSheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
var duplicateSheet = mySS.duplicateActiveSheet();
// Change the name of the new sheet.
duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());
// Format the new sheet.
duplicateSheet.autoResizeColumns(1, 5);
duplicateSheet.setFrozenRows(2);
// Move column F to column C.
var myRange = duplicateSheet.getRange("F2:F");
myRange.moveTo(duplicateSheet.getRange("C2"));
}
- احفظ الدالة وشغِّلها.
عند تشغيل هذه الدالة، يتم إنشاء ورقة مكرّرة وتفعيلها وتنسيقها. ويتم نقل محتوى العمود F إلى العمود C:
يستخدم الرمز الجديد الطريقة getRange(a1Notation) لتحديد نطاق البيانات المطلوب نقله. من خلال إدخال صيغة A1 "F2:F" كمعلَمة للطريقة، يمكنك تحديد العمود F (باستثناء F1). إذا كان النطاق المحدّد متوفّرًا، تعرض الطريقة getRange(a1Notation) مثيل Range. يخزّن الرمز المثيل في المتغيّر myRange لتسهيل الاستخدام.
بعد تحديد النطاق، تأخذ الطريقة moveTo(target) محتويات myRange (القيم والتنسيق) وتنقلها. يتم تحديد الوجهة (العمود C) باستخدام ترميز A1 "C2". هذه خلية واحدة وليست عمودًا. عند نقل البيانات، ليس عليك مطابقة الأحجام مع النطاقات المستهدَفة ونطاقات الوجهة. تتطابق "برمجة تطبيقات Google" ببساطة مع الخلية الأولى من كل منهما.
ترتيب النطاقات
يتيح لك صف Range قراءة مجموعات الخلايا وتعديلها وتنظيمها. على سبيل المثال، يمكنك ترتيب نطاق بيانات باستخدام الطريقة Range.sort(sortSpecObj):
- في "جداول بيانات Google"، انقر على ورقة
Sheet_Originalلتفعيلها. - في Apps Script، عدِّل الدالة
duplicateAndOrganizeActiveSheet()لتتطابق مع ما يلي:
function duplicateAndOrganizeActiveSheet() {
var mySS = SpreadsheetApp.getActiveSpreadsheet();
var duplicateSheet = mySS.duplicateActiveSheet();
// Change the name of the new sheet.
duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());
// Format the new sheet.
duplicateSheet.autoResizeColumns(1, 5);
duplicateSheet.setFrozenRows(2);
// Move column F to column C.
var myRange = duplicateSheet.getRange("F2:F");
myRange.moveTo(duplicateSheet.getRange("C2"));
// Sort all the data using column C (Price information).
myRange = duplicateSheet.getRange("A3:D55");
myRange.sort(3);
}
- احفظ الدالة وشغِّلها.
الآن، بالإضافة إلى التنسيق السابق، تفرز الدالة جميع البيانات في الجدول باستخدام معلومات الأسعار في العمود C:
يستخدِم الرمز الجديد getRange(a1Notation) لتحديد نطاق جديد يشمل A3:D55 (الجدول بأكمله باستثناء عناوين الأعمدة). يستدعي الرمز بعد ذلك الطريقة sort(sortSpecObj) لترتيب الجدول. في هذا المثال، تمثّل المَعلمة sortSpecObj رقم العمود الذي سيتم الترتيب حسبه. ترتّب الطريقة النطاق بحيث تنتقل قيم العمود المحدَّد من الأدنى إلى الأعلى (القيم التصاعدية). يمكن أن تنفّذ الطريقة sort(sortSpecObj) متطلبات ترتيب أكثر تعقيدًا، ولكنّك لست بحاجة إليها هنا. يمكنك الاطّلاع على جميع الطرق المختلفة التي يمكنك من خلالها استدعاء نطاقات الترتيب في مستندات مرجع الطريقة.
تهانينا، لقد أكملت جميع التمارين في هذا الدرس العملي بنجاح. يراجع القسم التالي النقاط الرئيسية في هذا الدرس العملي ويقدّم معاينة للدرس العملي التالي في قائمة التشغيل هذه.
7. الخاتمة
لقد وصلت إلى نهاية هذا الدرس العملي. يمكنك الآن استخدام وتحديد الفئات والمصطلحات الأساسية لخدمة جداول البيانات في "برمجة تطبيقات Google".
أنت جاهز للانتقال إلى الدرس العملي التالي.
هل كان هذا الدرس التطبيقي العملي مفيدًا؟
المواضيع التي تناولناها
- كيفية تمثيل جداول البيانات والأوراق والنطاقات في "برمجة تطبيقات Google"
- بعض الاستخدامات الأساسية للفئات
SpreadsheetAppوSpreadsheetوSheetوRange
الخطوات التالية
يتناول الدرس التطبيقي التالي في قائمة التشغيل هذه بمزيد من التفصيل كيفية قراءة البيانات وكتابتها وتعديلها في جدول بيانات.
يمكنك العثور على الدرس التطبيقي التالي في العمل مع البيانات.