Google Apps Script: Преобразование чисел в строки

Преобразование числовых данных в строковый формат является фундаментальной операцией во многих сценариях разработки на Google Apps Script (GAS). Хотя JavaScript, на котором основан GAS, часто выполняет неявное преобразование типов, явное управление этим процессом необходимо для обеспечения предсказуемости кода, корректной работы с API и правильного форматирования данных для отображения или хранения.

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Зачем преобразовывать числа в строки?

Необходимость в преобразовании чисел в строки возникает в различных ситуациях:

• Конкатенация строк: Объединение числовых значений с текстовыми описаниями (например, для создания отчетов, логов или сообщений).
• Форматирование вывода: Представление чисел в определенном формате (например, с ведущими нулями, разделителями разрядов, фиксированным количеством десятичных знаков).
• Работа с API: Многие API ожидают параметры в строковом формате, даже если они представляют числовые идентификаторы или значения.
• Ключи объектов: Использование числовых идентификаторов в качестве ключей в строковых словарях или хеш-картах.
• Работа с Google Sheets: Запись форматированных числовых значений как текста в ячейки.

Основные методы преобразования: краткий обзор

В Google Apps Script доступны несколько стандартных методов JavaScript и один специфичный для GAS:

1. String(): Глобальная функция-конструктор, безопасный способ преобразования любого значения, включая null и undefined.
2. Number.prototype.toString(): Метод объекта Number, позволяющий преобразовывать число в строку с указанием системы счисления (основания).
3. Utilities.formatString(): Сервис GAS, предоставляющий мощные возможности форматирования строк в стиле printf языка C.

Выбор метода зависит от конкретной задачи: требуется ли простое преобразование, смена системы счисления или сложное форматирование.

Использование метода String() для преобразования чисел

Функция String() является наиболее простым и безопасным способом преобразования числового значения в его строковое представление.

Синтаксис и примеры использования String()

Синтаксис предельно прост: передайте числовое значение в качестве аргумента функции.

/**
 * Демонстрирует базовое преобразование чисел в строки с помощью String().
 */
function demonstrateStringConversion() {
  const integerNumber: number = 12345;
  const stringFromInteger: string = String(integerNumber);
  Logger.log(`Integer ${integerNumber} as string: '${stringFromInteger}' (Type: ${typeof stringFromInteger})`);
  // Вывод: Integer 12345 as string: '12345' (Type: string)

  const zero: number = 0;
  const stringFromZero: string = String(zero);
  Logger.log(`Zero ${zero} as string: '${stringFromZero}' (Type: ${typeof stringFromZero})`);
  // Вывод: Zero 0 as string: '0' (Type: string)
}

Преобразование чисел с плавающей точкой

String() корректно обрабатывает числа с плавающей точкой, сохраняя их стандартное представление.

/**
 * Показывает преобразование чисел с плавающей точкой с помощью String().
 */
function floatToStringConversion() {
  const floatNumber: number = 987.65;
  const stringFromFloat: string = String(floatNumber);
  Logger.log(`Float ${floatNumber} as string: '${stringFromFloat}' (Type: ${typeof stringFromFloat})`);
  // Вывод: Float 987.65 as string: '987.65' (Type: string)

  const exponentialNumber: number = 1.23e4; // 12300
  const stringFromExponential: string = String(exponentialNumber);
  Logger.log(`Exponential ${exponentialNumber} as string: '${stringFromExponential}' (Type: ${typeof stringFromExponential})`);
  // Вывод: Exponential 12300 as string: '12300' (Type: string)
}

Особенности работы с отрицательными числами

Знак минус сохраняется при преобразовании отрицательных чисел.

/**
 * Иллюстрирует преобразование отрицательных чисел.
 */
function negativeNumberToStringConversion() {
  const negativeInteger: number = -500;
  const stringFromNegativeInt: string = String(negativeInteger);
  Logger.log(`Negative integer ${negativeInteger} as string: '${stringFromNegativeInt}'`);
  // Вывод: Negative integer -500 as string: '-500'

  const negativeFloat: number = -123.45;
  const stringFromNegativeFloat: string = String(negativeFloat);
  Logger.log(`Negative float ${negativeFloat} as string: '${stringFromNegativeFloat}'`);
  // Вывод: Negative float -123.45 as string: '-123.45'
}

Важное преимущество String() заключается в том, что он не вызывает ошибок при передаче null или undefined, преобразуя их в строки 'null' и 'undefined' соответственно. Однако для числовых преобразований всегда рекомендуется предварительная проверка типа.

Метод toString(): расширенные возможности преобразования

Метод toString(), вызываемый непосредственно у числового объекта, предоставляет дополнительные возможности, в частности, преобразование числа в строку в различных системах счисления.

Синтаксис и примеры использования toString()

Метод вызывается у числовой переменной или литерала. Без аргументов он работает аналогично String() для чисел.

/**
 * Демонстрирует использование метода toString() для чисел.
 */
function demonstrateToStringMethod() {
  const campaignId: number = 101101;
  const campaignIdStr: string = campaignId.toString();
  Logger.log(`Campaign ID ${campaignId} as string: '${campaignIdStr}' (Type: ${typeof campaignIdStr})`);
  // Вывод: Campaign ID 101101 as string: '101101' (Type: string)

  const ctr: number = 0.0567;
  const ctrStr: string = ctr.toString();
  Logger.log(`CTR ${ctr} as string: '${ctrStr}'`);
  // Вывод: CTR 0.0567 as string: '0.0567'

  // Можно вызвать и у литерала (требуются скобки)
  const literalStr: string = (123.45).toString();
  Logger.log(`Literal 123.45 as string: '${literalStr}'`);
  // Вывод: Literal 123.45 as string: '123.45'
}

Важно: Вызов toString() у переменных со значением null или undefined приведет к ошибке TypeError. Поэтому перед использованием этого метода необходима проверка на наличие реального числового значения.

Преобразование в различные системы счисления (основания)

Ключевая особенность toString() — это необязательный параметр radix (основание системы счисления), который может принимать значения от 2 до 36.

Примеры преобразования в двоичную, восьмеричную и шестнадцатеричную системы

Это полезно при работе с битовыми масками, цветами или специфическими форматами данных.

/**
 * Показывает преобразование чисел в разные системы счисления.
 */
function convertToBaseSystems() {
  const decimalNumber: number = 255;

  // В двоичную (binary, base 2)
  const binaryString: string = decimalNumber.toString(2);
  Logger.log(`${decimalNumber} in binary (radix 2): ${binaryString}`);
  // Вывод: 255 in binary (radix 2): 11111111

  // В восьмеричную (octal, base 8)
  const octalString: string = decimalNumber.toString(8);
  Logger.log(`${decimalNumber} in octal (radix 8): ${octalString}`);
  // Вывод: 255 in octal (radix 8): 377

  // В шестнадцатеричную (hexadecimal, base 16)
  const hexString: string = decimalNumber.toString(16);
  Logger.log(`${decimalNumber} in hexadecimal (radix 16): ${hexString}`);
  // Вывод: 255 in hexadecimal (radix 16): ff

  // Пример с другим числом
  const value: number = 42;
  Logger.log(`${value} (base 10) -> ${value.toString(2)} (base 2)`); // 101010
  Logger.log(`${value} (base 10) -> ${value.toString(16)} (base 16)`); // 2a
}

Форматирование чисел при преобразовании в строку

Часто простого преобразования числа в строку недостаточно. Требуется специфическое форматирование: добавление нулей, указание точности, использование разделителей.

Использование Utilities.formatString() для форматирования

Сервис Utilities в Google Apps Script предоставляет метод formatString(), который работает аналогично функции sprintf в C/C++ или других языках. Он позволяет вставлять значения в строку по заданным спецификаторам формата.

Настройка формата: добавление ведущих нулей, разделителей тысяч и десятичных знаков

Utilities.formatString() использует спецификаторы формата, начинающиеся с %. Основные для чисел:

• %d: Целое число (десятичное).
• %f: Число с плавающей точкой.
• %s: Строка (можно использовать и для чисел, но без форматирования).
• %x, %X: Шестнадцатеричное число (нижний/верхний регистр).
• %o: Восьмеричное число.

Модификаторы позволяют управлять выводом:

• %.<n>f: Задает n знаков после десятичной точки для %f.
• %<m>d: Задает минимальную ширину поля m. Пробелы добавляются слева.
• %0<m>d: Задает минимальную ширину поля m, пустое пространство заполняется ведущими нулями.

Примечание: Utilities.formatString() не поддерживает локализованные разделители тысяч (например, пробелы или запятые).

Примеры форматирования чисел для различных целей

/**
 * Демонстрирует форматирование чисел с помощью Utilities.formatString().
 */
function demonstrateNumberFormatting() {
  // Добавление ведущих нулей (например, для ID)
  const orderId: number = 78;
  const formattedOrderId: string = Utilities.formatString('ORD-%05d', orderId);
  Logger.log(`Formatted Order ID: ${formattedOrderId}`);
  // Вывод: Formatted Order ID: ORD-00078

  // Форматирование валюты или метрик с фиксированной точностью
  const price: number = 49.9;
  const formattedPrice: string = Utilities.formatString('%.2f USD', price);
  Logger.log(`Formatted Price: ${formattedPrice}`);
  // Вывод: Formatted Price: 49.90 USD

  const conversionRate: number = 0.123456;
  const formattedRate: string = Utilities.formatString('CR: %.3f%%', conversionRate * 100);
  Logger.log(`Formatted Conversion Rate: ${formattedRate}`);
  // Вывод: Formatted Conversion Rate: CR: 12.346% (обратите внимание на округление)

  // Выравнивание чисел по ширине
  const score1: number = 15;
  const score2: number = 1234;
  Logger.log(Utilities.formatString('Score 1: %6d', score1));
  Logger.log(Utilities.formatString('Score 2: %6d', score2));
  // Вывод:
  // Score 1:     15
  // Score 2:   1234
}

Практические примеры и распространенные ошибки

Рассмотрим применение этих методов в типовых задачах Google Apps Script.

Преобразование числовых значений из ячеек Google Sheets в строки

При чтении данных из таблицы важно убедиться, что значение действительно является числом, прежде чем применять методы toString() или форматирование.

/**
 * Читает числовое значение из ячейки и преобразует его в строку
 * с добавлением ведущих нулей для использования в качестве артикула.
 */
function formatSkuFromSheet() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getActiveSheet();
  const cell = sheet.getRange('A1');
  const value: any = cell.getValue();

  let sku: string = 'N/A';

  if (typeof value === 'number' && !isNaN(value)) {
    // Используем Utilities.formatString для добавления ведущих нулей
    sku = Utilities.formatString('SKU%08d', Math.trunc(value)); // Math.trunc для целой части
    Logger.log(`Read value: ${value}, Formatted SKU: ${sku}`);
  } else {
    Logger.log(`Value in A1 is not a valid number: ${value}`);
  }
  // Можно записать отформатированное значение обратно или использовать дальше
  // sheet.getRange('B1').setValue(sku);
}

Преобразование чисел для использования в API и URL

При формировании URL-запросов или отправке данных в JSON API, числовые параметры часто требуется передавать как строки.

/**
 * Формирует URL для гипотетического API отслеживания кликов,
 * где campaign_id должен быть строкой.
 */
function buildTrackingUrl() {
  const campaignId: number = 12345;
  const clickId: number = 987654321;

  // Преобразуем campaignId в строку с помощью String()
  const campaignIdStr: string = String(campaignId);

  // Click ID преобразуем через toString() для примера
  const clickIdStr: string = clickId.toString();

  // Не забываем про кодирование параметров URL
  const baseUrl: string = 'https://analytics.example.com/track';
  const url: string = `${baseUrl}?cid=${encodeURIComponent(campaignIdStr)}&clk=${encodeURIComponent(clickIdStr)}`;

  Logger.log(`Generated tracking URL: ${url}`);
  // Вывод: Generated tracking URL: https://analytics.example.com/track?cid=12345&clk=987654321
}

Распространенные ошибки и способы их исправления

1. TypeError: Cannot call method 'toString' of null (или undefined): Возникает при попытке вызвать value.toString() когда value равно null или undefined. Решение: Всегда проверяйте значение перед вызовом toString(): if (value !== null && value !== undefined) { value.toString(); } или используйте безопасный String(value). Для числовых проверок надежнее typeof value === 'number' && !isNaN(value).

2. Неожиданный результат от String() для null/undefined: String(null) возвращает 'null', String(undefined) возвращает 'undefined'. Если ожидается пустая строка или другое значение по умолчанию, нужна явная проверка: const strValue = (numericValue === null || numericValue === undefined) ? '' : String(numericValue);

3. Неправильный формат в Utilities.formatString(): Использование некорректных спецификаторов или несоответствие типов аргументов может привести к ошибкам или неверному результату. Решение: Тщательно проверяйте строку формата и типы передаваемых аргументов. Обратитесь к документации при необходимости.

4. Потеря точности при работе с большими числами или дробями: Стандартные проблемы работы с числами с плавающей точкой в JavaScript актуальны и для GAS. Решение: Для финансовых расчетов или при необходимости высокой точности рассмотрите использование специализированных библиотек или методов округления (toFixed(), Math.round/floor/ceil) перед преобразованием в строку.

Осознанный выбор метода преобразования и внимание к возможным граничным случаям и ошибкам помогут создавать надежный и предсказуемый код в Google Apps Script.