Как создать окно сообщений в Google Sheets с помощью Apps Script?

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

Что такое окно сообщений и зачем оно нужно?

Окно сообщений (или диалоговое окно) — это всплывающее окно, которое прерывает основной поток выполнения скрипта для взаимодействия с пользователем. Оно может использоваться для:

Информирования: Отображение уведомлений, результатов выполнения операций.

Подтверждения: Запрос подтверждения перед выполнением критически важных действий (например, удаление данных).

Предупреждения: Указание на потенциальные проблемы или ошибки.

Сбора данных: Получение простого ввода от пользователя.

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

Основные понятия Apps Script для работы с интерфейсом Google Sheets

Для создания окон сообщений в Google Sheets используется сервис Ui (User Interface). Он предоставляет доступ к элементам интерфейса редактора Google Workspace (Sheets, Docs, Forms).

Основным классом является SpreadsheetApp.getUi(), который возвращает экземпляр Ui, позволяющий вызывать методы для отображения диалоговых окон (alert, prompt, showSidebar, showModalDialog и т.д.).

Необходимые разрешения для использования UI Service

Скрипты, использующие Ui сервис для взаимодействия с интерфейсом Google Sheets, требуют авторизации пользователя. При первом запуске скрипта Google запросит разрешение на:

Просмотр и управление текущими таблицами.

Отображение и запуск сторонних веб-приложений, когда вы используете этот скрипт.

Без предоставления этих разрешений скрипт не сможет отображать окна сообщений.

Создание простого окна сообщений с кнопкой ‘OK’

Самый простой способ уведомить пользователя — использовать метод ui.alert().

Написание кода Apps Script для отображения окна сообщений

/**
 * Отображает простое информационное окно с сообщением и кнопкой OK.
 */
function showBasicAlert(): void {
  // Получаем доступ к интерфейсу пользователя текущей таблицы
  const ui: GoogleAppsScript.Base.Ui = SpreadsheetApp.getUi();

  // Отображаем окно сообщения
  const result: GoogleAppsScript.Base.Button = ui.alert(
     'Статус операции',
     'Обработка данных рекламной кампании успешно завершена.',
     ui.ButtonSet.OK
  );

  // Можно добавить логику проверки нажатой кнопки, хотя здесь только OK
  if (result === ui.Button.OK) {
    Logger.log('Пользователь нажал OK.');
  }
}

Объяснение основных функций и параметров (ui.alert())

Метод ui.alert() принимает до трех аргументов:

title (String): Текст заголовка окна.

prompt (String): Основной текст сообщения.

buttons (Ui.ButtonSet): Набор кнопок для отображения. По умолчанию используется ui.ButtonSet.OK.

Метод возвращает значение типа Ui.Button, указывающее, какую кнопку нажал пользователь (OK, CANCEL, YES, NO).

Запуск скрипта и тестирование окна сообщений

Откройте Google Sheets.

Перейдите в Расширения > Apps Script.

Вставьте приведенный выше код в редактор.

Сохраните скрипт (присвойте ему имя, например, MessageBoxes).

Выберите функцию showBasicAlert в выпадающем списке над редактором.

Нажмите кнопку Выполнить (иконка ▶️).

При первом запуске предоставьте необходимые разрешения.

Вернитесь в Google Sheets. Вы должны увидеть окно сообщения с заголовком ‘Статус операции’ и текстом ‘Обработка данных рекламной кампании успешно завершена.’

Настройка окна сообщений с несколькими кнопками и иконками

Для более сложных сценариев можно использовать различные наборы кнопок и получать ответ пользователя.

Использование enum-ов Ui.ButtonSet и Ui.Button для добавления кнопок

Apps Script предоставляет перечисления (enum) Ui.ButtonSet для стандартных комбинаций кнопок и Ui.Button для представления отдельных кнопок.

Ui.ButtonSet.OK: Кнопка ‘OK’.

Ui.ButtonSet.OK_CANCEL: Кнопки ‘OK’ и ‘Отмена’.

Ui.ButtonSet.YES_NO: Кнопки ‘Да’ и ‘Нет’.

Ui.ButtonSet.YES_NO_CANCEL: Кнопки ‘Да’, ‘Нет’ и ‘Отмена’.

Возвращаемые значения сравниваются с Ui.Button.OK, Ui.Button.CANCEL, Ui.Button.YES, Ui.Button.NO, Ui.Button.CLOSE.

Примеры различных наборов кнопок (YES_NO, OK_CANCEL и т.д.)

/**
 * Запрашивает подтверждение у пользователя перед выполнением действия.
 * Использует кнопки YES/NO.
 */
function confirmActionWithYesNo(): void {
  const ui: GoogleAppsScript.Base.Ui = SpreadsheetApp.getUi();

  const question: string = 'Вы уверены, что хотите обновить ставки для кампаний с CTR < 1%? Это действие необратимо.';
  const title: string = 'Подтверждение обновления ставок';

  const response: GoogleAppsScript.Base.Button = ui.alert(title, question, ui.ButtonSet.YES_NO);

  // Обработка ответа пользователя
  if (response === ui.Button.YES) {
    Logger.log('Пользователь подтвердил действие. Запускаем обновление ставок...');
    // Здесь должен быть вызов функции обновления ставок
    // updateCampaignBids();
  } else if (response === ui.Button.NO) {
    Logger.log('Пользователь отменил действие.');
  } else {
    // Обработка закрытия окна без выбора
    Logger.log('Окно было закрыто.');
  }
}

Реагирование на нажатие кнопок пользователем (условные операторы)

Как показано в примере выше, результат вызова ui.alert() сохраняется в переменную (например, response). Затем с помощью условных операторов (if, else if, else или switch) можно проверить, какая кнопка была нажата, и выполнить соответствующие действия.

Продвинутые возможности: Ввод данных пользователем через окно сообщений

Стандартные методы ui.alert() и ui.prompt() (для ввода одной строки текста) ограничены. Для создания более сложных форм ввода используется HtmlService.

Использование HtmlService для создания пользовательских диалоговых окон

HtmlService позволяет создавать веб-интерфейсы с использованием стандартных HTML, CSS и JavaScript. Эти интерфейсы могут быть отображены как боковые панели (showSidebar) или модальные диалоговые окна (showModalDialog). Модальные окна, как и alert, останавливают выполнение серверного скрипта до их закрытия.

Создание HTML-формы для ввода данных (текстовые поля, выпадающие списки и т.д.)

Сначала создается HTML-файл в проекте Apps Script (Файл > Создать > HTML-файл). Назовем его CampaignInputDialog.html.

  
    
    
    
      body { font-family: sans-serif; margin: 20px; }
      label { display: block; margin-top: 10px; }
      input[type="text"], input[type="number"] { width: 95%; padding: 8px; margin-top: 5px; border: 1px solid #ccc; border-radius: 4px; }
      button { padding: 10px 15px; margin-top: 20px; cursor: pointer; border: none; border-radius: 4px; }
      #submitBtn { background-color: #4CAF50; color: white; }
      #cancelBtn { background-color: #f44336; color: white; margin-left: 10px; }
    
  
  
    
Параметры новой рекламной кампании
    
      

        Название кампании:
        
      
      

        Дневной бюджет ($):
        
      
      

        Целевая цена за конверсию ($):
        
      
      Создать
      Отмена
    

    
      /**
       * Собирает данные формы и передает их серверной функции Apps Script.
       */
      function submitForm(): void {
        const formElement: HTMLFormElement = document.getElementById('campaignForm') as HTMLFormElement;
        const formData = {
          campaignName: (document.getElementById('campaignName') as HTMLInputElement).value,
          budget: parseFloat((document.getElementById('budget') as HTMLInputElement).value),
          targetCPA: parseFloat((document.getElementById('targetCPA') as HTMLInputElement).value) || null // Handle empty optional field
        };
        
        // Вызов серверной функции и передача данных
        google.script.run
          .withSuccessHandler(closeDialog)
          .withFailureHandler(showError)
          .processCampaignFormData(formData);
      }

      /**
       * Закрывает диалоговое окно после успешной отправки.
       */
      function closeDialog(): void {
        google.script.host.close();
      }

      /**
       * Показывает сообщение об ошибке (можно улучшить).
       * @param {Error} error - Объект ошибки.
       */
      function showError(error: Error): void {
        alert('Ошибка: ' + error.message);
      }
    
  

Передача данных из HTML-формы в Apps Script

В HTML-коде используется google.script.run — это асинхронный клиент-серверный API JavaScript, который позволяет HTML-странице вызывать функции Apps Script на стороне сервера.

google.script.run: Объект для вызова серверных функций.

.withSuccessHandler(callbackFunction): Указывает функцию JavaScript, которая будет вызвана при успешном выполнении серверной функции.

.withFailureHandler(callbackFunction): Указывает функцию JavaScript, которая будет вызвана при ошибке выполнения серверной функции.

.serverFunctionName(arguments): Имя серверной функции Apps Script для вызова и передаваемые ей аргументы (в нашем случае объект formData).

Обработка и сохранение введенных данных в Google Sheets

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

/**
 * Отображает модальное окно для ввода данных о новой кампании.
 */
function showCampaignInputDialog(): void {
  // Создаем HTML-вывод из файла CampaignInputDialog.html
  const htmlOutput: GoogleAppsScript.HTML.HtmlOutput = HtmlService.createHtmlOutputFromFile('CampaignInputDialog')
      .setWidth(400) // Задаем ширину окна
      .setHeight(350); // Задаем высоту окна

  // Получаем UI и отображаем модальное окно
  const ui: GoogleAppsScript.Base.Ui = SpreadsheetApp.getUi();
  ui.showModalDialog(htmlOutput, 'Создать новую кампанию');
}

/**
 * Обрабатывает данные, полученные из HTML-формы.
 * @param {object} formData - Объект с данными формы (campaignName, budget, targetCPA).
 */
function processCampaignFormData(formData: { campaignName: string; budget: number; targetCPA: number | null }): void {
  try {
    // Проверяем полученные данные (простая валидация)
    if (!formData || !formData.campaignName || formData.budget <= 0) {
      throw new Error('Некорректные данные: Название кампании и бюджет обязательны.');
    }

    Logger.log('Полученные данные: ' + JSON.stringify(formData));

    // Получаем активный лист или лист по имени
    const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Campaigns'); // Убедитесь, что лист 'Campaigns' существует
    if (!sheet) {
       throw new Error('Лист "Campaigns" не найден.');
    }
    
    // Добавляем данные в новую строку на листе
    sheet.appendRow([formData.campaignName, formData.budget, formData.targetCPA, new Date(), 'Active']); // Пример столбцов: Name, Budget, Target CPA, Creation Date, Status

    // Дополнительное уведомление об успехе (не обязательно, т.к. диалог закроется)
    SpreadsheetApp.getUi().alert('Кампания "' + formData.campaignName + '" успешно добавлена!');

  } catch (error) {
    Logger.log('Ошибка обработки данных формы: ' + error);
    // Важно передать ошибку обратно в HTML, чтобы пользователь ее увидел
    // В данном примере ошибка будет обработана .withFailureHandler в HTML
    throw error; // Передаем ошибку дальше
  }
}

Чтобы запустить этот пример, выберите функцию showCampaignInputDialog и нажмите Выполнить.

Практические примеры использования окон сообщений

Окна сообщений — универсальный инструмент для улучшения взаимодействия пользователя со скриптами.

Подтверждение удаления данных

Перед удалением строк или листов, особенно на основе сложных условий (например, удаление всех рекламных кампаний с нулевым бюджетом), запросите подтверждение с помощью ui.alert(..., ui.ButtonSet.YES_NO).

Отображение предупреждений и ошибок

Если скрипт обнаруживает потенциальную проблему (например, достижение лимита API Google Ads, некорректные данные в ячейке, используемой для расчетов), используйте ui.alert() для информирования пользователя.

Запрос подтверждения перед выполнением длительной операции

Операции, которые могут занять много времени (обработка больших объемов данных, множественные вызовы внешних API), должны предваряться запросом подтверждения. Это позволяет пользователю отменить операцию, если она была запущена случайно.

Создание простого интерфейса для настройки параметров скрипта

С помощью HtmlService можно создать диалоговое окно для ввода настроек скрипта (например, выбор диапазона дат для отчета, установка пороговых значений для анализа данных, ввод API-ключей) без необходимости редактировать сам код.