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

تسمح لك 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 حدودًا أفقية على الجزء الداخلي من النطاق. سيؤدي إغفال الحقل إلى إضافة الحدود فقط إلى أعلى وأسفل النطاق بأكمله.

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

في ما يلي بروتوكول الطلب.

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 إلى تنسيق الصف بالكامل. يقوم الطلب الثاني بضبط خصائص الورقة بحيث يتم تجميد صف الرأس.

جدول 3 في 3 يحتوي على صف عنوان منسق في ورقة.
الشكل 2. تنسيق صف العنوان في ورقة.

في ما يلي بروتوكول الطلب.

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، مع ترك الصفوف مفصولة.

جدول 3 في 3 يحتوي على خلايا مدمَجة في ورقة.
الشكل 3. دمج خلايا في ورقة

في ما يلي بروتوكول الطلب.

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".

جدول 3 × 3 بتنسيقات تاريخ ووقت وأرقام مخصصة في ورقة.
الشكل 4. يمكنك تعديل الخلايا للحصول على تنسيقات تاريخ ووقت وأرقام مخصّصة في ورقة بيانات.

في ما يلي بروتوكول الطلب.

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"
      }
    }
  ]
}