Что такое UI-запрос и зачем он нужен?
UI-запрос (User Interface prompt) в Google Apps Script – это способ интерактивного взаимодействия со пользователем. Он позволяет скрипту запрашивать у пользователя информацию или подтверждение, отображая диалоговое окно с текстом, кнопками и полями ввода. UI-запросы необходимы, когда скрипту требуется ввод данных от пользователя во время выполнения, например, для уточнения параметров операции, подтверждения действия или выбора опции.
В отличие от веб-приложений, где интерфейс создается с использованием HTML, CSS и JavaScript, в Google Apps Script UI-запросы предоставляют простой и быстрый способ добавить интерактивность без необходимости развертывания полноценного веб-приложения. Это особенно полезно для скриптов, автоматизирующих задачи в Google Sheets, Docs, Forms и других сервисах Google Workspace.
Среда выполнения Google Apps Script и UI
Google Apps Script работает в среде выполнения (runtime) Google Workspace. При работе с UI, важно понимать контекст выполнения скрипта. UI-запросы инициируются через объект Ui, который доступен через сервисы, такие как SpreadsheetApp, DocumentApp, FormApp и другие. Например, SpreadsheetApp.getUi() предоставляет доступ к UI-сервису, связанному с текущей электронной таблицей.
Ограничения и возможности UI-запросов
UI-запросы в Google Apps Script имеют свои ограничения. Они не предназначены для создания сложных пользовательских интерфейсов. Они ограничены простыми диалоговыми окнами с кнопками и текстовыми полями. Однако, для большинства задач автоматизации, требующих интерактивного взаимодействия с пользователем, UI-запросы вполне достаточны.
Ограничения:
Ограниченный набор элементов управления (кнопки, текстовые поля, оповещения).
Отсутствие гибкой настройки внешнего вида.
Блокирующий характер выполнения скрипта во время отображения запроса.
Возможности:
Простота и скорость создания.
Интеграция с сервисами Google Workspace.
Возможность получения ввода данных от пользователя.
Создание простого UI-запроса
Использование класса `Ui` для отображения запроса
Для отображения UI-запроса используется класс Ui, полученный через SpreadsheetApp.getUi(), DocumentApp.getUi() и другие аналогичные методы. Метод alert(), prompt() и showModelessDialog() этого класса позволяют создавать различные типы диалоговых окон.
Основные параметры запроса: заголовок, текст, кнопки
Основные параметры UI-запроса включают:
Заголовок: Текст, отображаемый в заголовке диалогового окна.
Текст: Основное сообщение, отображаемое пользователю.
Кнопки: Набор кнопок, предлагаемых пользователю для выбора (например, ‘ОК’, ‘Отмена’, ‘Да’, ‘Нет’).
Обработка ответа пользователя: `ButtonSet` и `Button`
Ответ пользователя представлен объектом Button, который возвращается после нажатия кнопки. Класс ButtonSet определяет предопределенные наборы кнопок, такие как ButtonSet.OK_CANCEL, ButtonSet.YES_NO, ButtonSet.CLOSE. Анализируя возвращенный объект Button, можно определить, какую кнопку нажал пользователь.
Пример кода: простой запрос с кнопками ‘ОК’ и ‘Отмена’
/**
* Отображает UI-запрос с кнопками 'ОК' и 'Отмена'.
*/
function showOkCancelPrompt() {
// Получаем объект Ui.
const ui: GoogleAppsScript.Script.Ui = SpreadsheetApp.getUi();
// Отображаем запрос с заголовком, текстом и кнопками 'ОК' и 'Отмена'.
const response: GoogleAppsScript.Script.ModalDialogResponse = ui.alert(
'Подтверждение', // Заголовок
'Вы уверены, что хотите продолжить?', // Текст
ui.ButtonSet.OK_CANCEL // Набор кнопок
);
// Обрабатываем ответ пользователя.
if (response == ui.Button.OK) {
// Пользователь нажал 'ОК'.
Logger.log('Пользователь подтвердил действие.');
} else {
// Пользователь нажал 'Отмена' или закрыл окно.
Logger.log('Действие отменено пользователем.');
}
}Работа с различными типами UI-запросов
Запросы с текстовым полем ввода (`prompt()` method)
Метод prompt() класса Ui позволяет отображать диалоговое окно с текстовым полем для ввода данных. Это полезно, когда скрипту требуется получить от пользователя произвольный текст, число или другую информацию.
Настройка текстового поля: валидация, значение по умолчанию
К сожалению, UI-запросы в Google Apps Script не предоставляют встроенных средств валидации ввода. Валидацию введенных данных необходимо реализовать вручную, проверяя значение, возвращенное методом prompt(). Значение по умолчанию для текстового поля задать нельзя.
Обработка введенного текста: получение значения и проверка
Результат работы prompt() возвращает объект PromptResponse, из которого можно получить введенный пользователем текст с помощью метода getResponseText(). Необходимо проверить полученный текст на соответствие ожидаемому формату и диапазону значений.
/**
* Отображает UI-запрос с текстовым полем для ввода имени пользователя.
*/
function getUserName() {
// Получаем объект Ui.
const ui: GoogleAppsScript.Script.Ui = SpreadsheetApp.getUi();
// Отображаем запрос с заголовком и текстом.
const result: GoogleAppsScript.Script.PromptResponse = ui.prompt(
'Имя пользователя', // Заголовок
'Пожалуйста, введите ваше имя:', // Текст
ui.ButtonSet.OK_CANCEL // Набор кнопок
);
// Обрабатываем ответ пользователя.
const button: GoogleAppsScript.Script.Button = result.getSelectedButton();
const text: string = result.getResponseText();
if (button == ui.Button.OK) {
// Пользователь нажал 'ОК'.
if (text) {
// Проверяем, что имя пользователя было введено.
Logger.log('Имя пользователя: ' + text);
} else {
Logger.log('Имя пользователя не было введено.');
}
} else {
// Пользователь нажал 'Отмена' или закрыл окно.
Logger.log('Ввод имени пользователя отменен.');
}
}Использование `SpreadsheetApp.getUi().alert()` для простых уведомлений
Метод alert() можно использовать не только для запросов с кнопками, но и для отображения простых уведомлений пользователю. Можно отобразить сообщение с одной кнопкой ‘ОК’ (по умолчанию) или без кнопок вообще.
Продвинутые техники и примеры UI-запросов
Асинхронные UI-запросы и обработка результатов
UI-запросы в Google Apps Script являются синхронными, то есть выполнение скрипта блокируется до тех пор, пока пользователь не ответит на запрос. Асинхронные UI запросы напрямую не поддерживаются. Но можно создать веб-приложение и вызывать его из скрипта, чтобы получить асинхронное поведение.
UI-запросы в Google Sheets и Google Docs
UI-запросы можно использовать в скриптах, работающих с Google Sheets и Google Docs, вызывая SpreadsheetApp.getUi() и DocumentApp.getUi() соответственно. Функциональность UI-запросов в этих сервисах идентична.
Обработка ошибок и исключений в UI-запросах
При работе с UI-запросами важно обрабатывать возможные ошибки и исключения. Например, пользователь может закрыть диалоговое окно, не выбрав ни одну из кнопок. В этом случае, метод getSelectedButton() вернет null. Необходимо предусмотреть обработку таких ситуаций.
Локализация UI-запросов (поддержка разных языков)
UI-запросы в Google Apps Script не поддерживают автоматическую локализацию. Для поддержки разных языков необходимо реализовать логику выбора текста запроса и заголовка в зависимости от языка пользователя. Можно использовать таблицу соответствий "язык — текст" и функцию, выбирающую текст на нужном языке.
Лучшие практики и советы по созданию UI-запросов
Дизайн UI-запросов: удобство и понятность для пользователя
Используйте понятные и лаконичные заголовки и текст запросов.
Предлагайте пользователю только необходимые варианты выбора.
Располагайте кнопки в логичном порядке (например, ‘ОК’ слева, ‘Отмена’ справа).
Избегайте использования сложных терминов и жаргона.
Избегание злоупотребления UI-запросами: альтернативные подходы
Частое использование UI-запросов может раздражать пользователей. Рассмотрите альтернативные подходы, такие как:
Использование параметров скрипта (Script properties).
Хранение настроек в электронной таблице.
Создание пользовательских диалоговых окон с использованием HTML-сервиса (для более сложных интерфейсов).
Тестирование UI-запросов
Перед развертыванием скрипта протестируйте UI-запросы, чтобы убедиться, что они работают корректно и отображаются правильно. Проверьте обработку различных вариантов ответов пользователя и обработку ошибок.