Что такое боковая панель в Google Apps Script?
Боковая панель в Google Apps Script – это пользовательский интерфейс, который отображается сбоку от основного окна приложения Google Workspace (например, Google Docs, Sheets, Slides, Forms). Она предоставляет пользователям удобный способ взаимодействия со скриптом, не прерывая их работу с основным документом или таблицей. Боковая панель, по сути, представляет собой HTML-страницу, отображаемую в iframe и взаимодействующую со скриптом через API google.script.run.
Преимущества использования боковых панелей
- Улучшенный пользовательский опыт: Боковые панели обеспечивают более интуитивно понятный и интегрированный способ взаимодействия со скриптом.
- Непрерывность работы: Пользователи могут взаимодействовать со скриптом, не переключаясь между окнами и не теряя контекст.
- Более сложное UI: Боковые панели поддерживают HTML, CSS и JavaScript, что позволяет создавать более сложные и интерактивные интерфейсы, чем стандартные диалоговые окна.
- Персистентность: Боковая панель остается открытой, пока пользователь не закроет ее, что позволяет выполнять несколько операций подряд.
Когда следует использовать боковую панель вместо диалогового окна
Используйте боковую панель, если:
- Требуется более сложное и интерактивное взаимодействие с пользователем.
- Необходимо отображать информацию, которая часто обновляется.
- Пользователь должен выполнять несколько связанных операций подряд.
- Нужен UI, который постоянно доступен во время работы с документом.
Диалоговое окно лучше подходит для простых запросов информации или выполнения одной операции.
Создание простой боковой панели
Необходимый код Apps Script для отображения боковой панели
Этот код показывает, как отобразить простую боковую панель. В нем вызывается HTML-файл, который будет загружен на боковую панель.
/**
* Отображает боковую панель в текущем документе.
*/
function showSidebar() {
// Получаем HTML-контент из файла "Sidebar"
const html = HtmlService.createHtmlOutputFromFile('Sidebar')
.setTitle('My Custom Sidebar');
// Отображаем боковую панель
SpreadsheetApp.getUi()
.showSidebar(html);
}
/**
* Функция, выполняемая при открытии документа.
*/
function onOpen() {
SpreadsheetApp.getUi()
.createMenu('Custom Menu')
.addItem('Show Sidebar', 'showSidebar')
.addToUi();
}
HTML, CSS и JavaScript для содержимого боковой панели
Пример HTML-кода для файла Sidebar.html:
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<style>
body {
font-family: sans-serif;
}
.container {
padding: 10px;
}
button {
background-color: #4CAF50; /* Green */
border: none;
color: white;
padding: 10px 20px;
text-align: center;
text-decoration: none;
display: inline-block;
font-size: 16px;
margin: 4px 2px;
cursor: pointer;
}
</style>
</head>
<body>
<div class="container">
<h1>Hello from Sidebar!</h1>
<button onclick="google.script.run.showAlert('Button Clicked!')">Click Me</button>
</div>
<script>
function onSuccess() {
console.log('Success!');
}
</script>
</body>
</html>
Развертывание и запуск боковой панели
- Создайте скрипт Google Apps Script (например, в Google Sheets: Инструменты > Редактор скриптов).
- Скопируйте код Apps Script в редактор.
- Создайте HTML-файл с именем
Sidebar.htmlи скопируйте HTML-код в него. - Сохраните оба файла.
- Обновите таблицу (или документ).
- Появится пункт меню «Custom Menu». Выберите Custom Menu > Show Sidebar для отображения боковой панели.
Примеры реализации боковых панелей
Боковая панель для управления форматированием документов
Боковая панель может предоставлять элементы управления для изменения шрифта, размера шрифта, цвета и т. д. Вы можете реализовать интерактивные элементы для выбора параметров форматирования.
function setBold() {
DocumentApp.getActiveDocument().getSelection().getSelectedElement().editAsText().setBold(true);
}
Боковая панель для работы с данными Google Sheets (чтение и запись)
Например, боковая панель может отображать статистику по данным в таблице или предоставлять интерфейс для фильтрации и сортировки данных. Также, боковая панель может давать возможность пакетного обновления данных.
/**
* Читает данные из листа и возвращает их в боковую панель.
* @return {Array<Array<any>>} Данные из листа.
*/
function getDataFromSheet(): any[][] {
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getActiveSheet();
const range = sheet.getDataRange();
const values = range.getValues();
return values;
}
/**
* Записывает данные в лист.
* @param {Array<Array<any>>} data Данные для записи.
*/
function writeDataToSheet(data: any[][]): void {
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getActiveSheet();
sheet.clearContents(); // Очистка содержимого листа
sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
}
Боковая панель для отправки электронных писем через Gmail
Боковая панель может позволять пользователю составлять и отправлять электронные письма, используя данные из текущего документа или таблицы. Например, боковая панель может предварительно заполнить поля «To», «Subject» и «Body» из Google Sheets.
/**
* Отправляет электронное письмо.
* @param {string} recipient Адрес электронной почты получателя.
* @param {string} subject Тема письма.
* @param {string} body Тело письма.
*/
function sendEmail(recipient: string, subject: string, body: string): void {
GmailApp.sendEmail(recipient, subject, body);
}
Боковая панель с использованием SpreadsheetApp/DocumentApp/GmailApp
Эти примеры показывают, как можно использовать боковую панель для взаимодействия с Google Sheets, Docs и Gmail.
Взаимодействие между боковой панелью и Google Apps Script
Передача данных из Apps Script в боковую панель (google.script.run)
Функция google.script.run позволяет вызывать функции Apps Script из JavaScript в боковой панели и передавать данные между ними.
// Apps Script
function getServerData() {
return { message: 'Hello from Apps Script!' };
}
// HTML (внутри <script>)
google.script.run.withSuccessHandler(function(data) {
console.log(data.message); // Выведет "Hello from Apps Script!"
}).getServerData();
Вызов функций Apps Script из боковой панели (google.script.run)
// HTML (внутри <script>)
function myClientFunction() {
google.script.run.withSuccessHandler(function(result) {
// Обработка результата
console.log('Result from server:', result);
}).myServerFunction('some argument');
}
// Apps Script
function myServerFunction(arg) {
Logger.log('Argument received:', arg);
return 'Server processed: ' + arg;
}
Асинхронные вызовы и обработка ответов
google.script.run выполняет вызовы асинхронно. Используйте withSuccessHandler, withFailureHandler и withUserObject для обработки ответов и ошибок.
// HTML
google.script.run
.withSuccessHandler(onSuccess)
.withFailureHandler(onFailure)
.getData();
function onSuccess(data) {
// Обработка данных
}
function onFailure(error) {
// Обработка ошибки
console.error(error);
}
Советы и лучшие практики
Безопасность боковых панелей
- Валидация данных: Всегда проверяйте данные, поступающие из боковой панели, чтобы предотвратить инъекции кода.
- Ограничение доступа: Используйте авторизацию и аутентификацию для ограничения доступа к функциям скрипта.
- Sanitization: Очищайте данные перед отображением в HTML, чтобы предотвратить XSS-атаки.
Обработка ошибок и отладка
- Используйте
try...catchблоки для обработки ошибок в Apps Script. - Используйте
console.logдля отладки JavaScript в боковой панели. Просмотреть логи можно в Инструменты > Журналы редактора. - Используйте
withFailureHandlerдля обработки ошибок при вызове функций Apps Script из боковой панели.
Оптимизация производительности боковой панели
- Минимизация вызовов Apps Script: Старайтесь передавать больше данных за один вызов, чтобы уменьшить количество запросов.
- Кэширование данных: Кэшируйте данные, которые не часто меняются, чтобы избежать повторных запросов.
- Оптимизация HTML/CSS/JavaScript: Используйте минификацию и сжатие для уменьшения размера файлов.
Рекомендации по дизайну пользовательского интерфейса (UI)
- Простота и понятность: Дизайн должен быть интуитивно понятным и простым в использовании.
- Адаптивность: Боковая панель должна корректно отображаться на разных устройствах и разрешениях.
- Соответствие стилю Google Workspace: Соблюдайте рекомендации Google по стилю UI для обеспечения единообразия.
- Использование Material Design: Material Design предоставляет готовые компоненты и стили для создания современного и удобного UI.