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

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

جدول 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"
      }
    }
  ]
}