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

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

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

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

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

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الرمز UpdateDimensionPropertiesRequest لتعديل سمة العرض للعمود "أ" إلى 160 بكسل. يُعدّل طلب ثانٍ سمة ارتفاع الصفوف في الصفوف الثلاثة الأولى لتكون 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
      }
    }
  ]
}

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

يوضِّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الرمز AutoResizeDimensionsRequest لتغيير حجم الأعمدة A:C استنادًا إلى حجم محتوى العمود. يشير الحقل 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 صحيحًا، يطلب من واجهة برمجة التطبيقات Sheets API منح الأعمدة أو الصفوف الجديدة السمات نفسها التي يمتلكها الصف أو العمود السابقان، وإذا كان الحقل خطأ، يتم اكتساب السمات من السمات التي تلي الأعمدة أو الصفوف الجديدة. لا يمكن أن تكون inheritFromBefore صحيحة في حال إدراج صف في الصف 1 أو عمود في عمود "أ".

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

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 لنقل العمود "أ" إلى موضع العمود "د". ينقل طلب ثانٍ الصفوف 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
      }
    },
  ],
}