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

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

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

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

في هذه الأمثلة، يشير العنصران النائبان 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 PM, Sun Apr 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"
      }
    }
  ]
}