Что такое активный диапазон?
Активный диапазон в Google Sheets (и, следовательно, в Google Apps Script) — это выделенная область ячеек на листе. Когда пользователь выбирает одну или несколько ячеек, этот выделенный фрагмент становится активным диапазоном. Это ключевое понятие для автоматизации задач, требующих взаимодействия с пользовательским вводом или текущей областью интереса пользователя.
Зачем получать активный диапазон?
Получение активного диапазона позволяет:
Автоматически обрабатывать данные, с которыми в данный момент работает пользователь.
Создавать скрипты, реагирующие на выделение ячеек.
Разрабатывать пользовательские функции, применяемые к выбранной области.
Реагировать на изменения в выделенной области через триггеры.
Методы получения активного диапазона
Использование `getActiveRange()` для получения активного диапазона на листе
Самый простой способ получить активный диапазон — использовать метод getActiveRange() объекта SpreadsheetApp. Этот метод возвращает объект Range, представляющий текущий активный диапазон на активном листе. Важно отметить, что если активного диапазона нет (например, если ни одна ячейка не выделена), метод вернет null.
Пример кода: Простое получение и вывод активного диапазона
/**
* Функция для получения и логирования активного диапазона.
*/
function logActiveRange() {
// Получаем активную таблицу.
const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
// Получаем активный лист.
const sheet: GoogleAppsScript.Spreadsheet.Sheet = ss.getActiveSheet();
// Получаем активный диапазон.
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
// Проверяем, что активный диапазон существует.
if (activeRange) {
// Логируем адрес активного диапазона.
Logger.log(`Активный диапазон: ${activeRange.getA1Notation()}`);
} else {
Logger.log('Активный диапазон не выбран.');
}
}Работа с активным диапазоном
Получив объект Range, можно выполнять различные операции с активным диапазоном.
Получение значений из активного диапазона (`getValues()`)
Метод getValues() возвращает двумерный массив, содержащий значения ячеек активного диапазона.
/**
* Функция для получения значений из активного диапазона.
*/
function getActiveRangeValues(): any[][] | null {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
const values: any[][] = activeRange.getValues();
Logger.log(values);
return values; // Возвращаем массив значений
} else {
Logger.log('Активный диапазон не выбран.');
return null; // Возвращаем null, если диапазон не выбран
}
}Запись данных в активный диапазон (`setValues()`)
Метод setValues() позволяет записать данные в активный диапазон. Аргументом является двумерный массив, соответствующий размеру диапазона.
/**
* Функция для записи данных в активный диапазон.
*/
function setActiveRangeValues(data: any[][]): void {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
activeRange.setValues(data);
} else {
Logger.log('Активный диапазон не выбран.');
}
}Получение размера активного диапазона (`getNumRows()`, `getNumColumns()`)
Методы getNumRows() и getNumColumns() возвращают количество строк и столбцов в активном диапазоне, соответственно.
/**
* Функция для получения размеров активного диапазона.
*/
function getActiveRangeSize(): { rows: number; columns: number } | null {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
const rows: number = activeRange.getNumRows();
const columns: number = activeRange.getNumColumns();
Logger.log(`Строк: ${rows}, Столбцов: ${columns}`);
return { rows: rows, columns: columns };
} else {
Logger.log('Активный диапазон не выбран.');
return null;
}
}Очистка содержимого активного диапазона (`clearContent()`)
Метод clearContent() удаляет содержимое всех ячеек в активном диапазоне, оставляя только форматирование.
/**
* Функция для очистки содержимого активного диапазона.
*/
function clearActiveRangeContent(): void {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
activeRange.clearContent();
} else {
Logger.log('Активный диапазон не выбран.');
}
}Расширенные сценарии использования активного диапазона
Обработка нескольких активных диапазонов (например, при выделении нескольких областей)
Если пользователь выделил несколько несвязных областей, getActiveRange() вернет только первую выделенную область. Для обработки всех выделенных областей потребуется более сложный код, возможно, с использованием событий мыши и API Spreadsheet.
Активный диапазон в пользовательских диалоговых окнах
Активный диапазон можно использовать для передачи данных между пользовательским диалоговым окном и таблицей. Например, можно открыть диалоговое окно, которое отображает данные из активного диапазона и позволяет пользователю их редактировать.
Активный диапазон и триггеры Google Apps Script
Можно использовать триггеры onSelectionChange (если он доступен) или onChange, чтобы отслеживать изменения в активном диапазоне и выполнять определенные действия. Однако, использование onChange может потребовать дополнительной фильтрации для определения, что изменение произошло именно в результате изменения выделения.
Практические примеры и советы
Пример: Автоматическое форматирование активного диапазона
/**
* Функция для автоматического форматирования активного диапазона.
*/
function formatActiveRange(): void {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
activeRange.setFontWeight('bold');
activeRange.setBackgroundColor('#FFFF00');
activeRange.setHorizontalAlignment('center');
} else {
Logger.log('Активный диапазон не выбран.');
}
}Пример: Отправка данных из активного диапазона по электронной почте
/**
* Функция для отправки данных из активного диапазона по электронной почте.
*/
function sendActiveRangeDataByEmail(emailAddress: string): void {
const sheet: GoogleAppsScript.Spreadsheet.Sheet = SpreadsheetApp.getActiveSheet();
const activeRange: GoogleAppsScript.Spreadsheet.Range | null = sheet.getActiveRange();
if (activeRange) {
const values: any[][] = activeRange.getValues();
const subject: string = 'Данные из активного диапазона';
const body: string = values.map(row => row.join(', ')).join('\n');
MailApp.sendEmail({
to: emailAddress,
subject: subject,
body: body
});
Logger.log(`Данные отправлены на ${emailAddress}`);
} else {
Logger.log('Активный диапазон не выбран.');
}
}Советы по оптимизации работы с активным диапазоном
Проверяйте наличие активного диапазона: Всегда проверяйте, что getActiveRange() возвращает не null, прежде чем пытаться с ним работать.
Минимизируйте вызовы API: Каждый вызов API Google Sheets занимает время. Старайтесь объединять операции, например, использовать setValues() вместо многократных вызовов setValue().
Используйте пакетные операции: Для больших диапазонов используйте методы, которые позволяют выполнять операции пакетами (например, getValues() и setValues()).
Учитывайте права доступа: Убедитесь, что у скрипта есть необходимые права доступа для работы с таблицей.