Что такое диалоговое окно ввода и зачем оно нужно?
Диалоговое окно ввода в Google Apps Script — это модальное окно, которое отображается поверх интерфейса Google Workspace (Sheets, Docs, Forms, etc.) и запрашивает у пользователя ввод данных. Оно служит для интерактивного взаимодействия скрипта с пользователем, позволяя получать необходимую информацию для дальнейшей обработки без необходимости редактирования самого кода или ячеек таблицы.
Основное назначение — сбор пользовательских параметров, подтверждений или данных непосредственно в момент выполнения скрипта. Это делает автоматизацию более гибкой и управляемой.
Когда стоит использовать диалоговые окна ввода?
Диалоговые окна ввода целесообразно применять в следующих ситуациях:
Запрос параметров: Когда скрипту требуются динамические параметры для выполнения, например, имя новой рекламной кампании, диапазон дат для отчета, адрес электронной почты для отправки уведомления.
Подтверждение действий: Перед выполнением потенциально необратимых операций, таких как удаление данных, массовая рассылка, изменение структуры документа.
Простая форма ввода: Для сбора небольшого объема структурированных данных, не требующих сложной логики или интерфейса (альтернатива созданию полноценной боковой панели или веб-приложения через HTMLService).
Быстрая отладка: Иногда удобно использовать prompt для ввода тестовых значений или переменных во время разработки.
Ограничения и возможности диалоговых окон в Google Apps Script
Стандартные диалоговые окна, создаваемые методом Ui.prompt(), обладают рядом ограничений:
Одно поле ввода: Позволяют ввести только одно строковое значение.
Ограниченная кастомизация: Нельзя изменить дизайн, добавить изображения или сложные элементы управления (флажки, выпадающие списки).
Блокировка интерфейса: Являются модальными, блокируя взаимодействие с основным документом до закрытия окна.
Однако они предоставляют базовые возможности:
Задание заголовка и текста.
Выбор набора стандартных кнопок (OK, Отмена, Закрыть).
Получение введенного текста и информации о нажатой кнопке.
Для более сложных сценариев, требующих нескольких полей ввода, валидации или кастомного интерфейса, необходимо использовать HTMLService.
Создание простого диалогового окна ввода
Использование класса `Ui` для создания интерфейса
Для взаимодействия с пользовательским интерфейсом Google Workspace в серверных скриптах используется класс Ui. Получить экземпляр Ui можно через активный документ, таблицу или форму:
/**
* Получает объект Ui для текущего приложения.
* @returns {GoogleAppsScript.Base.Ui} Объект Ui.
*/
function getUiEnvironment(): GoogleAppsScript.Base.Ui {
// Для Google Sheets
// return SpreadsheetApp.getUi();
// Для Google Docs
// return DocumentApp.getUi();
// Для Google Forms
return FormApp.getUi(); // Пример для Forms
}Метод `prompt()`: отображение окна и получение ввода
Основным методом для создания простого окна ввода является Ui.prompt(). Он принимает несколько аргументов:
title: Заголовок окна (строка).
prompt: Текст приглашения к вводу (строка).
buttons: Набор кнопок (enum Ui.ButtonSet).
Метод возвращает объект PromptResponse, содержащий введенный текст и информацию о нажатой кнопке.
Обработка различных ответов пользователя (OK, Отмена, Закрыть)
Объект PromptResponse имеет два ключевых метода:
getResponseText(): Возвращает введенный пользователем текст (string) или пустую строку, если ввод не был сделан.
getSelectedButton(): Возвращает нажатую кнопку (enum Ui.Button). Возможные значения: OK, CANCEL, CLOSE.
Необходимо проверять, какая кнопка была нажата, прежде чем использовать введенные данные.
Пример кода простого диалогового окна
/**
* Запрашивает у пользователя название новой рекламной кампании.
*/
function requestCampaignName(): void {
const ui: GoogleAppsScript.Base.Ui = SpreadsheetApp.getUi(); // Пример для Google Sheets
const title: string = 'Новая кампания';
const promptText: string = 'Введите название новой рекламной кампании:';
// Отображаем диалоговое окно с кнопками OK и Отмена
const response: GoogleAppsScript.Base.PromptResponse = ui.prompt(title, promptText, ui.ButtonSet.OK_CANCEL);
// Проверяем, какая кнопка была нажата
const selectedButton: GoogleAppsScript.Base.Button = response.getSelectedButton();
const inputText: string = response.getResponseText();
if (selectedButton === ui.Button.OK) {
if (inputText && inputText.trim() !== '') {
Logger.log(`Название кампании принято: ${inputText.trim()}`);
// Здесь может быть код для создания кампании в Google Ads API или записи в таблицу
SpreadsheetApp.getActiveSpreadsheet().toast(`Кампания '${inputText.trim()}' будет создана.`);
} else {
ui.alert('Название кампании не может быть пустым.');
}
} else if (selectedButton === ui.Button.CANCEL) {
Logger.log('Пользователь отменил ввод названия кампании.');
SpreadsheetApp.getActiveSpreadsheet().toast('Создание кампании отменено.');
} else if (selectedButton === ui.Button.CLOSE) {
Logger.log('Диалоговое окно было закрыто.');
}
}Настройка и расширение функциональности диалогового окна
Изменение заголовка и текста приглашения
Как показано в примере выше, заголовок (title) и текст приглашения (prompt) легко настраиваются передачей соответствующих строк в метод ui.prompt().
Добавление кнопок действий (custom buttons)
Стандартный метод prompt() не поддерживает добавление произвольных кнопок. Он ограничен наборами Ui.ButtonSet (OK, OK_CANCEL, YES_NO, YES_NO_CANCEL). Для создания окон с кастомными кнопками необходимо использовать HTMLService для построения собственного HTML-интерфейса.
Валидация введенных данных (проверка на пустые значения, формат)
Базовую валидацию (например, проверку на пустое значение) можно выполнить после получения ответа, как в примере с requestCampaignName. Для более сложной валидации (формат email, числовой диапазон, регулярные выражения) лучше использовать HTMLService, где можно применить JavaScript на стороне клиента для немедленной обратной связи.
Пример простой серверной валидации email:
/**
* Проверяет, является ли строка валидным email адресом (упрощенная проверка).
* @param {string} email Строка для проверки.
* @returns {boolean} True, если строка похожа на email, иначе false.
*/
function isValidEmail(email: string): boolean {
if (!email) {
return false;
}
// Простое регулярное выражение для базовой проверки формата email
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
}
/**
* Запрашивает email у пользователя и валидирует его.
*/
function requestUserEmail(): void {
const ui: GoogleAppsScript.Base.Ui = SpreadsheetApp.getUi();
const response: GoogleAppsScript.Base.PromptResponse = ui.prompt('Email для отчета', 'Введите ваш email:', ui.ButtonSet.OK_CANCEL);
if (response.getSelectedButton() === ui.Button.OK) {
const email: string = response.getResponseText();
if (isValidEmail(email)) {
Logger.log(`Email принят: ${email}`);
// Дальнейшие действия, например, отправка отчета
} else {
ui.alert('Введен некорректный формат email. Пожалуйста, попробуйте снова.');
}
} else {
Logger.log('Ввод email отменен или окно закрыто.');
}
}Более сложные примеры и продвинутые техники
Создание диалоговых окон с несколькими полями ввода (использование HTMLService)
Для создания форм с несколькими полями, флажками, выпадающими списками и кастомной валидацией необходимо использовать HTMLService. Это позволяет создать полноценный HTML-интерфейс и взаимодействовать с ним через JavaScript на стороне клиента и серверные функции Apps Script.
// === Код Code.gs ===
/**
* Отображает диалоговое окно с несколькими полями с использованием HTMLService.
*/
function showMultiInputDialog(): void {
const htmlOutput = HtmlService.createHtmlOutputFromFile('MultiInputDialog')
.setWidth(300)
.setHeight(250);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'Параметры отчета');
}
/**
* Серверная функция для обработки данных, полученных из HTML-формы.
* @param {object} formObject Объект с данными формы.
*/
function processFormData(formObject: { startDate: string, endDate: string, reportType: string }): void {
Logger.log(`Получены данные: Начало=${formObject.startDate}, Конец=${formObject.endDate}, Тип=${formObject.reportType}`);
// Здесь код для обработки данных, например, генерация отчета
SpreadsheetApp.getActiveSpreadsheet().toast('Параметры отчета приняты.');
}
// === Код MultiInputDialog.html ===
Ежедневный
Еженедельный
Ежемесячный
document.getElementById('reportForm').addEventListener('submit', function(e) {
e.preventDefault(); // Предотвращаем стандартную отправку формы
// Собираем данные формы
const formData = {
startDate: document.getElementById('startDate').value,
endDate: document.getElementById('endDate').value,
reportType: document.getElementById('reportType').value
};
// Вызываем серверную функцию Apps Script для обработки данных
google.script.run
.withSuccessHandler(function() {
// Закрываем диалог после успешной обработки
google.script.host.close();
})
.withFailureHandler(function(error) {
// Показываем сообщение об ошибке (можно сделать его более информативным)
alert('Ошибка: ' + error.message);
})
.processFormData(formData);
});
Взаимодействие диалогового окна с Google Sheets/Docs/Forms
Диалоговые окна, особенно созданные с помощью HTMLService, могут активно взаимодействовать с открытым документом:
Чтение данных: Получение значений из ячеек/текста документа для предзаполнения полей формы.
Запись данных: Вставка данных, введенных пользователем, в определенные ячейки таблицы или места в документе.
Изменение структуры: Создание новых листов, добавление вопросов в форму на основе пользовательского ввода.
Для этого используются соответствующие службы (SpreadsheetApp, DocumentApp, FormApp) внутри серверных функций Apps Script, вызываемых из диалогового окна.
Использование диалоговых окон для создания пользовательских форм
Комбинация HTMLService и Ui.showModalDialog() или Ui.showSidebar() позволяет создавать сложные пользовательские формы для сбора данных, настройки скриптов или выполнения специфических задач в интерфейсе Google Workspace. Это мощный инструмент для расширения стандартной функциональности приложений.
Рекомендации и лучшие практики
Советы по дизайну диалоговых окон для улучшения пользовательского опыта
Ясность: Заголовок и текст приглашения должны четко объяснять, какая информация требуется от пользователя.
Краткость: Избегайте длинных текстов. Используйте понятные метки для полей ввода.
Значения по умолчанию: Если возможно, предоставляйте осмысленные значения по умолчанию.
Обратная связь: Информируйте пользователя о результате операции (успех, ошибка) с помощью ui.alert() или SpreadsheetApp.toast().
Консистентность: Старайтесь придерживаться единого стиля для диалоговых окон в рамках одного скрипта или проекта.
Не злоупотребляйте: Используйте модальные окна только тогда, когда необходимо получить ввод перед продолжением выполнения скрипта. Для длительных взаимодействий лучше подходят боковые панели (showSidebar).
Обработка ошибок и предотвращение сбоев
Проверка кнопок: Всегда проверяйте, какая кнопка была нажата (getSelectedButton()), прежде чем обрабатывать ввод.
Валидация ввода: Реализуйте как клиентскую (в HTMLService), так и серверную валидацию данных.
Обработка исключений: Используйте блоки try...catch в серверных функциях, вызываемых из диалоговых окон, для перехвата и корректной обработки ошибок.
Информативные сообщения об ошибках: Вместо стандартных сообщений показывайте пользователю понятные уведомления о том, что пошло не так и как это исправить.
Оптимизация кода для повышения производительности
Минимизация вызовов API: В функциях, вызываемых из диалоговых окон (google.script.run), старайтесь минимизировать количество обращений к сервисам Google (Sheets, Docs и т.д.). По возможности, получайте или записывайте данные одним батчем.
Асинхронность: google.script.run работает асинхронно. Используйте withSuccessHandler и withFailureHandler для обработки результатов без блокировки интерфейса диалогового окна.
Кеширование: Для часто запрашиваемых, но редко изменяющихся данных используйте CacheService для ускорения ответа сервера.