Что такое параметры функций и зачем они нужны
Параметры функций – это входные данные, которые вы передаете функции для выполнения определенных задач. Они позволяют делать функции более гибкими и повторно используемыми. Без параметров, функция была бы ограничена выполнением только одной предопределенной операции с жестко закодированными данными. Параметры позволяют функциям принимать разные входные значения и адаптировать свое поведение в соответствии с этими значениями, что значительно расширяет их функциональность.
Объявление функций с параметрами в Google Apps Script
В Google Apps Script объявление функции с параметрами выполняется следующим образом:
/**
* Функция для расчета ROI (Return on Investment).
* @param {number} investment Сумма инвестиций.
* @param {number} revenue Доход от инвестиций.
* @return {number} ROI в процентах.
*/
function calculateROI(investment, revenue) {
// Проверка на нулевые инвестиции для избежания деления на ноль.
if (investment === 0) {
return 0; // Или можно выбросить ошибку: throw new Error("Инвестиции не могут быть равны нулю");
}
const roi = ((revenue - investment) / investment) * 100;
return roi;
}В этом примере investment и revenue – это параметры функции calculateROI. При вызове функции вы передаете значения этих параметров, которые будут использоваться внутри функции для вычислений.
Область применения параметров и переменных
Область видимости параметров и переменных внутри функции ограничена этой функцией. Это означает, что вы не можете получить доступ к параметрам или переменным, объявленным внутри функции, извне этой функции. Это помогает избежать конфликтов имен и делает код более модульным и предсказуемым. Глобальные переменные, объявленные вне функций, доступны изнутри функций, но их использование следует минимизировать для улучшения читаемости и поддерживаемости кода.
Типы параметров в Google Apps Script
Основные типы данных: строки, числа, логические значения
Google Apps Script поддерживает следующие основные типы данных, которые можно использовать в качестве параметров функций:
string: Текстовые строки (например, "Google Ads").
number: Числа (например, 123, 3.14).
boolean: Логические значения (например, true, false).
Примеры:
/**
* Функция для логирования сообщения с заданным уровнем.
* @param {string} message Сообщение для логирования.
* @param {number} logLevel Уровень логирования (1 - INFO, 2 - WARNING, 3 - ERROR).
*/
function logMessage(message, logLevel) {
// ... код для логирования ...
}Объекты и массивы в качестве параметров
Вы также можете передавать объекты и массивы в качестве параметров. Это особенно полезно для передачи сложных структур данных в функцию.
/**
* Функция для обновления данных в Google Sheets.
* @param {Object} data Объект с данными для обновления (ключи - заголовки столбцов, значения - данные).
* @param {string} sheetName Название листа Google Sheets.
*/
function updateSheetData(data, sheetName) {
// ... код для обновления данных ...
}Использование типа ‘variant’ для гибкости
Тип variant позволяет передавать параметры любого типа. Однако, следует использовать его с осторожностью, так как это может усложнить отладку и понимание кода. Рекомендуется явно указывать тип параметра, если это возможно, для повышения читаемости и надежности кода.
Передача параметров в функции
Передача по значению vs. передача по ссылке
В Google Apps Script примитивные типы данных (строки, числа, логические значения) передаются по значению, а объекты и массивы – по ссылке. Это означает, что при передаче по значению функция получает копию значения параметра, а при передаче по ссылке функция получает ссылку на исходный объект или массив.
Передача примитивных типов и объектов
При передаче примитивных типов изменение параметра внутри функции не влияет на исходное значение переменной, переданной в качестве аргумента.
При передаче объектов и массивов изменение свойств объекта или элементов массива внутри функции отразится на исходном объекте или массиве, так как функция работает с ссылкой на этот объект/массив.
Изменение параметров внутри функции и его влияние на внешнюю среду
function modifyArray(arr) {
arr.push(4); // Изменяем массив, переданный по ссылке
}
let myArray = [1, 2, 3];
modifyArray(myArray);
Logger.log(myArray); // Вывод: [1, 2, 3, 4] - исходный массив был изменен
function modifyNumber(num) {
num = num + 1; // Изменяем число, переданное по значению
}
let myNumber = 5;
modifyNumber(myNumber);
Logger.log(myNumber); // Вывод: 5 - исходное число не было измененоДополнительные возможности работы с параметрами
Необязательные параметры: установка значений по умолчанию
В Google Apps Script нет встроенной поддержки необязательных параметров с значениями по умолчанию, как в некоторых других языках программирования. Однако, вы можете реализовать эту функциональность, проверяя наличие параметра и присваивая ему значение по умолчанию, если он не был передан.
/**
* Функция для поиска ключевых слов в тексте.
* @param {string} text Текст для поиска.
* @param {string} [keywords=""] Ключевые слова для поиска (необязательный параметр). Если не указан, поиск не производится.
*/
function findKeywords(text, keywords) {
if (keywords === undefined) {
keywords = ""; // Значение по умолчанию
}
if (keywords) {
// Выполняем поиск ключевых слов
}
// ... остальной код ...
}Аргументы переменной длины (использование arguments)
Объект arguments предоставляет доступ к массиву аргументов, переданных в функцию, независимо от того, сколько параметров было объявлено в определении функции. Это позволяет создавать функции, которые могут принимать переменное количество аргументов.
function sumArguments() {
let sum = 0;
for (let i = 0; i < arguments.length; i++) {
sum += arguments[i];
}
return sum;
}
Logger.log(sumArguments(1, 2, 3, 4, 5)); // Вывод: 15Использование JSDoc для документирования параметров
Используйте JSDoc для документирования параметров функций. Это помогает другим разработчикам (и вам в будущем) понимать, какие параметры ожидает функция и какого типа.
/**
* Функция для форматирования числа как валюты.
* @param {number} number Число для форматирования.
* @param {string} [currency="USD"] Валюта (ISO код валюты). По умолчанию USD.
* @param {string} [locale="en-US"] Локаль для форматирования. По умолчанию en-US.
* @return {string} Отформатированное число как валюта.
*/
function formatCurrency(number, currency, locale) {
// ... код для форматирования ...
}Практические примеры использования параметров функций
Пример 1: Функция для форматирования даты с разными параметрами
/**
* Форматирует дату в соответствии с заданным форматом и локалью.
* @param {Date} date Объект Date для форматирования.
* @param {string} format Строка формата даты (например, 'yyyy-MM-dd').
* @param {string} locale Локаль для форматирования даты (например, 'ru-RU').
* @return {string} Отформатированная дата.
*/
function formatDate(date, format, locale) {
const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'short' }); // Использовать dateStyle для упрощения
return Utilities.formatDate(date, Session.getTimeZone(), format);
}
// Пример использования:
const today = new Date();
const formattedDate = formatDate(today, 'yyyy-MM-dd', 'ru-RU');
Logger.log(formattedDate);Пример 2: Функция для обработки данных из Google Sheets с передачей диапазона в качестве параметра
/**
* Обрабатывает данные из указанного диапазона Google Sheets.
* @param {string} spreadsheetId ID Google Sheets.
* @param {string} range Строка, определяющая диапазон (например, 'A1:B10').
* @return {Array<Array>} Двумерный массив с данными из диапазона.
*/
function processSheetData(spreadsheetId, range) {
const ss = SpreadsheetApp.openById(spreadsheetId);
const sheet = ss.getActiveSheet();
const dataRange = sheet.getRange(range);
const values = dataRange.getValues();
return values;
}
// Пример использования:
const spreadsheetId = 'your_spreadsheet_id';
const range = 'A1:C5';
const data = processSheetData(spreadsheetId, range);
Logger.log(data);Пример 3: Функция для отправки email с настраиваемыми параметрами отправителя, получателя и тела письма
/**
* Отправляет email с заданными параметрами.
* @param {string} recipient Email получателя.
* @param {string} subject Тема письма.
* @param {string} body Тело письма.
* @param {Object} [options={}] Объект с дополнительными опциями (например, cc, bcc, replyTo).
*/
function sendEmail(recipient, subject, body, options = {}) {
const emailOptions = {
to: recipient,
subject: subject,
body: body
};
// Добавляем опции, если они переданы
if (options.cc) {
emailOptions.cc = options.cc;
}
if (options.bcc) {
emailOptions.bcc = options.bcc;
}
if (options.replyTo) {
emailOptions.replyTo = options.replyTo;
}
MailApp.sendEmail(emailOptions);
}
// Пример использования:
sendEmail('recipient@example.com', 'Привет!', 'Это тестовое письмо.', {cc: 'cc@example.com'});