الجداول

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

ما هو الجدول؟

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

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

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

إضافة جدول

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

ينشئ المثال التالي جدولاً باسم "تتبُّع المشاريع" في range المحدّد مع عمودَين محدّدَين. عمود نسبة مئوية في العمود الأول وعمود نوع Dropdown في العمود الثاني

{
  "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 وقدِّم DeleteTableRequest. استخدِم DeleteTableRequest لحذف الجدول بأكمله ومحتوياته.

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

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

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