Функции Google Apps Script: какие аргументы можно использовать?

11.09.2025
51491

5 мин
125

Что такое аргументы функций и зачем они нужны?

Аргументы функций – это значения, которые передаются в функцию при её вызове. Они позволяют сделать функции более гибкими и универсальными, позволяя им оперировать разными данными и выполнять различные действия в зависимости от переданных аргументов. Без аргументов, функция была бы ограничена в работе с фиксированным набором данных и не могла бы адаптироваться к различным сценариям использования. Аргументы позволяют параметризировать поведение функции.

Обзор синтаксиса функций с аргументами в Google Apps Script

В Google Apps Script (GAS) синтаксис определения функций с аргументами выглядит следующим образом:

/**
 * Описание функции.
 *
 * @param {тип_аргумента1} имя_аргумента1 Описание аргумента1.
 * @param {тип_аргумента2} имя_аргумента2 Описание аргумента2.
 * @return {тип_возвращаемого_значения} Описание возвращаемого значения.
 */
function имяФункции(имя_аргумента1, имя_аргумента2) {
  // Тело функции, использующее аргументы.
  return результат;
}

Например:

/**
 * Складывает два числа.
 *
 * @param {number} a Первое число.
 * @param {number} b Второе число.
 * @return {number} Сумма двух чисел.
 */
function add(a, b) {
  return a + b;
}

let sum = add(5, 3); // sum будет равно 8

Типы аргументов, поддерживаемые в Google Apps Script

Примитивные типы данных (числа, строки, логические значения)

Google Apps Script поддерживает передачу в функции примитивных типов данных, таких как:

number: Числа (целые и с плавающей точкой).

string: Строки.

boolean: Логические значения (true или false).

null: Представляет отсутствие значения.

undefined: Значение не определено.

Пример:

/**
 * Форматирует строку, добавляя префикс и суффикс.
 *
 * @param {string} str Исходная строка.
 * @param {string} prefix Префикс.
 * @param {string} suffix Суффикс.
 * @return {string} Отформатированная строка.
 */
function formatString(str, prefix, suffix) {
  return prefix + str + suffix;
}

let formatted = formatString("Hello", ""); // formatted будет равно ""

Объекты (массивы, даты, объекты Google Apps Script)

Функции GAS могут принимать объекты в качестве аргументов. Это включает в себя массивы, даты и объекты, предоставляемые самим Google Apps Script (например, Spreadsheet, Document, MailApp).

Пример работы с массивом:

/**
 * Вычисляет сумму элементов массива.
 *
 * @param {number[]} arr Массив чисел.
 * @return {number} Сумма элементов массива.
 */
function sumArray(arr) {
  let sum = 0;
  for (let i = 0; i < arr.length; i++) {
    sum += arr[i];
  }
  return sum;
}

let numbers = [1, 2, 3, 4, 5];
let total = sumArray(numbers); // total будет равно 15

Пример работы с объектом Date:

/**
 * Форматирует дату в строку.
 *
 * @param {Date} date Объект Date.
 * @return {string} Отформатированная дата.
 */
function formatDate(date) {
  return Utilities.formatDate(date, Session.getTimeZone(), 'yyyy-MM-dd');
}

let today = new Date();
let formattedDate = formatDate(today); // formattedDate будет равно текущей дате в формате yyyy-MM-dd

Функции как аргументы (callback-функции)

Google Apps Script поддерживает передачу функций в качестве аргументов другим функциям. Это позволяет реализовать паттерн callback, когда одна функция вызывает другую функцию, переданную ей в качестве аргумента, для выполнения определенной задачи.

Пример:

/**
 * Выполняет операцию над каждым элементом массива и возвращает новый массив с результатами.
 *
 * @param {number[]} arr Исходный массив.
 * @param {function(number): number} callback Функция, применяемая к каждому элементу массива.
 * @return {number[]} Новый массив с результатами применения callback-функции.
 */
function mapArray(arr, callback) {
  let result = [];
  for (let i = 0; i < arr.length; i++) {
    result.push(callback(arr[i]));
  }
  return result;
}

/**
 * Удваивает число.
 *
 * @param {number} x Число.
 * @return {number} Удвоенное число.
 */
function double(x) {
  return x * 2;
}

let numbers = [1, 2, 3];
let doubledNumbers = mapArray(numbers, double); // doubledNumbers будет равно [2, 4, 6]

Передача аргументов в функции Google Apps Script

Передача по значению и по ссылке: особенности Google Apps Script

В Google Apps Script, примитивные типы данных (числа, строки, логические значения) передаются по значению. Это означает, что функция получает копию значения, и изменение этого значения внутри функции не влияет на исходную переменную. Объекты же передаются по ссылке. Функция получает ссылку на объект, и изменение объекта внутри функции отразится на исходном объекте.

Пример:

function modifyValue(x, obj) {
  x = 10;
  obj.value = 20;
}

let a = 5;
let b = { value: 15 };

modifyValue(a, b);

// a останется равным 5, так как передается по значению
// b.value станет равным 20, так как объект передается по ссылке

Использование оператора `…` для передачи переменного числа аргументов

Оператор ... (rest operator) позволяет функции принимать переменное число аргументов. Эти аргументы будут собраны в массив внутри функции.

Пример:

/**
 * Суммирует переменное число аргументов.
 *
 * @param {...number} numbers Переменное число чисел.
 * @return {number} Сумма чисел.
 */
function sumAll(...numbers) {
  let sum = 0;
  for (let number of numbers) {
    sum += number;
  }
  return sum;
}

let total = sumAll(1, 2, 3, 4, 5); // total будет равно 15

Работа с необязательными и именованными аргументами

Реализация необязательных аргументов с использованием `if` и значений по умолчанию

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

Пример:

/**
 * Умножает два числа. Второй аргумент необязательный (значение по умолчанию - 1).
 *
 * @param {number} a Первое число.
 * @param {number} [b=1] Второе число (необязательный).
 * @return {number} Произведение двух чисел.
 */
function multiply(a, b) {
  if (b === undefined) {
    b = 1; // Значение по умолчанию
  }
  return a * b;
}

let result1 = multiply(5, 2); // result1 будет равно 10
let result2 = multiply(5);    // result2 будет равно 5 (5 * 1)

Эмуляция именованных аргументов с помощью объектов

Именованные аргументы, как и необязательные, не поддерживаются напрямую. Однако, можно передавать аргументы в виде объекта, где ключи объекта будут представлять имена аргументов.

Пример:

/**
 * Создает HTML-элемент с заданными атрибутами.
 *
 * @param {Object} options Объект с атрибутами элемента.
 * @param {string} options.tag Имя тега (обязательный).
 * @param {string} [options.id] ID элемента (необязательный).
 * @param {string} [options.class] Класс элемента (необязательный).
 * @return {string} HTML-элемент.
 */
function createHTMLElement(options) {
  let tag = options.tag;
  let id = options.id || '';
  let className = options.class || '';

  let html = '';
  html += '';

  return html;
}

let element = createHTMLElement({ tag: 'div', id: 'myDiv', class: 'container' });
// element будет равно '
'

Примеры использования аргументов функций в Google Apps Script

Чтение данных из Google Sheets с использованием аргументов для указания диапазона

/**
 * Считывает данные из Google Sheets в заданном диапазоне.
 *
 * @param {string} spreadsheetId ID таблицы Google Sheets.
 * @param {string} sheetName Название листа.
 * @param {string} range Диапазон ячеек (например, "A1:B10").
 * @return {any[][]} Двумерный массив с данными из таблицы.
 */
function readDataFromSheet(spreadsheetId, sheetName, range) {
  let spreadsheet = SpreadsheetApp.openById(spreadsheetId);
  let sheet = spreadsheet.getSheetByName(sheetName);
  let dataRange = sheet.getRange(range);
  let values = dataRange.getValues();
  return values;
}

// Пример использования:
// let data = readDataFromSheet("YOUR_SPREADSHEET_ID", "Sheet1", "A1:C5");

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

/**
 * Отправляет email-сообщение.
 *
 * @param {string} recipient Адрес получателя.
 * @param {string} subject Тема письма.
 * @param {string} body Тело письма.
 * @param {object} options Дополнительные параметры отправки.
 */
function sendEmail(recipient, subject, body, options = {}) {
  MailApp.sendEmail(recipient, subject, body, options);
}

// Пример использования:
// sendEmail("user@example.com", "Тема письма", "Текст письма");

Создание пользовательских диалоговых окон с динамическим контентом, передаваемым через аргументы

/**
 * Отображает пользовательское диалоговое окно с заданным сообщением.
 *
 * @param {string} title Заголовок диалогового окна.
 * @param {string} message Сообщение в диалоговом окне.
 */
function showCustomDialog(title, message) {
  let ui = SpreadsheetApp.getUi();
  let result = ui.alert(
    title,
    message,
    ui.ButtonSet.OK
  );
}

// Пример использования:
// showCustomDialog("Внимание", "Произошла ошибка!");

Добавить комментарий

Google Apps Script: Как получить длину массива?

Что такое массив и зачем он нужен? Массив в Google Apps Script, как и в большинстве языков программирования, представляет собой упорядоченную коллекцию элементов.

93
2025

Google Apps Script: Как получить уникальные значения?

В Google Apps Script, как и в любом другом языке программирования, часто возникает необходимость получения уникальных значений из массива или диапазона данных.

93
2025

Как инициализировать массив в Google Apps Script: Полное руководство

Что такое массив и зачем он нужен? Массив – это упорядоченная коллекция элементов, каждый из которых имеет свой индекс.

93
2025