الجداول

يصف هذا الدليل كيفية استخدام 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 لحذف صف كامل من جدول البيانات.

**ملاحظة:** في حال استخدام InsertRangeRequest أو DeleteRangeRequest، يجب أن يغطّي النطاق في الطلب الصفوف بالكامل في حال حذف صف، أو الأعمدة بالكامل في حال حذف عمود.

إيقاف تذييل الجدول أو تفعيله

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

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

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

حذف جدول

استخدِم الـ spreadsheets.batchUpdate method وقدِّم DeleteTableRequest. استخدِم DeleteTableRequest لحذف الجدول بالكامل ومحتوياته.

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

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

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