التنسيق الأساسي

تتيح لك Google Sheets API تعديل تنسيق الخلايا والنطاقات داخل جداول البيانات. توضِّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ بعض عمليات التنسيق الشائعة باستخدام واجهة برمجة التطبيقات Sheets API. يمكنك الاطّلاع على المزيد من أمثلة التنسيق الشرطي في صفحة التنسيق الشرطي.

عند تعديل جدول بيانات، قد تُعرِض بعض أنواع الطلبات ردودًا. ويتم عرض هذه الردود في صفيف، مع احتلال كلّ استجابة للفهرس نفسه الذي يشغله الطلب المقابل. لا تتضمّن بعض الطلبات ردودًا، ويكون الردّ فارغًا في هذه الحالات. يمكن العثور على بنية الاستجابة لهذه الأمثلة ضمن spreadsheets.batchUpdate.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على مقالة تعديل جداول بيانات Google.

في هذين المثالَين، تشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي يجب فيه تقديم معرّفات التطبيقَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الأسلوب spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. أحد مثالي النطاق هو الورقة1!A1:D5.

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

تعديل حدود الخلايا

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الرمز UpdateBordersRequest لمنح كل خلية في النطاق A1:F10 حدودًا متقطّعة زرقاء في أعلى وأسفل الخلية. ينشئ الحقل innerHorizontal حدودًا أفقية في داخل النطاق. سيؤدي حذف الحقل إلى إضافة حدود إلى أعلى وأسفل النطاق بأكمله فقط.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateBorders": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 6
        },
        "top": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "bottom": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "innerHorizontal": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
      }
    }
  ]
}

تنسيق صف العنوان

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام الرمز RepeatCellRequest لتنسيق صف عنوان في ورقة بيانات. يعدّل الطلب الأول لون النص، ولون الخلفية، وحجم خط النص، ومحاذاة النص، ويجعل النص غامقًا. يؤدي حذف فهرسات الأعمدة في حقل range إلى تنسيق الصف بالكامل. يعدّل الطلب الثاني سمات ورقة البيانات لتتمكّن من تجميد صف العنوان.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "backgroundColor": {
              "red": 0.0,
              "green": 0.0,
              "blue": 0.0
            },
            "horizontalAlignment" : "CENTER",
            "textFormat": {
              "foregroundColor": {
                "red": 1.0,
                "green": 1.0,
                "blue": 1.0
              },
              "fontSize": 12,
              "bold": true
            }
          }
        },
        "fields": "userEnteredFormat(backgroundColor,textFormat,horizontalAlignment)"
      }
    },
    {
      "updateSheetProperties": {
        "properties": {
          "sheetId": SHEET_ID,
          "gridProperties": {
            "frozenRowCount": 1
          }
        },
        "fields": "gridProperties.frozenRowCount"
      }
    }
  ]
}

دمج الخلايا

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الرمز MergeCellsRequest لدمج الخلايا. يدمج الطلب الأول النطاق A1:B2 في خلية واحدة. يمجِّن الطلب الثاني الأعمدة في A3:B6، مع إبقاء الصفوف مفصولة.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 2,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_ALL"
      }
    },
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 2,
          "endRowIndex": 6,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_COLUMNS"
      }
    },
  ]
}

ضبط تنسيق تاريخ ووقت أو تنسيق عشري مخصّص لنطاق

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام الرمز RepeatCellRequest لتعديل الخلايا بحيث تتضمّن تنسيقات مخصّصة للوقت والتاريخ والأرقام. يمنح الطلب الأول الخلايا في النطاق A1:A10 تنسيق التاريخ والوقت المخصّص hh:mm:ss am/pm, ddd mmm dd yyyy. في ما يلي مثال على التاريخ والوقت بالتنسيق التالي: "02:05:07 مساءً، الأحد 03 نيسان (أبريل) 2016".

يمنح الطلب الثاني الخلايا في B1:B10 تنسيق الأرقام المخصّص #,##0.0000، الذي يشير إلى أنّه يجب تجميع الأرقام باستخدام فواصل الفواصل، وأنّه يجب أن يكون هناك 4 أرقام بعد النقطة العشرية، وأنّه يجب حذف كل الأرقام البادئة إلا واحدة. على سبيل المثال، يتم عرض الرقم "3.14" بالتنسيق "3.1400"، في حين يتم عرض الرقم "12345.12345" بالتنسيق "12,345.1235".

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "DATE",
              "pattern": "hh:mm:ss am/pm, ddd mmm dd yyyy"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    },
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 2
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "NUMBER",
              "pattern": "#,##0.0000"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    }
  ]
}