سرویس برگه های پیشرفته

از Apps Script برای خواندن، ویرایش، قالب‌بندی و ارائه داده‌ها در Google Sheets.

سرویس Advanced Sheets به شما امکان می‌دهد با استفاده از Google Apps Script به API Sheets دسترسی داشته باشید. این API دقیقاً مانند سرویس داخلی Google Sheets API در Apps Script، به اسکریپت‌ها اجازه می‌دهد داده‌ها را در Google Sheets بخوانند، ویرایش کنند، قالب‌بندی کنند و ارائه دهند. در بیشتر موارد، استفاده از سرویس داخلی آسان‌تر است، اما این سرویس پیشرفته چند ویژگی اضافی نیز ارائه می‌دهد.

این یک سرویس پیشرفته است که قبل از استفاده باید فعال شود.

مرجع

برای اطلاعات دقیق در مورد این سرویس، به مستندات مرجع API مربوط به Sheets مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس پیشرفته Sheets از همان اشیاء، متدها و پارامترهای API عمومی استفاده می‌کند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای متد» مراجعه کنید.

برای گزارش مشکلات و یافتن پشتیبانی‌های دیگر، به راهنمای پشتیبانی Sheets مراجعه کنید.

کد نمونه

کد نمونه زیر از نسخه ۴ این API استفاده می‌کند؛ این تنها نسخه از API مربوط به Sheets است که به عنوان یک سرویس پیشرفته در Apps Script موجود است.

خواندن مقادیر از یک محدوده

مثال زیر نحوه خواندن مقادیر داده از یک محدوده مشخص در یک برگه را با سرویس پیشرفته Sheets نشان می‌دهد. این معادل نمونه دستور پخت تک محدوده‌ای «خواندن» است.

پیشرفته/sheets.gs

مشاهده در گیت‌هاب

/**
 * Read a range (A1:D5) of data values. Logs the values.
 * @param {string} spreadsheetId The spreadsheet ID to read from.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/get
 */
function readRange(spreadsheetId = yourspreadsheetId) {
  try {
    const response = Sheets.Spreadsheets.Values.get(
      spreadsheetId,
      "Sheet1!A1:D5",
    );
    if (response.values) {
      console.log(response.values);
      return;
    }
    console.log("Failed to get range of values from spreadsheet");
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", e.message);
  }
}

نوشتن مقادیر در چندین محدوده

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

پیشرفته/sheets.gs

مشاهده در گیت‌هاب

/**
 * Write to multiple, disjoint data ranges.
 * @param {string} spreadsheetId The spreadsheet ID to write to.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate
 */
function writeToMultipleRanges(spreadsheetId = yourspreadsheetId) {
  // Specify some values to write to the sheet.
  const columnAValues = [["Item", "Wheel", "Door", "Engine"]];
  const rowValues = [
    ["Cost", "Stocked", "Ship Date"],
    ["$20.50", "4", "3/1/2016"],
  ];

  const request = {
    valueInputOption: "USER_ENTERED",
    data: [
      {
        range: "Sheet1!A1:A4",
        majorDimension: "COLUMNS",
        values: columnAValues,
      },
      {
        range: "Sheet1!B1:D2",
        majorDimension: "ROWS",
        values: rowValues,
      },
    ],
  };
  try {
    const response = Sheets.Spreadsheets.Values.batchUpdate(
      request,
      spreadsheetId,
    );
    if (response) {
      console.log(response);
      return;
    }
    console.log("response null");
  } catch (e) {
    // TODO (developer) - Handle  exception
    console.log("Failed with error %s", e.message);
  }
}

اضافه کردن برگه جدید

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

پیشرفته/sheets.gs

مشاهده در گیت‌هاب

/**
 * Add a new sheet with some properties.
 * @param {string} spreadsheetId The spreadsheet ID.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate
 */
function addSheet(spreadsheetId = yourspreadsheetId) {
  const requests = [
    {
      addSheet: {
        properties: {
          title: "Deposits",
          gridProperties: {
            rowCount: 20,
            columnCount: 12,
          },
          tabColor: {
            red: 1.0,
            green: 0.3,
            blue: 0.4,
          },
        },
      },
    },
  ];
  try {
    const response = Sheets.Spreadsheets.batchUpdate(
      { requests: requests },
      spreadsheetId,
    );
    console.log(
      `Created sheet with ID: ${response.replies[0].addSheet.properties.sheetId}`,
    );
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", e.message);
  }
}

ایجاد یک جدول محوری

مثال زیر نحوه ایجاد یک جدول محوری از داده‌های منبع را نشان می‌دهد. این معادل نمونه دستور العمل افزودن جدول محوری است.

پیشرفته/sheets.gs

مشاهده در گیت‌هاب

/**
 * Add a pivot table.
 * @param {string} spreadsheetId The spreadsheet ID to add the pivot table to.
 * @param {string} pivotSourceDataSheetId The sheet ID to get the data from.
 * @param {string} destinationSheetId The sheet ID to add the pivot table to.
 * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate
 */
function addPivotTable(
  spreadsheetId = yourspreadsheetId,
  pivotSourceDataSheetId = yourpivotSourceDataSheetId,
  destinationSheetId = yourdestinationSheetId,
) {
  const requests = [
    {
      updateCells: {
        rows: {
          values: [
            {
              pivotTable: {
                source: {
                  sheetId: pivotSourceDataSheetId,
                  startRowIndex: 0,
                  startColumnIndex: 0,
                  endRowIndex: 20,
                  endColumnIndex: 7,
                },
                rows: [
                  {
                    sourceColumnOffset: 0,
                    showTotals: true,
                    sortOrder: "ASCENDING",
                    valueBucket: {
                      buckets: [
                        {
                          stringValue: "West",
                        },
                      ],
                    },
                  },
                  {
                    sourceColumnOffset: 1,
                    showTotals: true,
                    sortOrder: "DESCENDING",
                    valueBucket: {},
                  },
                ],
                columns: [
                  {
                    sourceColumnOffset: 4,
                    sortOrder: "ASCENDING",
                    showTotals: true,
                    valueBucket: {},
                  },
                ],
                values: [
                  {
                    summarizeFunction: "SUM",
                    sourceColumnOffset: 3,
                  },
                ],
                valueLayout: "HORIZONTAL",
              },
            },
          ],
        },
        start: {
          sheetId: destinationSheetId,
          rowIndex: 49,
          columnIndex: 0,
        },
        fields: "pivotTable",
      },
    },
  ];
  try {
    const response = Sheets.Spreadsheets.batchUpdate(
      { requests: requests },
      spreadsheetId,
    );
    // The Pivot table will appear anchored to cell A50 of the destination sheet.
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", e.message);
  }
}