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

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

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

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

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى مكان تقديم هذين المعرّفَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف ورقة البيانات باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق Sheet1!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"
      }
    }
  ]
}