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

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

عند تعديل جدول بيانات، قد تعرض بعض أنواع الطلبات ردودًا. يتم عرض هذه الردود في مصفوفة، ويشغل كل رد الفهرس نفسه الذي يشغله الطلب المقابل. لا تتضمّن بعض الطلبات ردودًا، وفي هذه الحالة يكون الرد فارغًا. يمكنك الاطّلاع على بنية الردود لهذه الأمثلة ضمن 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"
      }
    }
  ]
}