Что такое меню в Google Apps Script и зачем оно нужно?
Меню в Google Apps Script – это настраиваемый интерфейс, который позволяет пользователям взаимодействовать со скриптом непосредственно из интерфейса Google Sheets, Docs, Forms или Slides. Это намного удобнее, чем вызывать функции скрипта непосредственно из редактора кода. Меню позволяют автоматизировать задачи, запускать аналитику, интегрировать данные из внешних источников и расширять функциональность базовых приложений Google Workspace.
Представьте, что вы создали скрипт для автоматической генерации отчетов контекстной рекламы на основе данных Google Ads API. Вместо того, чтобы каждый раз открывать редактор скриптов и запускать функцию, вы можете добавить пункт меню "Сформировать отчет", который будет доступен прямо в Google Sheets. Это значительно упрощает работу для не-программистов.
Основные типы меню и их применение
В Google Apps Script меню создаются программно. В основном, существует один тип меню, которое вы настраиваете, добавляя пункты и подменю.
Применение меню варьируется в зависимости от задачи: автоматизация отчетов, управление задачами (например, обновление статусов в Google Sheets), экспорт данных в нестандартные форматы, интеграция с внешними сервисами и многое другое.
Предварительные требования: доступ к редактору скриптов
Для создания меню вам потребуется доступ к редактору скриптов Google Apps Script. Открыть его можно из любого приложения Google Workspace (Sheets, Docs, Forms, Slides) через меню "Инструменты" -> "Редактор скриптов".
Создание простого меню
Базовый синтаксис функции `onOpen()`
Функция onOpen() является специальной функцией, которая автоматически запускается при открытии документа Google Sheets, Docs, Forms или Slides. Именно в этой функции необходимо создавать меню.
/**
* @OnlyCurrentDoc
*/
function onOpen() {
// Код для создания меню
}Аннотация @OnlyCurrentDoc рекомендуется для повышения безопасности. Она ограничивает доступ скрипта только к текущему документу.
Добавление меню с одной командой
Для добавления меню используется объект SpreadsheetApp (для Sheets), DocumentApp (для Docs), FormApp (для Forms) или SlidesApp (для Slides). Метод getUi() возвращает объект Ui, который предоставляет методы для создания меню.
Пример кода: создание простого меню, выводящего сообщение
/**
* @OnlyCurrentDoc
*/
function onOpen() {
SpreadsheetApp.getUi()
.createMenu('Custom Menu')
.addItem('Show Alert', 'showAlert')
.addToUi();
}
/**
* Displays an alert message.
*/
function showAlert() {
SpreadsheetApp.getUi() // Same patterns as above.
.alert('Hello, world!');
}Запуск функции `onOpen()` для отображения меню
После добавления кода, необходимо обновить страницу с Google Sheets (или Docs, Forms, Slides). После обновления в интерфейсе появится новое меню с названием "Custom Menu" и пунктом "Show Alert". При нажатии на пункт меню будет выведено всплывающее сообщение "Hello, world!".
Обратите внимание: при первом запуске скрипта Google Apps Script запросит разрешения на доступ к вашему аккаунту.
Добавление команд в меню
Функция `addItem()`: добавление новых пунктов меню
Функция addItem() добавляет новый пункт в меню. Каждый пункт меню связан с функцией, которая будет выполняться при выборе этого пункта.
Параметры функции `addItem()`: текст пункта и функция для вызова
Функция addItem() принимает два параметра:
Текст пункта меню: Строка, отображаемая в меню.
Название функции для вызова: Строка, представляющая имя функции, которая будет вызвана при выборе пункта меню.
Пример кода: добавление нескольких команд в меню
/**
* @OnlyCurrentDoc
*/
function onOpen() {
SpreadsheetApp.getUi()
.createMenu('Analytics')
.addItem('Generate Google Ads Report', 'generateAdsReport')
.addItem('Export Data to CSV', 'exportToCSV')
.addSeparator()
.addItem('Refresh Data', 'refreshData')
.addToUi();
}
/**
* Generates a Google Ads report (placeholder function).
*/
function generateAdsReport() {
SpreadsheetApp.getUi().alert('Generating Google Ads Report...');
// Здесь будет код для генерации отчета.
}
/**
* Exports data to CSV (placeholder function).
*/
function exportToCSV() {
SpreadsheetApp.getUi().alert('Exporting to CSV...');
// Здесь будет код для экспорта данных.
}
/**
* Refreshes data (placeholder function).
*/
function refreshData() {
SpreadsheetApp.getUi().alert('Refreshing data...');
// Здесь будет код для обновления данных.
}В этом примере создано меню "Analytics" с тремя пунктами и разделителем. Каждый пункт вызывает свою функцию.
Создание подменю
Использование `addSubMenu()` для организации меню
Функция addSubMenu() позволяет создавать вложенные меню, что полезно для организации большого количества команд.
Пример кода: создание подменю с несколькими командами
/**
* @OnlyCurrentDoc
*/
function onOpen() {
SpreadsheetApp.getUi()
.createMenu('Data Management')
.addSubMenu(SpreadsheetApp.getUi().createMenu('Import')
.addItem('Import from Google Ads', 'importFromAds')
.addItem('Import from CSV', 'importFromCSV'))
.addSubMenu(SpreadsheetApp.getUi().createMenu('Export')
.addItem('Export to CSV', 'exportToCSV')
.addItem('Export to JSON', 'exportToJSON'))
.addToUi();
}
/**
* Imports data from Google Ads (placeholder function).
*/
function importFromAds() {
SpreadsheetApp.getUi().alert('Importing from Google Ads...');
// Здесь будет код для импорта данных из Google Ads.
}
/**
* Imports data from CSV (placeholder function).
*/
function importFromCSV() {
SpreadsheetApp.getUi().alert('Importing from CSV...');
// Здесь будет код для импорта данных из CSV.
}
/**
* Exports data to CSV (placeholder function).
*/
function exportToCSV() {
SpreadsheetApp.getUi().alert('Exporting to CSV...');
// Здесь будет код для экспорта данных в CSV.
}
/**
* Exports data to JSON (placeholder function).
*/
function exportToJSON() {
SpreadsheetApp.getUi().alert('Exporting to JSON...');
// Здесь будет код для экспорта данных в JSON.
}В этом примере создано меню "Data Management" с двумя подменю: "Import" и "Export". Каждое подменю содержит свои пункты.
Вложенные подменю: организация сложной структуры
Можно создавать более сложные структуры меню, добавляя подменю внутрь подменю. Однако, рекомендуется не злоупотреблять вложенностью, чтобы не усложнять навигацию для пользователей.
Расширенные возможности меню
Динамическое создание меню в зависимости от условий
Меню можно создавать динамически, в зависимости от текущего состояния документа или данных. Например, можно добавлять пункты меню, которые доступны только для администраторов или в зависимости от значения определенной ячейки.
/**
* @OnlyCurrentDoc
*/
function onOpen() {
let userEmail = Session.getActiveUser().getEmail();
let menu = SpreadsheetApp.getUi().createMenu('Dynamic Menu');
if (userEmail === 'admin@example.com') {
menu.addItem('Admin Action', 'adminAction');
} else {
menu.addItem('User Action', 'userAction');
}
menu.addToUi();
}
/**
* Admin action (placeholder function).
*/
function adminAction() {
SpreadsheetApp.getUi().alert('Admin Action!');
}
/**
* User action (placeholder function).
*/
function userAction() {
SpreadsheetApp.getUi().alert('User Action!');
}Использование иконок в меню (если применимо, с учетом ограничений)
К сожалению, Google Apps Script не предоставляет встроенной возможности добавлять иконки к пунктам меню. Это ограничение платформы.
Обработка ошибок и отладка меню
Для отладки меню можно использовать Logger.log() для вывода сообщений в журнал выполнения скрипта. Также, рекомендуется использовать блоки try...catch для обработки возможных ошибок.
function generateAdsReport() {
try {
SpreadsheetApp.getUi().alert('Generating Google Ads Report...');
// Здесь будет код для генерации отчета.
} catch (e) {
Logger.log('Error generating report: ' + e);
SpreadsheetApp.getUi().alert('An error occurred while generating the report. See the logs for details.');
}
}Рекомендации по оптимизации меню для лучшей производительности
Избегайте выполнения длительных операций непосредственно в функции onOpen(), чтобы меню отображалось быстро.
Используйте асинхронные вызовы для выполнения длительных операций в фоновом режиме.
Оптимизируйте код функций, вызываемых из меню, чтобы они выполнялись быстро.
Не создавайте слишком много пунктов меню, чтобы не перегружать интерфейс.