عمليات الصفوف والأعمدة

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

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

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي يجب فيه تقديم أرقام التعريف هذه. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL الخاص بجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق: الورقة1!A1:D5.

تعديل عرض العمود أو ارتفاع الصف

يوضّح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام UpdateDimensionPropertiesRequest لتعديل سمة العرض للعمود A إلى 160 بكسل. يعدّل الطلب الثاني قيمة السمة row height الخاصة بالصفوف الثلاثة الأولى لتصبح 40 بكسل. يحدّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة جدول.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateDimensionProperties": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "COLUMNS",
          "startIndex": 0,
          "endIndex": 1
        },
        "properties": {
          "pixelSize": 160
        },
        "fields": "pixelSize"
      }
    },
    {
      "updateDimensionProperties": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "ROWS",
          "startIndex": 0,
          "endIndex": 3
        },
        "properties": {
          "pixelSize": 40
        },
        "fields": "pixelSize"
      }
    }
  ]
}

إلحاق صفوف أو أعمدة فارغة

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

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "appendDimension": {
        "sheetId": SHEET_ID,
        "dimension": "ROWS",
        "length": 3
      }
    },
    {
      "appendDimension": {
        "sheetId": SHEET_ID,
        "dimension": "COLUMNS",
        "length": 1
      }
    }
  ]
}

تغيير حجم عمود تلقائيًا

يوضّح نموذج الرمز التالي كيفية استخدام AutoResizeDimensionsRequest لتغيير حجم الأعمدة من A إلى C، استنادًا إلى حجم محتوى العمود.spreadsheets.batchUpdate يشير الحقل dimension إلى أنّ العملية تنطبق على أعمدة ورقة البيانات.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "autoResizeDimensions": {
        "dimensions": {
          "sheetId": SHEET_ID,
          "dimension": "COLUMNS",
          "startIndex": 0,
          "endIndex": 3
        }
      }
    }
  ]
}

تغيير حجم صف تلقائيًا

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

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "autoResizeDimensions": {
        "dimensions": {
          "sheetId": SHEET_ID,
          "dimension": "ROWS",
          "startIndex": 0,
          "endIndex": 3
        }
      }
    }
  ]
}

حذف الصفوف أو الأعمدة

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام DeleteDimensionRequest لحذف الصفوف الثلاثة الأولى في ورقة. يؤدي طلب ثانٍ إلى حذف الأعمدة من B إلى D. يحدّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة جدول.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "ROWS",
          "startIndex": 0,
          "endIndex": 3
        }
      }
    },
    {
      "deleteDimension": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "COLUMNS",
          "startIndex": 1,
          "endIndex": 4
        }
      }
    },
  ],
}

إدراج صف أو عمود فارغ

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام InsertDimensionRequest لإدراج أعمدة أو صفوف في فهرس معيّن (مثل إضافة صفوف فارغة في بداية ورقة). يُدرج الطلب الأول عمودَين فارغَين في العمود C. يؤدي الطلب الثاني إلى إدراج ثلاثة صفوف فارغة بدءًا من الصف 1.

يحدّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة جدول.

إذا كانت القيمة صحيحة، يطلب الحقل inheritFromBefore من واجهة برمجة التطبيقات في "جداول بيانات Google" منح الأعمدة أو الصفوف الجديدة الخصائص نفسها التي كانت متوفّرة للصف أو العمود السابق، وإذا كانت القيمة خاطئة، يطلب منها منح الأعمدة أو الصفوف الجديدة الخصائص نفسها التي كانت متوفّرة للأبعاد. لا يمكن أن تكون قيمة inheritFromBefore صحيحة إذا كنت تريد إدراج صف في الصف 1 أو عمود في العمود A.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "insertDimension": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "COLUMNS",
          "startIndex": 2,
          "endIndex": 4
        },
        "inheritFromBefore": true
      }
    },
    {
      "insertDimension": {
        "range": {
          "sheetId": SHEET_ID,
          "dimension": "ROWS",
          "startIndex": 0,
          "endIndex": 3
        },
        "inheritFromBefore": false
      }
    },
  ],
}

نقل صف أو عمود

يوضّح نموذج الرمز البرمجي spreadsheets.batchUpdate التالي كيفية استخدام MoveDimensionRequest لنقل العمود A إلى موضع العمود D. يؤدي طلب ثانٍ إلى نقل الصفوف من 5 إلى 10 إلى الموضع 20.

يحدّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة جدول. يحدّد الحقل destinationIndex المكان الذي سيتم نقل بيانات المصدر إليه باستخدام فهرس بدء مستند إلى الصفر.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "moveDimension": {
        "source": {
          "sheetId": SHEET_ID,
          "dimension": "COLUMNS",
          "startIndex": 0,
          "endIndex": 1
        },
        "destinationIndex": 3
      }
    },
    {
      "moveDimension": {
        "source": {
          "sheetId": SHEET_ID,
          "dimension": "ROWS",
          "startIndex": 4,
          "endIndex": 10
        },
        "destinationIndex": 19
      }
    },
  ],
}