الجداول

يوضّح هذا الدليل كيفية استخدام Google Sheets API لإنشاء جداول في جداول البيانات والأسباب التي تدفعك إلى ذلك.

ما هو الجدول؟

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

تتضمّن الجداول العديد من الميزات، مثل العناوين والتذييلات وأنواع الأعمدة والفلاتر وطرق العرض ومراجع الجداول وأسماء الجداول. يمكنك الاطّلاع على مزيد من المعلومات في إعلان الميزة والتعرّف على كيفية استخدام الجداول في "جداول بيانات Google".

يمكنك استخدام الجداول لتنفيذ مهام مثل تتبُّع المشاريع وتخطيط الأحداث وإدارة المستودع.

إضافة جدول

لإضافة جدول، استخدِم طريقة batchUpdate، مع توفير طلب addTable. يمكنك استخدام هذا الطلب لإضافة جدول إلى جدول البيانات.

ينشئ المثال التالي جدولاً باسم "Project Tracker" في range المحدّد مع عمودَين مضبوطَين. عمود نسبة مئوية في العمود الأول ونوع عمود قائمة منسدلة في العمود الثاني

{   "addTable": {     "table": {       "name": "Project Tracker",       "tableId": "123",       "range": {         "sheetId": 0,         "startColumnIndex": 0,         "endColumnIndex": 5,         "startRowIndex": 0,         "endRowIndex": 5,       },       "columnProperties": [         {           "columnIndex": 0,           "columnName": "Column 1",           "columnType": "PERCENT"         },         {           "columnIndex": 1,           "columnName": "Column 2",           "columnType": "DROPDOWN",           "dataValidationRule": {             "condition": {               "type": "ONE_OF_LIST",               "values": [                 {                   "userEnteredValue": "Not Started"                 },                 {                   "userEnteredValue": "In Progress"                 },                 {                   "userEnteredValue": "Complete"                 }               ]             }           }         }       ],     }   } }

أنواع الأعمدة

تحتوي الجداول على أنواع أعمدة مثل الأرقام والتاريخ والقائمة المنسدلة والشريحة الذكية ومربّع الاختيار. يتم ملء نوعَي العمودَين "التقييم" و"مربّع الاختيار" بالقيم التلقائية 0 وFALSE على التوالي.

ينشئ نوع العمود "قائمة منسدلة" قائمة منسدلة على شكل شريحة. إذا تم ضبط نوع العمود على قائمة منسدلة، يجب ضبط dataValidationRule للعمود باستخدام شرط ONE_OF_LIST. يجب ألا يتم ضبط الحقل `dataValidationRule` لأنواع الأعمدة الأخرى.

تعديل جدول

استخدِم طريقة spreadsheets.batchUpdate وقدِّم UpdateTableRequest.

تعديل حجم الجدول

استخدِم طريقة UpdateTableRequest لتعديل range الذي يجب أن يضيفه الجدول إلى الصفوف أو الأعمدة الجديدة.

إذا كنت بحاجة إلى إضافة صف أو عمود جديدَين داخل الجدول، استخدِم InsertRangeRequest أو InsertDimensionRequest.

إذا كنت بحاجة إلى حذف صف جدول، يمكنك استخدام DeleteRangeRequest، أو يمكنك استخدام DeleteDimensionRequest لحذف صف كامل من جدول البيانات.

إذا كنت تعدّل جدولاً حاليًا بدون تذييل لإضافة تذييل، سيتوسّع range بمقدار صف واحد. إذا كنت تعدّل جدولاً حاليًا يتضمّن تذييلاً وتزيل التذييل، سيتم تقليل حجم range بمقدار صف واحد.

إلحاق قيم بجدول

استخدِم AppendCellsRequest مع tableId لإضافة صفوف إلى نهاية جدول. يؤدي ذلك إلى إلحاق القيم بأول صف فارغ، كما أنّه يدرك الصفوف الكاملة والتذييلات. إذا لم تكن هناك صفوف فارغة، سيؤدي ذلك إلى إدراج صفوف في نهاية الجدول وقبل أي تذييل، إذا كان ذلك منطبقًا.

حذف جدول

استخدِم طريقة spreadsheets.batchUpdate وقدِّم DeleteTableRequest. استخدِم DeleteTableRequest لحذف الجدول بأكمله ومحتواه.

استخدِم DeleteBandingRequest لإزالة تنسيق الجدول مع الاحتفاظ بالبيانات.

استخدام الجداول مع ميزات "جداول بيانات Google" الأخرى

تشمل ميزات واجهة برمجة التطبيقات الأخرى التي تتيح استخدام الجداول كبيانات أساسية ما يلي: الفلاتر عروض الفلاتر النطاقات المحمية.