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

تتيح لك 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"
      }
    }
  ]
}