Google Apps Script: Как вернуть несколько значений?

В Google Apps Script, как и в JavaScript, функция может возвращать только одно значение. Однако, часто возникает необходимость вернуть несколько связанных значений. В этой статье мы рассмотрим несколько способов достижения этой цели.

Зачем возвращать несколько значений?

Представьте себе ситуацию, когда вам нужно получить данные из Google Sheets, обработать их и вернуть не только результат вычислений, но и статус операции (например, успешно/неуспешно) и сообщение об ошибке, если она возникла. В таких случаях, возврат нескольких значений становится необходимым.

Обзор методов возврата нескольких значений

Существует два основных способа возврата нескольких значений в Google Apps Script:

Использование массива.

Использование объекта JavaScript.

Использование массива для возврата нескольких значений

Массив представляет собой упорядоченный список значений. Он идеально подходит для возврата набора данных, где порядок имеет значение.

Создание и заполнение массива

Создание массива в Google Apps Script выполняется следующим образом:

var myArray = []; // Создание пустого массива
var myArray = [1, 2, 3]; // Создание массива с элементами

Заполнение массива элементами:

myArray[0] = "John";
myArray[1] = "Doe";

Возврат массива из функции

Чтобы вернуть массив из функции, просто используйте оператор return:

function myFunction() {
  var myArray = [1, 2, 3];
  return myArray;
}

Пример кода: Возврат имени и фамилии

/**
 * Возвращает имя и фамилию.
 *
 * @returns {string[]} Массив, содержащий имя и фамилию.
 */
function getNameAndLastName(): string[] {
  const firstName: string = "John";
  const lastName: string = "Doe";
  return [firstName, lastName];
}

// Пример использования
function testGetNameAndLastName() {
  const nameData: string[] = getNameAndLastName();
  Logger.log(nameData[0]); // John
  Logger.log(nameData[1]); // Doe
}

Обращение к элементам массива после возврата

После возврата массива из функции, вы можете получить доступ к его элементам по индексу:

var result = myFunction();
var firstElement = result[0]; // Доступ к первому элементу

Использование объекта JavaScript для возврата нескольких значений

Объект JavaScript представляет собой коллекцию пар ключ-значение. Он подходит для возврата связанных данных, где важна именованная структура.

Создание объекта с ключами и значениями

Создание объекта:

var myObject = {}; // Создание пустого объекта
var myObject = {name: "John", age: 30}; // Создание объекта с данными

Возврат объекта из функции

Возврат объекта из функции выполняется аналогично массиву:

function myFunction() {
  var myObject = {name: "John", age: 30};
  return myObject;
}

Пример кода: Возврат адреса (улица, город, индекс)

/**
 * Возвращает объект, содержащий адрес.
 *
 * @returns {{street: string, city: string, zip: string}} Объект с адресом.
 */
function getAddress(): { street: string; city: string; zip: string } {
  const street: string = "123 Main St";
  const city: string = "Anytown";
  const zip: string = "12345";
  return { street: street, city: city, zip: zip };
}

// Пример использования
function testGetAddress() {
  const address: { street: string; city: string; zip: string } = getAddress();
  Logger.log(address.street); // 123 Main St
  Logger.log(address.city); // Anytown
  Logger.log(address.zip); // 12345
}

Доступ к свойствам объекта после возврата

Для доступа к свойствам объекта используйте точечную нотацию или квадратные скобки:

var result = myFunction();
var name = result.name; // Доступ к свойству 'name'
var age = result['age']; // Доступ к свойству 'age'

Преимущества и недостатки различных методов

Сравнение массивов и объектов

Массивы:

Преимущества: Простота, упорядоченность.

Недостатки: Сложность запоминания индексов, менее читаемый код.

Объекты:

Преимущества: Читаемый код, удобный доступ к данным по имени.

Недостатки: Неупорядоченность (до ES6), немного сложнее в создании.

Когда использовать массив?

Используйте массив, когда порядок возвращаемых значений важен и их смысл понятен из контекста. Например, координаты точки (x, y).

Когда использовать объект?

Используйте объект, когда возвращаемые значения имеют разный смысл и требуют именования для улучшения читаемости кода. Например, данные пользователя (имя, фамилия, возраст).

Примеры реальных задач и решений

Получение данных из Google Sheets и их обработка

Предположим, у вас есть функция, которая считывает данные из Google Sheets, выполняет вычисления и должна вернуть результат, а также статус выполнения. Используйте объект для возврата:

function processSheetData(sheetId: string): { result: number; status: string; error?: string } {
  try {
    const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.openById(sheetId);
    const sheet: GoogleAppsScript.Spreadsheet.Sheet = ss.getActiveSheet();
    const data: any[][] = sheet.getDataRange().getValues();

    // Здесь производим необходимые вычисления
    let sum: number = 0;
    for (let i = 1; i < data.length; i++) { // Предполагаем, что первая строка - заголовок
      sum += Number(data[i][0]); // Суммируем значения из первого столбца
    }

    return { result: sum, status: "success" };
  } catch (e: any) {
    return { result: 0, status: "error", error: e.message };
  }
}

function testProcessSheetData(){
  const result = processSheetData("your_sheet_id");
  Logger.log(result);
}

Возврат результатов выполнения API-запроса

При работе с API, часто требуется возвращать не только данные, полученные из API, но и код ответа (HTTP status code). Опять же, объект – отличный выбор:

function fetchApiData(url: string): { data: any; statusCode: number; error?: string } {
  try {
    const response: GoogleAppsScript.URL_Fetch.HTTPResponse = UrlFetchApp.fetch(url);
    const statusCode: number = response.getResponseCode();
    const data: any = JSON.parse(response.getContentText());

    return { data: data, statusCode: statusCode };
  } catch (e: any) {
    return { data: null, statusCode: 500, error: e.message };
  }
}

Создание пользовательских функций для Google Sheets

Предположим, вы создаете пользовательскую функцию для Google Sheets, которая должна возвращать отформатированное значение и комментарий. Вы можете вернуть массив, где первый элемент – отформатированное значение, а второй – комментарий.

В заключение, выбор метода возврата нескольких значений зависит от конкретной задачи. Массивы подходят для простых случаев, где важен порядок, а объекты – для сложных ситуаций, где требуется именованная структура данных.