Что такое Google Apps Script и его возможности
Google Apps Script (GAS) — это облачная платформа для разработки скриптов на основе JavaScript, позволяющая автоматизировать задачи и расширять функциональность приложений Google Workspace (Sheets, Docs, Forms, Gmail и др.). GAS предоставляет доступ к обширным API для взаимодействия с этими сервисами, создания пользовательских интерфейсов и интеграции со сторонними ресурсами.
Платформа идеально подходит для автоматизации рутинных операций, таких как обработка данных в таблицах, генерация отчетов, отправка персонализированных email-рассылок, создание кастомных меню и диалоговых окон, а также интеграция данных между различными сервисами Google и внешними API.
Основы работы со строками в Google Apps Script
Работа со строками — фундаментальная часть любого скрипта в GAS. Поскольку GAS основан на JavaScript, он наследует все стандартные методы и свойства для манипуляции строками: конкатенация (+), получение длины (.length), поиск подстрок (.indexOf(), .includes()), извлечение частей (.substring(), .slice()), замена (.replace()), изменение регистра (.toUpperCase(), .toLowerCase()) и другие.
Понимание этих методов необходимо для эффективной обработки текстовых данных, будь то парсинг данных из ячеек таблиц, формирование динамического контента для email или документов, или обработка пользовательского ввода.
Задача: Вставка новой строки в текст — актуальность и применение
Вставка символа новой строки (\n) является частой задачей при работе с текстом в GAS. Это необходимо для форматирования вывода, разделения данных, создания структурированных отчетов или сообщений. Например, при формировании тела email-сообщения, описания в ячейке Google Sheets, или при генерации содержимого для Google Docs, правильное использование переносов строк делает информацию более читаемой и организованной.
Рассмотрим сценарий из интернет-маркетинга: формирование текста объявления для контекстной рекламы, где каждая строка (заголовок 1, заголовок 2, описание) должна быть четко разделена, или создание многострочного отчета по эффективности кампаний для отправки клиенту.
Основные способы вставки новой строки в Google Apps Script
Существует несколько стандартных способов добавить перенос строки в текстовые данные в Google Apps Script.
Использование ‘\n’ (символ новой строки)
Самый распространенный и универсальный способ — использование управляющей последовательности \n. Этот символ интерпретируется большинством систем и приложений как команда для перехода на новую строку.
/**
* Демонстрирует использование '\n' для переноса строки.
*
* @returns {string} Текст с переносом строки.
*/
function useNewlineCharacter(): string {
/** @type {string} */
const line1: string = "Первая строка текста.";
/** @type {string} */
const line2: string = "Вторая строка текста.";
// Конкатенация строк с использованием '\n'
/** @type {string} */
const combinedText: string = line1 + "\n" + line2;
Logger.log(combinedText);
// Вывод в лог:
// Первая строка текста.
// Вторая строка текста.
return combinedText;
}Применение `\r\n` (возврат каретки и новая строка) для совместимости
В некоторых контекстах, особенно при работе с системами Windows или определенными протоколами (например, HTTP), может потребоваться использовать комбинацию \r\n (возврат каретки + новая строка). Это обеспечивает лучшую совместимость, хотя в большинстве случаев внутри Google Workspace достаточно \n.
/**
* Демонстрирует использование '\r\n' для переноса строки.
*
* @returns {string} Текст с переносом строки в формате CRLF.
*/
function useCRLF(): string {
/** @type {string} */
const line1: string = "Строка для Windows совместимости.";
/** @type {string} */
const line2: string = "Следующая строка после CRLF.";
// Использование '\r\n'
/** @type {string} */
const combinedText: string = line1 + "\r\n" + line2;
Logger.log(combinedText);
// Вывод в лог будет визуально таким же, как с '\n',
// но базовые символы будут отличаться.
return combinedText;
}Использование String.fromCharCode() для вставки символа новой строки
Альтернативный способ вставки символа новой строки — использование метода String.fromCharCode() с кодом символа ASCII для новой строки (LF — Line Feed), который равен 10.
/**
* Демонстрирует использование String.fromCharCode(10) для переноса строки.
*
* @returns {string} Текст с переносом строки, созданным через код символа.
*/
function useFromCharCode(): string {
/** @type {string} */
const line1: string = "Использование fromCharCode.";
/** @type {string} */
const line2: string = "Для вставки новой строки.";
/** @type {string} */
const newline: string = String.fromCharCode(10); // Эквивалент '\n'
/** @type {string} */
const combinedText: string = line1 + newline + line2;
Logger.log(combinedText);
// Вывод в лог:
// Использование fromCharCode.
// Для вставки новой строки.
return combinedText;
}Этот метод может быть полезен в ситуациях, когда прямая вставка \n затруднена или нежелательна (например, при работе с данными, где \n может иметь специальное значение).
Практические примеры вставки новой строки
Вставка новой строки в текстовые поля Google Sheets
При работе с Google Sheets часто требуется записать в ячейку многострочный текст. Символ \n корректно обрабатывается Таблицами для создания переноса строки внутри ячейки.
/**
* Записывает многострочный текст в указанную ячейку Google Sheets.
*
* @param {string} sheetName Имя листа.
* @param {string} cellNotation Обозначение ячейки (например, "A1").
* @param {string[]} lines Массив строк для записи.
*/
function setMultiLineTextInSheet(sheetName: string, cellNotation: string, lines: string[]): void {
/** @type {GoogleAppsScript.Spreadsheet.Spreadsheet} */
const ss = SpreadsheetApp.getActiveSpreadsheet();
/** @type {GoogleAppsScript.Spreadsheet.Sheet | null} */
const sheet = ss.getSheetByName(sheetName);
if (!sheet) {
Logger.log(`Лист с именем '${sheetName}' не найден.`);
return;
}
/** @type {string} */
const multiLineText: string = lines.join("\n");
/** @type {GoogleAppsScript.Spreadsheet.Range} */
const cell = sheet.getRange(cellNotation);
cell.setValue(multiLineText);
// Включим перенос по словам для наглядности
cell.setWrapStrategy(SpreadsheetApp.WrapStrategy.WRAP);
Logger.log(`Многострочный текст записан в ячейку ${cellNotation} листа ${sheetName}.`);
}
// Пример использования:
// setMultiLineTextInSheet("Лист1", "B2", [
// "Отчет по рекламной кампании XYZ",
// "Период: 01.01.2024 - 31.01.2024",
// "Показы: 10000",
// "Клики: 500",
// "CTR: 5.00%"
// ]);Добавление новой строки при формировании HTML-кода для отправки email
При отправке email с HTML-содержимым через MailApp или GmailApp, для переноса строк в визуальном представлении письма используется HTML-тег <br>. Символ \n в HTML-коде обычно игнорируется браузерами при рендеринге, но может быть полезен для форматирования самого исходного HTML-кода.
/**
* Отправляет email с HTML-содержимым, используя
для переносов.
*
* @param {string} recipient Адрес получателя.
* @param {string} subject Тема письма.
* @param {string[]} bodyLines Массив строк для тела письма.
*/
function sendHtmlEmailWithLineBreaks(recipient: string, subject: string, bodyLines: string[]): void {
// Формируем HTML-тело, объединяя строки через
/** @type {string} */
const htmlBody: string = bodyLines.join("
");
try {
MailApp.sendEmail({
to: recipient,
subject: subject,
htmlBody: htmlBody, // Используем htmlBody для HTML-форматирования
});
Logger.log(`HTML email успешно отправлен на ${recipient}.`);
} catch (e) {
Logger.log(`Ошибка при отправке email: ${e}`);
}
}
// Пример использования:
// sendHtmlEmailWithLineBreaks(
// "client@example.com",
// "Еженедельный отчет по SEO",
// [
// "Уважаемый клиент,",
// "Ваш еженедельный отчет по позициям сайта готов.",
// "Основные изменения:",
// "- Ключевое слово 1: +2 позиции",
// "- Ключевое слово 2: -1 позиция",
// "Подробности во вложении.",
// "С уважением, Ваше Агентство"
// ]
// );Вставка новой строки при работе с Google Docs
При добавлении текста в Google Docs с помощью DocumentApp, символ \n корректно интерпретируется как перенос строки (создание нового параграфа или разрыва строки внутри параграфа, в зависимости от метода).
/**
* Добавляет многострочный текст в конец активного Google Документа.
*
* @param {string[]} textLines Массив строк для добавления.
*/
function appendMultiLineTextToDoc(textLines: string[]): void {
/** @type {GoogleAppsScript.Document.Document} */
const doc = DocumentApp.getActiveDocument();
/** @type {GoogleAppsScript.Document.Body} */
const body = doc.getBody();
// Объединяем строки с помощью '\n'
/** @type {string} */
const textToAppend: string = textLines.join("\n");
// Метод appendParagraph добавит каждую строку как новый параграф,
// если используется '\n'. Можно также добавлять параграфы по одному.
body.appendParagraph(textToAppend);
Logger.log("Многострочный текст добавлен в документ.");
}
// Пример использования:
// appendMultiLineTextToDoc([
// "Лог анализа данных:",
// `Timestamp: ${new Date().toISOString()}`,
// "Источник данных: Google Analytics API",
// "Выводы: Обнаружен рост трафика на 15%."
// ]);Обработка пользовательского ввода и добавление разрывов строк
Если вы создаете веб-приложение или боковую панель с помощью HTML Service, и пользователь вводит текст в <textarea>, браузер передаст переносы строк как \r\n или \n. В Apps Script их можно сохранить или преобразовать.
/**
* Обрабатывает текст из textarea, сохраняя переносы строк.
* (Предполагается, что эта функция вызывается из серверной части
* после получения данных от клиента).
*
* @param {string} userInput Текст, введенный пользователем (например, из