Как выполнить форматирование чисел в Google Apps Script?

Работа с числовыми данными является неотъемлемой частью многих скриптов Google Apps Script, будь то обработка финансовой отчетности в Google Sheets, анализ метрик веб-аналитики из Google Analytics или подготовка данных для email-рассылки.

Зачем нужно форматировать числа?

Форматирование чисел необходимо для нескольких ключевых целей:

Удобочитаемость: Представление чисел в понятном для человека виде (например, с разделителями тысяч, знаком валюты или определенным количеством десятичных знаков).

Соответствие стандартам: Соблюдение правил форматирования, принятых в конкретной предметной области (например, финансовые отчеты, научные данные).

Корректное отображение: Гарантия того, что числовые данные в пользовательском интерфейсе (например, в Google Sheets или HTML-сервисах) отображаются правильно, без потери точности или двусмысленности.

Основные методы форматирования чисел в Google Apps Script

В Google Apps Script существует два основных подхода к форматированию чисел, в зависимости от контекста:

Форматирование чисел как строк: Создание строкового представления числа с заданным форматом. Это полезно для вывода данных в логи, email-сообщения, HTML-сервисы или для создания форматированных текстовых значений в ячейках.

Форматирование ячеек в Google Sheets: Применение числового формата непосредственно к ячейкам таблицы, что влияет только на отображение числа, но не на его фактическое значение. Это стандартный подход при работе с электронными таблицами.

Примеры использования форматирования чисел

Рассмотрим типовые задачи, требующие форматирования:

Отображение денежных сумм с символом валюты и двумя десятичными знаками.

Представление процентов с определенной точностью.

Использование разделителей тысяч для больших чисел (например, количество просмотров страницы).

Выравнивание чисел в текстовых отчетах с помощью отступов или заполнения нулями.

Далее мы подробно рассмотрим, как эти задачи решаются с помощью встроенных средств Google Apps Script.

Метод `Utilities.formatString()` для форматирования чисел

Метод Utilities.formatString() является частью встроенного сервиса Utilities и предназначен для форматирования строк по аналогии с функцией printf в C или String.format в Java. Он очень удобен для создания форматированных текстовых выводов.

Синтаксис и параметры `Utilities.formatString()`

Основной синтаксис выглядит так:

Utilities.formatString(format, value1, value2, ...)

format: Строка формата, содержащая обычный текст и спецификаторы формата, начинающиеся с %.

value1, value2, ...: Значения, которые будут вставлены в строку формата вместо спецификаторов.

Для чисел наиболее часто используются следующие спецификаторы:

%d: Форматирование целого числа.

%f: Форматирование числа с плавающей точкой.

%s: Форматирование как строки (может быть полезно для приведения числа).

Спецификаторы могут включать флаги, ширину поля и точность (для %f). Например:

%0d: Целое число с заполнением нулями.

%5d: Целое число в поле шириной 5 символов.

%.2f: Число с плавающей точкой, с двумя знаками после запятой.

%7.2f: Число с плавающей точкой, в поле шириной 7 символов, с двумя знаками после запятой.

Использование спецификаторов формата для чисел

Спецификаторы позволяют тонко настроить вывод чисел.

Например, для выравнивания чисел в отчете можно использовать ширину поля:

let impressionCount: number = 12345;
let clickCount: number = 567;

// Выравнивание по правому краю в поле шириной 10 символов
Logger.log(Utilities.formatString('Показы: %10d\nКлики: %10d', impressionCount, clickCount));

Вывод будет примерно таким:

Показы:      12345
Клики:        567

Примеры форматирования чисел с использованием `Utilities.formatString()`

Рассмотрим примеры, связанные с анализом маркетинговых метрик.

Предположим, у нас есть данные о расходах, конверсиях и доходе:

function formatMarketingMetrics(): void {
  const totalCost: number = 543.789;
  const conversions: number = 15;
  const revenue: number = 1250.50;
  const averageCPA: number = totalCost / conversions; // Cost Per Acquisition
  const roas: number = revenue / totalCost * 100;     // Return On Ad Spend

  // Форматируем стоимость с двумя знаками после запятой (для валюты)
  let formattedCost: string = Utilities.formatString('Стоимость: %.2f руб.', totalCost);
  Logger.log(formattedCost);

  // Форматируем CPA с двумя знаками после запятой
  let formattedCPA: string = Utilities.formatString('Средний CPA: %.2f руб.', averageCPA);
  Logger.log(formattedCPA);

  // Форматируем ROAS как процент с одним знаком после запятой
  let formattedROAS: string = Utilities.formatString('ROAS: %.1f %%', roas); // %% для вывода символа %
  Logger.log(formattedROAS);

  // Форматируем количество конверсий (целое число)
  let formattedConversions: string = Utilities.formatString('Конверсий: %d', conversions);
  Logger.log(formattedConversions);
}

Этот метод отлично подходит, когда нужно создать строковое представление числа для вывода за пределами Google Sheets.

Использование класса `NumberFormat` для форматирования чисел

Класс NumberFormat является частью сервиса Spreadsheet и предназначен для применения числовых форматов к ячейкам Google Sheets. Он позволяет настроить отображение чисел непосредственно в таблице, не меняя их базовое значение.

Получение объекта `NumberFormat` из Spreadsheet service

Вы не создаете объект NumberFormat напрямую с помощью new NumberFormat(). Вместо этого вы используете методы класса SpreadsheetApp.newNumberFormat(), который является строителем (builder).

Пример получения объекта builder:

function createCurrencyFormatBuilder(): GoogleAppsScript.Spreadsheet.NumberFormatBuilder {
  // Получаем строитель форматов
  return SpreadsheetApp.newNumberFormat();
}

Настройка формата числа с помощью `NumberFormat`

Объект builder NumberFormatBuilder предоставляет методы для указания желаемого формата:

setPattern(pattern): Устанавливает шаблон формата. Шаблоны соответствуют тем, что используются в интерфейсе Google Sheets (например, # ##0.00, 0%, yyyy-mm-dd).

setLocale(locale): Устанавливает локаль для формата (например, 'en_US', 'ru_RU'). Влияет на символы разделителей десятичных знаков и групп разрядов, а также символы валюты.

Пример настройки формата валюты:

function configureNumberFormat(): GoogleAppsScript.Spreadsheet.NumberFormat {
  const currencyPattern: string = '# ##0.00 ₽'; // Пример шаблона для рублей с разделителем тысяч
  const ruLocale: string = 'ru_RU';

  // Создаем объект формата с помощью builder
  const numberFormat: GoogleAppsScript.Spreadsheet.NumberFormat = SpreadsheetApp.newNumberFormat()
    .setPattern(currencyPattern)
    .setLocale(ruLocale) // Указываем локаль для корректных разделителей и символа валюты
    .build(); // Завершаем построение и получаем готовый формат

  return numberFormat;
}

Применение формата к ячейкам таблицы

Полученный объект NumberFormat применяется к диапазону ячеек с использованием метода setNumberFormat() объекта Range.

function applyFormatToSheet(): void {
  const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = ss.getSheetByName('ДанныеРасходов'); // Укажите имя вашего листа

  if (!sheet) {
    Logger.log('Лист с названием "ДанныеРасходов" не найден.');
    return;
  }

  // Получаем диапазон, к которому нужно применить формат (например, столбец B)
  const rangeToFormat: GoogleAppsScript.Spreadsheet.Range = sheet.getRange('B2:B' + sheet.getLastRow());

  // Настраиваем формат (используем функцию из предыдущего примера)
  const currencyFormat: GoogleAppsScript.Spreadsheet.NumberFormat = configureNumberFormat();

  // Применяем формат к диапазону
  rangeToFormat.setNumberFormat(currencyFormat);

  Logger.log('Формат валюты применен к столбцу B.');
}

Этот метод предпочтителен, когда вы работаете непосредственно с данными в Google Sheets и хотите, чтобы числа отображались в стандартном формате таблицы.

Продвинутые техники форматирования чисел

Комбинируя Utilities.formatString() и NumberFormat, можно решать более сложные задачи форматирования. Знание шаблонов формата для NumberFormat особенно важно.

Форматирование валюты

Utilities.formatString(): Используйте %.nf где n — количество знаков после запятой. Символ валюты добавляйте вручную в строку формата: Utilities.formatString('%.2f ₽', amount);

NumberFormat: Используйте шаблоны типа # ##0.00 или 0.00 в сочетании с локалью (setLocale()) или явно указывайте символ валюты в шаблоне (например, # ##0.00 ₽). Пример: SpreadsheetApp.newNumberFormat().setPattern('# ##0.00 ₽').build();

Форматирование процентов

Важно помнить, что в Google Sheets и при работе с числовыми значениями, 5% обычно представляется как 0.05. Шаблон 0% или 0.00% в NumberFormat автоматически умножит число на 100 и добавит знак процента.

Utilities.formatString(): Умножьте число на 100 перед форматированием. Используйте %.nf и добавьте %% для символа процента: Utilities.formatString('%.1f %%', percentage * 100);

NumberFormat: Используйте шаблоны 0% (целый процент), 0.0% (один знак после запятой), 0.00% (два знака после запятой) и т.д. Пример: SpreadsheetApp.newNumberFormat().setPattern('0.00%').build();

Форматирование чисел с разделителями групп разрядов

Utilities.formatString(): Стандартные спецификаторы %d и %f в Utilities.formatString не добавляют разделители тысяч автоматически в зависимости от локали. Для этого может потребоваться более сложная логика или сторонняя библиотека (если применимо и допустимо по ограничениям GAS).

NumberFormat: Шаблоны # ##0 или #,# (в английской локали) или # ##0 (в русской локали при установке локали) используются для добавления разделителей тысяч. Пример: SpreadsheetApp.newNumberFormat().setPattern('# ##0').setLocale('ru_RU').build();

Форматирование с указанием количества десятичных знаков

Utilities.formatString(): Используйте спецификатор %.nf, где n — требуемое количество знаков после запятой. Например, %.3f для трех знаков.

NumberFormat: Используйте шаблоны с нулями или символами # после десятичной точки (которая может быть точкой или запятой в зависимости от локали). 0.00 гарантирует два знака после запятой, даже если они нули. # ##0.## покажет до двух знаков после запятой, но опустит их, если они нули. Пример: SpreadsheetApp.newNumberFormat().setPattern('0.000').build();

Решение распространенных проблем и лучшие практики

При работе с форматированием чисел могут возникнуть нюансы, особенно при взаимодействии с данными из разных источников или при обработке больших объемов.

Обработка ошибок при форматировании

Метод Utilities.formatString() может выбросить исключение, если количество спецификаторов формата не соответствует количеству переданных значений. Убедитесь, что вы передаете правильное количество аргументов.

При работе с NumberFormat ошибки чаще связаны с некорректными шаблонами формата или попыткой применить формат к некорректному типу данных в ячейке (хотя Sheets обычно просто не применяет формат в таких случаях или отображает ошибку в ячейке).

Всегда полезно использовать блоки try...catch при обработке данных из внешних источников или при выполнении сложных операций форматирования.

function safeFormatValue(formatString: string, value: any): string {
  try {
    // Проверяем, является ли значение числом перед форматированием как числа
    if (typeof value === 'number' && !isNaN(value)) {
       // Можем использовать formatString с %d или %f
       return Utilities.formatString(formatString, value);
    } else {
      // Для нечисловых значений или NaN используем %s
      return Utilities.formatString('%s', value);
    }
  } catch (e) {
    Logger.log('Ошибка форматирования значения %s: %s', value, e.toString());
    return 'Ошибка форматирования'; // Возвращаем понятное сообщение об ошибке
  }
}

// Пример использования
let safeFormatted: string = safeFormatValue('Значение: %.2f', 123.456);
Logger.log(safeFormatted);

safeFormatted = safeFormatValue('Значение: %.2f', 'abc'); // Вызовет ошибку форматирования если формат %f
Logger.log(safeFormatted);

Производительность при форматировании больших объемов данных

Utilities.formatString(): Этот метод выполняется на сервере Google и обычно достаточно быстр для большинства задач, связанных с генерацией строк.

NumberFormat (Spreadsheet): Применение формата к ячейкам таблицы (range.setNumberFormat()) является операцией сервиса Spreadsheet. Выполнение этой операции для каждой ячейки по отдельности будет крайне неэффективным. Всегда применяйте формат к диапазону ячеек целиком, даже если этот диапазон охватывает весь столбец или весь лист. Это значительно сокращает количество вызовов API.

Советы по выбору оптимального метода форматирования

Выбирайте метод в зависимости от цели:

Используйте Utilities.formatString(), когда вам нужно получить строковое представление числа для вывода (логи, отчеты, email, HTML-сервисы) или для записи форматированного текста в ячейку.

Используйте NumberFormat (через SpreadsheetApp.newNumberFormat().build()) и range.setNumberFormat(), когда вам нужно изменить только отображение числа в ячейке Google Sheets, сохраняя его числовое значение для дальнейших вычислений.

В большинстве случаев при работе с таблицами предпочтительнее использовать NumberFormat, так как это сохраняет данные в числовом формате, что позволяет выполнять над ними вычисления непосредственно в Google Sheets.