ردیف & عملیات ستون

Google Sheets API به شما امکان می‌دهد سطرها و ستون‌ها را در برگه‌ها اضافه، حذف و دستکاری کنید. مثال‌های موجود در این صفحه نشان می‌دهند که چگونه می‌توان برخی از عملیات‌های رایج سطر و ستون را با Sheets API به دست آورد.

این نمونه ها در قالب درخواست های HTTP برای خنثی بودن زبان ارائه شده اند. برای یادگیری نحوه اجرای یک به‌روزرسانی دسته‌ای به زبان‌های مختلف با استفاده از کتابخانه‌های سرویس گیرنده Google API، به به‌روزرسانی صفحات گسترده مراجعه کنید.

در این مثال‌ها، متغیرهای SPREADSHEET_ID و SHEET_ID نشان می‌دهند که کجا آن شناسه‌ها را ارائه می‌کنید. می‌توانید شناسه صفحه‌گسترده را در URL صفحه‌گسترده پیدا کنید. با استفاده از روش spreadsheets.get می توانید شناسه برگه را دریافت کنید. محدوده ها با استفاده از نماد A1 مشخص می شوند. محدوده نمونه Sheet1!A1:D5 است.

عرض ستون یا ارتفاع ردیف را تنظیم کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از UpdateDimensionPropertiesRequest را برای به روز رسانی ویژگی عرض ستون A به 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 یا یک ستون در ستون 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
      }
    },
  ],
}