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

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

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

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

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

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از UpdateDimensionPropertiesRequest را برای به‌روزرسانی ویژگی عرض ستون A به ۱۶۰ پیکسل نشان می‌دهد. درخواست دوم، ویژگی ارتفاع ردیف سه ردیف اول را به ۴۰ پیکسل به‌روزرسانی می‌کند. فیلد 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 درج می‌کند. درخواست دوم سه ردیف خالی را که از ردیف ۱ شروع می‌شوند، درج می‌کند.

فیلد dimension تعیین می‌کند که آیا عملیات روی ستون‌ها یا ردیف‌های یک برگه اعمال می‌شود یا خیر.

اگر درست باشد، فیلد inheritFromBefore به Sheets API می‌گوید که به ستون‌ها یا ردیف‌های جدید همان ویژگی‌های ردیف یا ستون قبلی را بدهد و اگر نادرست باشد، از ابعاد بعد از ستون‌ها یا ردیف‌های جدید ارث‌بری کند. inheritFromBefore نمی‌تواند درست باشد اگر یک ردیف در ردیف ۱ یا یک ستون در ستون 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 نشان می‌دهد. درخواست دوم ردیف‌های ۵ تا ۱۰ را به موقعیت ردیف ۲۰ منتقل می‌کند.

فیلد 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
      }
    },
  ],
}