appsscript

appsscript содержит всё, что касается сервисов Google. Это та часть библиотеки, которая работает только внутри среды Apps Script, — что это значит для тестов, разобрано в Среда выполнения Apps Script.

Пакеты

Пакет	Содержит
`appsscript/base`	общие помощники для остальных пакетов сервисов
`appsscript/admin`	сервис Admin SDK Directory
`appsscript/sheet`	Таблицы: строки, столбцы, нотация A1, `GridRange`, проверки типов
`appsscript/slide`	Презентации: поиск слайдов, замена текста, преобразование Markdown
`appsscript/net`	аутентификацию запросов
`appsscript/ui`	встроенные классы `Ui`, `HtmlOutput` и `TextOutput`
`appsscript/doc`, `appsscript/drive`, `appsscript/form`	зарезервированы, пока не реализованы

Нотация A1

parseA1Notation превращает строку нотации в GridRange — простой объект с границами от нуля и невключённой правой границей, как в Sheets API, а не позициями от единицы, которые принимают методы Range:

import { parseA1Notation } from "apps-script-utils";

parseA1Notation("Sheet1!A1:B10");
// {
//   sheetName: "Sheet1",
//   a1Notation: "A1:B10",
//   startRowIndex: 0,
//   endRowIndex: 10,
//   startColumnIndex: 0,
//   endColumnIndex: 2
// }

parseA1Notation("B5");
// { sheetName: null, a1Notation: "B5", startRowIndex: 4, endRowIndex: 5, ... }

Открытые нотации тоже разбираются: "5:15" оставляет границы столбцов незаданными, "M:X" — границы строк.

toA1Notation — обратная операция:

import { toA1Notation } from "apps-script-utils";

toA1Notation({ startRowIndex: 0, endRowIndex: 10, startColumnIndex: 0, endColumnIndex: 2 });
// "A1:B10"

parseA1Notations принимает список через запятую и возвращает по одному GridRange на запись:

import { parseA1Notations } from "apps-script-utils";

parseA1Notations("Sheet1!A1:B2, Sheet1!D1"); // два объекта GridRange

Имя листа можно прочитать, заменить или отбросить, не разбирая нотацию заново:

import {
  extractRangeFromA1Notation,
  extractSheetNameFromA1Notation,
  updateSheetNameInA1Notation
} from "apps-script-utils";

extractSheetNameFromA1Notation("'My Sheet'!A1"); // "My Sheet"
extractRangeFromA1Notation("'My Sheet'!A1:B2"); // "A1:B2"
updateSheetNameInA1Notation("Sheet1!A1:B2", "Data"); // "Data!A1:B2"

Столбцы

В ходу две схемы нумерации, и имена функций говорят, какую именно они возвращают. Индекс считается от нуля, как в GridRange; позиция — от единицы, как в Sheet.getRange():

import {
  getColumnIndexByLetter,
  getColumnLetterByIndex,
  getColumnPositionByLetter
} from "apps-script-utils";

getColumnIndexByLetter("A"); // 0
getColumnIndexByLetter("AZ"); // 51
getColumnLetterByIndex(0); // "A"
getColumnLetterByIndex(51); // "AZ"
getColumnPositionByLetter("A"); // 1

Сравнение диапазонов

Объекты GridRange сравниваются без похода к сервису:

import {
  doGridRangesIntersect,
  isCellGridRange,
  isGridRangeContainedIn,
  isGridRangeSameDimensions
} from "apps-script-utils";

const header = { startRowIndex: 0, endRowIndex: 1, startColumnIndex: 0, endColumnIndex: 5 };
const body = { startRowIndex: 1, endRowIndex: 100, startColumnIndex: 0, endColumnIndex: 5 };

doGridRangesIntersect(header, body); // false
isCellGridRange(header); // false — он занимает пять столбцов

Запись строк и столбцов

import { appendRows, prependRows, appendColumns } from "apps-script-utils";

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data");

appendRows(sheet, [
  ["John Doe", "john@example.com", 28],
  ["Jane Smith", "jane@example.com", 32]
]);

prependRows(sheet, [["Name", "Email", "Age"]]);

Они пишут за один вызов, а не построчно, — это разница между одним походом к сервису и походом на каждую строку. Все строки должны быть одной длины; проверить это заранее помогает isConsistent2DArray из lang.

Проверки типов для объектов сервисов

То же соглашение, что и во всей библиотеке, применённое к классам Apps Script:

import { isSheet, isSpreadsheet, isRange, requireSheet } from "apps-script-utils";

function rowCount(value: unknown): number {
  return requireSheet(value).getLastRow();
}

requireSheet, requireSpreadsheet и requireRange бросают InvalidSheetException, InvalidSpreadsheetException и InvalidRangeException соответственно — смотрите Обработка исключений.

Презентации

import { getSlideByIndex, findReplaceAllTextInSlide, requireSlide } from "apps-script-utils";

const presentation = SlidesApp.getActivePresentation();

// getSlideByIndex возвращает null, если индекс за пределами, поэтому его
// сочетают с requireSlide там, где отсутствие слайда должно остановить скрипт.
const slide = requireSlide(getSlideByIndex(presentation, 0));

findReplaceAllTextInSlide(slide, "{{name}}", "Ada Lovelace");

findReplaceAllTextInSlide возвращает число сделанных замен и по умолчанию учитывает регистр; передайте false четвёртым аргументом для поиска без учёта регистра. requireSlide бросает SlideNotFoundException, если значение не является слайдом.

Admin SDK

import { isAdmin } from "apps-script-utils";

if (isAdmin()) {
  Logger.log("Access granted to admin panel.");
}

isAdmin возвращает false, если сервис Admin SDK Directory не включён в проекте, записывая причину в журнал, а не бросая исключение. Вызов поэтому безопасен даже при построении меню, но false сам по себе ещё не доказывает, что пользователь не администратор. Включите расширенный сервис, прежде чем полагаться на ответ.

23 September 2026

Эта документация сгенерирована нейросетью (Claude) на основе исходного кода библиотеки.