Что такое окно ввода и зачем оно нужно?
Окно ввода в Google Apps Script — это диалоговое окно, которое позволяет запрашивать у пользователя текстовую информацию. Оно необходимо для создания интерактивных скриптов, требующих взаимодействия с пользователем, например, для получения параметров, настроек или подтверждений.
Основные сценарии использования окон ввода
Получение критериев поиска для отчетов по рекламным кампаниям.
Запрос имени файла для экспорта данных из Google Sheets.
Запрос подтверждения перед выполнением критической операции (например, удаление данных).
Сбор пользовательских настроек для скрипта.
Получение данных для динамического формирования отчетов или дашбордов.
Ограничения и особенности окон ввода в Google Apps Script
Простота интерфейса: Окна ввода, созданные с помощью Browser.inputBox(), достаточно просты и не поддерживают расширенные элементы управления (например, выпадающие списки или календари). Для более сложных интерфейсов следует использовать HTML Service.
Блокировка выполнения скрипта: Выполнение скрипта приостанавливается до тех пор, пока пользователь не введет данные и не нажмет «OK» или «Отмена». Это следует учитывать при разработке длительных процессов.
Клиентская сторона: Browser.inputBox() выполняется на стороне клиента, поэтому требует наличия активной сессии Google пользователя.
Создание простого окна ввода с использованием `Browser.inputBox()`
Синтаксис и параметры функции `Browser.inputBox()`
Функция Browser.inputBox() имеет следующий синтаксис:
Browser.inputBox(title, prompt, buttons)
title: Заголовок окна ввода (строка).
prompt: Сообщение, отображаемое в окне ввода (строка).
buttons: (Необязательный) Тип кнопок, отображаемых в окне. Может принимать значения Browser.Buttons.OK_CANCEL (по умолчанию) или Browser.Buttons.YES_NO.
Пример кода: создание и отображение базового окна ввода
/**
* Отображает базовое окно ввода и возвращает введенное значение.
* @return {string|null} Введенное пользователем значение или null, если нажата кнопка "Отмена".
*/
function showBasicInputBox(): string | null {
const userInput: string | null = Browser.inputBox('Введите значение', 'Пожалуйста, введите значение:');
return userInput;
}Обработка полученных данных: чтение и использование введенного значения
/**
* Получает данные из окна ввода и выводит их в лог.
*/
function processUserInput(): void {
const userInput: string | null = showBasicInputBox();
if (userInput) {
Logger.log('Введенное значение: ' + userInput);
// Здесь можно выполнять дальнейшую обработку введенных данных
} else {
Logger.log('Пользователь отменил ввод.');
}
}Обработка нажатия кнопок ‘OK’ и ‘Отмена’
Возвращаемое значение Browser.inputBox() зависит от действия пользователя:
Если пользователь нажимает «OK», функция возвращает введенную строку.
Если пользователь нажимает «Отмена», функция возвращает null.
Продвинутые возможности окон ввода
Настройка заголовка и подсказки окна ввода
Заголовок и подсказка важны для понятности окна ввода. Используйте информативные заголовки и четкие подсказки, чтобы пользователь понимал, что от него требуется.
const userInput: string | null = Browser.inputBox('Введите URL кампании', 'Пожалуйста, введите URL кампании для анализа:');Использование различных типов ввода (текст, число, дата и т.д.)
Browser.inputBox() возвращает всегда строку. Для работы с числами или датами необходимо преобразовывать введенное значение:
/**
* Запрашивает у пользователя число и возвращает его.
* @return {number|null} Введенное число или null, если ввод отменен или введен некорректный формат.
*/
function getNumberFromInput(): number | null {
const userInput: string | null = Browser.inputBox('Введите число', 'Пожалуйста, введите число:');
if (userInput) {
const number: number = Number(userInput);
if (!isNaN(number)) {
return number;
} else {
Browser.msgBox('Ошибка', 'Введено некорректное значение. Пожалуйста, введите число.', Browser.Buttons.OK);
return null;
}
} else {
return null;
}
}Валидация введенных данных (проверка на соответствие условиям)
Валидация необходима для обеспечения корректности данных. Проверяйте введенные данные на соответствие формату, диапазону и другим условиям.
/**
* Проверяет, является ли введенная строка валидным URL.
* @param {string} url Строка для проверки.
* @return {boolean} True, если строка является валидным URL, иначе false.
*/
function isValidUrl(url: string): boolean {
try {
new URL(url);
return true;
} catch (_) {
return false;
}
}
/**
* Запрашивает URL и проверяет его валидность.
* @return {string|null} Валидный URL или null, если ввод отменен или URL не валиден.
*/
function getValidUrl(): string | null {
let url: string | null = Browser.inputBox('Введите URL', 'Пожалуйста, введите валидный URL:');
while (url && !isValidUrl(url)) {
Browser.msgBox('Ошибка', 'Введен некорректный URL. Пожалуйста, введите валидный URL.', Browser.Buttons.OK);
url = Browser.inputBox('Введите URL', 'Пожалуйста, введите валидный URL:');
}
return url;
}Интеграция окон ввода с другими элементами Google Apps Script
Окна ввода в пользовательских интерфейсах (HTML Service)
Для создания более сложных и гибких интерфейсов используйте HTML Service. Он позволяет создавать веб-страницы с элементами управления (текстовые поля, выпадающие списки, кнопки и т.д.) и взаимодействовать с ними из Google Apps Script.
Использование окон ввода в триггерах и автоматических процессах
Окна ввода можно использовать в триггерах, но следует учитывать, что триггеры выполняются в фоновом режиме и не могут напрямую взаимодействовать с пользователем. В этом случае можно использовать Script Properties для хранения настроек, которые пользователь может изменить через отдельный интерфейс.
Пример: Запись введенных данных в Google Sheets
/**
* Записывает введенные данные в Google Sheets.
*/
function writeDataToSheet(): void {
const userInput: string | null = Browser.inputBox('Введите данные', 'Пожалуйста, введите данные для записи в таблицу:');
if (userInput) {
const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const sheet: GoogleAppsScript.Spreadsheet.Sheet = ss.getActiveSheet();
sheet.appendRow([userInput]);
Browser.msgBox('Успех', 'Данные успешно записаны в таблицу.', Browser.Buttons.OK);
} else {
Browser.msgBox('Отмена', 'Запись данных отменена.', Browser.Buttons.OK);
}
}Лучшие практики и распространенные ошибки
Оптимизация пользовательского опыта при работе с окнами ввода
Используйте понятные заголовки и подсказки.
Минимизируйте количество запросов к пользователю.
Предоставляйте обратную связь о результате выполнения операции.
Избегайте использования окон ввода в длительных процессах.
Обработка ошибок и исключений
Обрабатывайте возможные ошибки при преобразовании типов данных.
Предусматривайте ситуации, когда пользователь отменяет ввод.
Используйте try...catch блоки для обработки исключений.
Альтернативные способы получения пользовательского ввода
HTML Service: Для создания более сложных и гибких интерфейсов.
Script Properties: Для хранения настроек, которые пользователь может изменить через отдельный интерфейс.
User Interface Service (UI Service): Устаревший сервис, рекомендуется использовать HTML Service.