Google Apps Script: Как создать массив?

Что такое массив и зачем он нужен?

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

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Массивы особенно полезны в задачах, связанных с:

• Обработкой данных из Google Sheets.
• Формированием отчетов.
• Управлением списками пользователей.
• Реализацией сложных алгоритмов.

Объявление массива: основные способы

В Google Apps Script существует несколько способов объявления массива:

• Использование литералов массива (наиболее распространенный способ).
• Использование конструктора Array().

Создание массивов в Google Apps Script

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

Литералы массива – это самый простой и предпочтительный способ создания массивов. Элементы массива заключаются в квадратные скобки [] и разделяются запятыми.

/**
 * Создает массив ключевых слов для рекламной кампании.
 * @return {string[]} Массив ключевых слов.
 */
function createKeywordsArray(): string[] {
  const keywords: string[] = ['купить', 'заказать', 'цена', 'доставка'];
  return keywords;
}

Создание массива с помощью конструктора Array()

Конструктор Array() – менее распространенный способ, но иногда может быть полезен, особенно при создании массивов с заданным размером.

/**
 * Создает массив заданного размера.
 * @param {number} size Размер массива.
 * @return {number[]} Массив, заполненный null значениями.
 */
function createEmptyArray(size: number): (number | null)[] {
  const myArray: (number | null)[] = new Array(size);
  for (let i = 0; i < size; i++) {
    myArray[i] = null; // Или любое другое значение по умолчанию
  }
  return myArray;
}

Создание многомерных массивов

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

/**
 * Создает матрицу (двумерный массив).
 * @param {number} rows Количество строк.
 * @param {number} cols Количество столбцов.
 * @return {number[][]} Матрица, заполненная нулями.
 */
function createMatrix(rows: number, cols: number): number[][] {
  const matrix: number[][] = [];
  for (let i = 0; i < rows; i++) {
    matrix[i] = new Array(cols).fill(0);
  }
  return matrix;
}

Работа с элементами массива

Доступ к элементам массива по индексу

Доступ к элементам массива осуществляется по индексу, начиная с 0.

/**
 * Получает ключевое слово по индексу.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {number} index Индекс элемента.
 * @return {string | undefined} Ключевое слово по индексу, или undefined, если индекс вне диапазона.
 */
function getKeywordByIndex(keywords: string[], index: number): string | undefined {
  return keywords[index];
}

Добавление элементов в массив: push(), unshift()

• push() – добавляет элемент в конец массива.
• unshift() – добавляет элемент в начало массива.

/**
 * Добавляет ключевое слово в массив.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {string} keyword Новое ключевое слово.
 * @param {boolean} toBeginning Добавить в начало, если true, иначе - в конец.
 * @return {number} Новая длина массива.
 */
function addKeyword(keywords: string[], keyword: string, toBeginning: boolean = false): number {
  if (toBeginning) {
    return keywords.unshift(keyword);
  } else {
    return keywords.push(keyword);
  }
}

Удаление элементов из массива: pop(), shift(), splice()

• pop() – удаляет последний элемент массива.
• shift() – удаляет первый элемент массива.
• splice() – удаляет элементы из массива, начиная с указанного индекса.

/**
 * Удаляет ключевое слово из массива.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {number} index Индекс удаляемого элемента.
 * @param {number} deleteCount Количество удаляемых элементов, начиная с index.
 * @return {string[]} Массив удаленных элементов.
 */
function removeKeyword(keywords: string[], index: number, deleteCount: number = 1): string[] {
  return keywords.splice(index, deleteCount);
}

Изменение значений элементов массива

Значения элементов массива можно изменять, обращаясь к ним по индексу.

/**
 * Изменяет ключевое слово в массиве.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {number} index Индекс изменяемого элемента.
 * @param {string} newKeyword Новое ключевое слово.
 * @return {void}
 */
function updateKeyword(keywords: string[], index: number, newKeyword: string): void {
  keywords[index] = newKeyword;
}

Методы массивов в Google Apps Script

Перебор массива: for, forEach()

• for – классический цикл для перебора элементов массива.
• forEach() – метод, позволяющий выполнить функцию для каждого элемента массива.

/**
 * Выводит все ключевые слова в лог.
 * @param {string[]} keywords Массив ключевых слов.
 * @return {void}
 */
function logKeywords(keywords: string[]): void {
  keywords.forEach(function(keyword, index) {
    Logger.log(`Ключевое слово ${index + 1}: ${keyword}`);
  });
}

Поиск в массиве: indexOf(), includes(), find(), findIndex()

• indexOf() – возвращает индекс первого вхождения элемента в массиве.
• includes() – проверяет, содержит ли массив указанный элемент.
• find() – возвращает первый элемент массива, удовлетворяющий условию.
• findIndex() – возвращает индекс первого элемента массива, удовлетворяющего условию.

/**
 * Проверяет, содержит ли массив ключевое слово.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {string} keyword Искомое ключевое слово.
 * @return {boolean}
 */
function hasKeyword(keywords: string[], keyword: string): boolean {
  return keywords.includes(keyword);
}

Преобразование массива: map(), filter(), reduce()

• map() – создает новый массив, применяя функцию к каждому элементу исходного массива.
• filter() – создает новый массив, содержащий только элементы, удовлетворяющие условию.
• reduce() – применяет функцию к аккумулятору и каждому элементу массива (слева направо), сводя его к одному значению.

/**
 * Преобразует массив ключевых слов в массив в верхнем регистре.
 * @param {string[]} keywords Массив ключевых слов.
 * @return {string[]}
 */
function uppercaseKeywords(keywords: string[]): string[] {
  return keywords.map(keyword => keyword.toUpperCase());
}

Сортировка массива: sort()

sort() – сортирует элементы массива.

/**
 * Сортирует массив ключевых слов в алфавитном порядке.
 * @param {string[]} keywords Массив ключевых слов.
 * @return {string[]}
 */
function sortKeywords(keywords: string[]): string[] {
  return keywords.sort();
}

Преобразование массива в строку: join()

join() – объединяет все элементы массива в строку, используя указанный разделитель.

/**
 * Преобразует массив ключевых слов в строку, разделенную запятыми.
 * @param {string[]} keywords Массив ключевых слов.
 * @param {string} separator Разделитель.
 * @return {string}
 */
function keywordsToString(keywords: string[], separator: string = ','): string {
  return keywords.join(separator);
}

Примеры использования массивов в Google Apps Script

Чтение данных из Google Sheets в массив

/**
 * Читает данные из Google Sheets в массив.
 * @param {string} spreadsheetId ID Google Sheets.
 * @param {string} sheetName Название листа.
 * @return {any[][]} Массив данных из Google Sheets.
 */
function readDataFromSheet(spreadsheetId: string, sheetName: string): any[][] {
  const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
  const sheet = spreadsheet.getSheetByName(sheetName);
  if (!sheet) {
    throw new Error(`Лист с именем "${sheetName}" не найден.`);
  }
  const dataRange = sheet.getDataRange();
  const data = dataRange.getValues();
  return data;
}

Запись данных из массива в Google Sheets

/**
 * Записывает данные из массива в Google Sheets.
 * @param {string} spreadsheetId ID Google Sheets.
 * @param {string} sheetName Название листа.
 * @param {any[][]} data Массив данных для записи.
 * @return {void}
 */
function writeDataToSheet(spreadsheetId: string, sheetName: string, data: any[][]): void {
  const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
  const sheet = spreadsheet.getSheetByName(sheetName);
  if (!sheet) {
    throw new Error(`Лист с именем "${sheetName}" не найден.`);
  }
  const numRows = data.length;
  const numCols = data[0].length;
  const range = sheet.getRange(1, 1, numRows, numCols);
  range.setValues(data);
}

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

Предположим, у вас есть массив данных о рекламных кампаниях с полями: кампания, показы, клики, CTR.

/**
 * Создает отчет по рекламным кампаниям.
 *
 * @param {Array<Array<any>>} campaignData - Двумерный массив данных о кампаниях.
 * @returns {object} - Объект с агрегированными данными.
 */
function generateCampaignReport(campaignData) {
  // Пропускаем строку заголовков, если она есть
  const dataRows = campaignData.slice(1);

  // Инициализируем переменные для агрегации
  let totalImpressions = 0;
  let totalClicks = 0;

  // Обрабатываем каждую строку с данными
  dataRows.forEach(row => {
    totalImpressions += row[1]; // Суммируем показы
    totalClicks += row[2]; // Суммируем клики
  });

  // Рассчитываем общий CTR
  const totalCTR = totalImpressions > 0 ? totalClicks / totalImpressions : 0;

  // Форматируем CTR в проценты
  const formattedCTR = (totalCTR * 100).toFixed(2) + '%';

  // Возвращаем объект с результатами
  return {
    totalImpressions: totalImpressions,
    totalClicks: totalClicks,
    totalCTR: formattedCTR
  };
}