Поделиться через


ExcelScript.Worksheet interface

Лист Excel представляет собой сетку ячеек. Он может содержать данные, таблицы, диаграммы и т. д.

Замечания

Примеры

/**
 * This script creates a new worksheet named "Plum" and sets its tab color to purple.
 */
function main(workbook: ExcelScript.Workbook) {
  const newSheet = workbook.addWorksheet("Plum")
  newSheet.setTabColor("purple");
}

Методика

activate()

Активация листа в пользовательском интерфейсе Excel.

addChart(type, sourceData, seriesBy)

Создает диаграмму.

addComment(cellAddress, content, contentType)

Создает новое примечание с указанным содержимым в определенной ячейке. Если InvalidArgument указанный диапазон больше одной ячейки, возникает ошибка.

addGeometricShape(geometricShapeType)

Добавляет геометрическую фигуру на лист. Shape Возвращает объект, представляющий новую фигуру.

addGroup(values)

Группирует подмножество фигур на листе этой коллекции. Shape Возвращает объект , представляющий новую группу фигур.

addHorizontalPageBreak(pageBreakRange)

Добавляет разрыв страницы перед левой верхней ячейкой указанного диапазона.

addImage(base64ImageString)

Создает изображение из строки в кодировке Base64 и добавляет его на лист. Shape Возвращает объект , представляющий новое изображение.

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Добавляет линию на лист. Shape Возвращает объект , представляющий новую строку.

addNamedItem(name, reference, comment)

Добавляет новое имя в определенную коллекцию.

addNamedItemFormulaLocal(name, formula, comment)

Добавляет новое имя в определенную коллекцию, используя языковой стандарт пользователя для формулы.

addNamedSheetView(name)

Создает представление листа с заданным именем.

addPivotTable(name, source, destination)

Добавьте сводную таблицу на основе указанных исходных данных и вставьте ее в левую верхнюю ячейку целевого диапазона.

addSlicer(slicerSource, sourceField, slicerDestination)

Добавляет новый срез в книгу.

addTable(address, hasHeaders)

Создает таблицу. Объект или исходный адрес диапазона определяет лист, на который будет добавлена таблица. Если добавить таблицу не удается (например, если адрес недействителен или одна таблица будет перекрываться другой), выводится сообщение об ошибке.

addTextBox(text)

Добавляет текстовое поле на лист с указанным текстом в качестве содержимого. Shape Возвращает объект , представляющий новое текстовое поле.

addVerticalPageBreak(pageBreakRange)

Добавляет разрыв страницы перед левой верхней ячейкой указанного диапазона.

addWorksheetCustomProperty(key, value)

Добавляет новое пользовательское свойство, которое сопоставляется с предоставленным ключом. При этом существующие настраиваемые свойства перезаписываются этим ключом.

calculate(markAllDirty)

Вычисляет все ячейки на листе.

copy(positionType, relativeTo)

Копирует лист и помещает его в указанное положение.

delete()

Удаляет лист из книги. Обратите внимание, что если для видимости листа задано значение VeryHidden, операция удаления завершится ошибкой InvalidOperation с исключением. Сначала необходимо изменить видимость на скрытую или видимую перед удалением.

enterTemporaryNamedSheetView()

Создает и активирует новое временное представление листа. Временные представления удаляются при закрытии приложения, выходе из временного представления с помощью метода exit или переключении в другое представление листа. Доступ к временному представлению листа также можно получить с помощью пустой строки (""), если временное представление существует.

exitActiveNamedSheetView()

Выход из текущего активного представления листа.

findAll(text, criteria)

Находит все вхождения заданной строки на основе заданных критериев и возвращает их в виде RangeAreas объекта, состоящего из одного или нескольких прямоугольных диапазонов.

getActiveNamedSheetView()

Возвращает текущее активное представление листа.

getAutoFilter()

Представляет AutoFilter объект листа.

getCell(row, column)

Возвращает объект, Range содержащий одну ячейку на основе номеров строк и столбцов. Ячейка может находиться за пределами родительского диапазона, если она находится в сетке листа.

getChart(name)

Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них. Если диаграмма не существует, этот метод возвращает .undefined

getCharts()

Возвращает коллекцию диаграмм, которые являются частью листа.

getComment(commentId)

Получает примечание из коллекции на основе его идентификатора. Если объект comment не существует, этот метод возвращает undefined.

getCommentByCell(cellAddress)

Получает примечание из указанной ячейки. Если в ячейке нет комментария, возникает ошибка.

getCommentByReplyId(replyId)

Возвращает комментарий, к которому подключен данный ответ.

getComments()

Возвращает коллекцию всех объектов Comments на листе.

getCustomProperties()

Возвращает коллекцию настраиваемых свойств на уровне листа.

getEnableCalculation()

Определяет, следует ли excel пересчитывать лист при необходимости. Значение true, если Excel пересчитывает лист при необходимости. Значение false, если Excel не пересчитывает лист.

getFreezePanes()

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

getHorizontalPageBreaks()

Получает коллекцию горизонтальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

getId()

Возвращает значение, однозначно идентифицирующее лист в данной книге. Значение идентификатора остается прежним, даже если переименовать или переместить лист.

getName()

Отображаемое имя листа. Имя должно содержать менее 32 символов.

getNamedItem(name)

Возвращает объект, NamedItem используя его имя. Если объект не существует, этот метод возвращает undefined.

getNamedSheetView(key)

Возвращает представление листа, используя его имя. Если объект представления листа не существует, то этот метод возвращает объект со свойством isNullObjecttrue.

getNamedSheetViews()

Возвращает коллекцию представлений листа, присутствующих на листе.

getNames()

Коллекция имен, относящих к текущему листу.

getNext(visibleOnly)

Возвращает лист, следующий за этим. Если после этого листа нет, этот метод возвращает undefined.

getPageLayout()

PageLayout Возвращает объект листа.

getPivotTable(name)

Получает сводную таблицу по имени. Если сводная таблица не существует, этот метод возвращает undefined.

getPivotTables()

Коллекция сводных таблиц на листе.

getPosition()

Положение листа (начиная с нуля) в книге.

getPrevious(visibleOnly)

Возвращает лист, предшествующий этому листу. Если предыдущих листов нет, этот метод возвращает undefined.

getProtection()

Возвращает объект защиты листа для листа.

getRange(address)

Range Возвращает объект , представляющий один прямоугольный блок ячеек, заданный адресом или именем.

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

Возвращает объект, Range начинающийся с определенного индекса строки и индекса столбца и охватывающий определенное количество строк и столбцов.

getRanges(address)

RangeAreas Возвращает объект , представляющий один или несколько блоков прямоугольных диапазонов, заданных адресом или именем.

getShape(key)

Возвращает фигуру, используя ее имя или идентификатор. Если объект shape не существует, этот метод возвращает undefined.

getShapes()

Возвращает коллекцию всех объектов Shape на листе.

getShowDataTypeIcons()

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

getShowGridlines()

Указывает, являются ли линии сетки видимыми для пользователя.

getShowHeadings()

Указывает, являются ли заголовки видимыми для пользователя.

getSlicer(key)

Возвращает срез с использованием его имени или идентификатора. Если срез не существует, этот метод возвращает undefined.

getSlicers()

Возвращает коллекцию срезов, которые являются частью листа.

getStandardHeight()

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

getStandardWidth()

Задает стандартную (по умолчанию) ширину всех столбцов на листе. Одна единица ширины столбца равна ширине одного символа в обычном стиле. Для пропорциональных шрифтов используется ширина символа 0 (ноль).

getTabColor()

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет иметь значение null. Если лист виден, но для цвета вкладки задано значение auto, возвращается пустая строка. В противном случае свойству будет присвоен цвет в форме #RRGGBB (например, FFA500). При настройке цвета используйте пустую строку, чтобы задать "автоматический" цвет или реальный цвет в противном случае.

getTabId()

Возвращает значение, представляющее этот лист, который может быть прочитан с помощью Open Office XML. Это целочисленное значение, которое отличается от worksheet.id (возвращает глобальный уникальный идентификатор) и worksheet.name (которое возвращает такое значение, как "Лист1").

getTable(key)

Получает таблицу по имени или ИД. Если таблица не существует, этот метод возвращает undefined.

getTables()

Коллекция таблиц, имеющихся на листе.

getUsedRange(valuesOnly)

Используемый диапазон — это наименьший диапазон, включающий в себя все ячейки с определенным значением или форматированием. Если весь лист пуст, этот метод возвращает undefined.

getVerticalPageBreaks()

Получает коллекцию вертикальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

getVisibility()

Видимость листа.

getWorksheetCustomProperty(key)

Возвращает объект настраиваемого свойства по ключу, указываемому без учета регистра. Если пользовательское свойство не существует, этот метод возвращает undefined.

refreshAllPivotTables()

Обновляет все сводные таблицы в коллекции.

removeAllHorizontalPageBreaks()

Сбрасывает все добавленные вручную разрывы страниц в коллекции.

removeAllVerticalPageBreaks()

Сбрасывает все добавленные вручную разрывы страниц в коллекции.

replaceAll(text, replacement, criteria)

Находит и заменяет определенную строку на основе условий, указанных в текущем листе.

setEnableCalculation(enableCalculation)

Определяет, следует ли excel пересчитывать лист при необходимости. Значение true, если Excel пересчитывает лист при необходимости. Значение false, если Excel не пересчитывает лист.

setName(name)

Отображаемое имя листа. Имя должно содержать менее 32 символов.

setPosition(position)

Положение листа (начиная с нуля) в книге.

setShowDataTypeIcons(showDataTypeIcons)

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

setShowGridlines(showGridlines)

Указывает, являются ли линии сетки видимыми для пользователя.

setShowHeadings(showHeadings)

Указывает, являются ли заголовки видимыми для пользователя.

setStandardWidth(standardWidth)

Задает стандартную (по умолчанию) ширину всех столбцов на листе. Одна единица ширины столбца равна ширине одного символа в обычном стиле. Для пропорциональных шрифтов используется ширина символа 0 (ноль).

setTabColor(tabColor)

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет иметь значение null. Если лист виден, но для цвета вкладки задано значение auto, возвращается пустая строка. В противном случае свойству будет присвоен цвет в форме #RRGGBB (например, FFA500). При настройке цвета используйте пустую строку, чтобы задать "автоматический" цвет или реальный цвет в противном случае.

setVisibility(visibility)

Видимость листа.

showOutlineLevels(rowLevels, columnLevels)

Показывает группы строк или столбцов по уровням структуры. Структурирует группы и суммирует список данных на листе. Параметры rowLevels и columnLevels указывают, сколько уровней структуры будет отображаться. Допустимый диапазон аргументов находится в диапазоне от 0 до 8. Значение 0 не изменяет текущее отображение. Значение, превышающее текущее количество уровней, отображает все уровни.

Подробнее о методе

activate()

Активация листа в пользовательском интерфейсе Excel.

activate(): void;

Возвращает

void

Примеры

/**
 * This script switches the active view to a worksheet named "Data", if it exists.
 */
function main(workbook: ExcelScript.Workbook) {
  // Check if the "Data" worksheet exists.
  let dataWorksheet = workbook.getWorksheet("Data");
  if (dataWorksheet) {
    // Switch to the "Data" worksheet.
    dataWorksheet.activate();
  } else {
    console.log(`No worksheet named "Data" in this workbook.`);
  }
}

addChart(type, sourceData, seriesBy)

Создает диаграмму.

addChart(
            type: ChartType,
            sourceData: Range,
            seriesBy?: ChartSeriesBy
        ): Chart;

Параметры

type
ExcelScript.ChartType

Представляет тип диаграммы. Дополнительные сведения см. в этой ExcelScript.ChartType статье.

sourceData
ExcelScript.Range

Объект Range , соответствующий исходным данным.

seriesBy
ExcelScript.ChartSeriesBy

Необязательный параметр. Определяет способ использования столбцов или строк в качестве рядов данных на диаграмме. Дополнительные сведения см. в этой ExcelScript.ChartSeriesBy статье.

Возвращает

Примеры

/**
 * This sample creates a column-clustered chart based on the current worksheet's data.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the data range.
  let range = selectedSheet.getUsedRange();

  // Insert a chart using the data on the current worksheet.
  let chart = selectedSheet.addChart(ExcelScript.ChartType.columnClustered, range);

  // Name the chart for easy access in other scripts.
  chart.setName("ColumnChart");
}

addComment(cellAddress, content, contentType)

Создает новое примечание с указанным содержимым в определенной ячейке. Если InvalidArgument указанный диапазон больше одной ячейки, возникает ошибка.

addComment(
            cellAddress: Range | string,
            content: CommentRichContent | string,
            contentType?: ContentType
        ): Comment;

Параметры

cellAddress

ExcelScript.Range | string

Ячейка, в которую добавляется комментарий. Это может быть Range объект или строка. Если это строка, она должна содержать полный адрес, включая имя листа. Если InvalidArgument указанный диапазон больше одной ячейки, возникает ошибка.

content

ExcelScript.CommentRichContent | string

Содержимое комментария. Это может быть строка или CommentRichContent объект. Строки используются для обычного текста. CommentRichContent объекты позволяют использовать другие функции комментариев, такие как упоминания.

contentType
ExcelScript.ContentType

Необязательный параметр. Тип содержимого, содержащегося в комментарии. Значение по умолчанию — перечисление ContentType.Plain.

Возвращает

addGeometricShape(geometricShapeType)

Добавляет геометрическую фигуру на лист. Shape Возвращает объект, представляющий новую фигуру.

addGeometricShape(geometricShapeType: GeometricShapeType): Shape;

Параметры

geometricShapeType
ExcelScript.GeometricShapeType

Представляет тип геометрической фигуры. Дополнительные сведения см. в этой ExcelScript.GeometricShapeType статье.

Возвращает

Примеры

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

addGroup(values)

Группирует подмножество фигур на листе этой коллекции. Shape Возвращает объект , представляющий новую группу фигур.

addGroup(values: Array<string | Shape>): Shape;

Параметры

values

Array<string | ExcelScript.Shape>

Массив идентификаторов фигур или объектов фигур.

Возвращает

addHorizontalPageBreak(pageBreakRange)

Добавляет разрыв страницы перед левой верхней ячейкой указанного диапазона.

addHorizontalPageBreak(pageBreakRange: Range | string): PageBreak;

Параметры

pageBreakRange

ExcelScript.Range | string

Диапазон сразу после добавления разрыва страницы.

Возвращает

addImage(base64ImageString)

Создает изображение из строки в кодировке Base64 и добавляет его на лист. Shape Возвращает объект , представляющий новое изображение.

addImage(base64ImageString: string): Shape;

Параметры

base64ImageString

string

Строка в кодировке Base64, представляющая изображение в формате JPEG или PNG.

Возвращает

Примеры

/**
 * This sample copies an image from a URL. 
 * This could be used to copy photos that a colleague stored in a shared folder to a related workbook.
 */
async function main(workbook: ExcelScript.Workbook) {
  // Fetch the image from a URL.
  const link = "https://raw.githubusercontent.com/OfficeDev/office-scripts-docs/master/docs/images/git-octocat.png";
  const response = await fetch(link);

  // Store the response as an ArrayBuffer, since it is a raw image file.
  const data = await response.arrayBuffer();

  // Convert the image data into a base64-encoded string.
  const image = convertToBase64(data);

  // Add the image to the current worksheet.
  workbook.getActiveWorksheet().addImage(image);
}

/**
 * Converts an ArrayBuffer containing a .png image into a base64-encoded string.
 */
function convertToBase64(input: ArrayBuffer) {
  const uInt8Array = new Uint8Array(input);
  const count = uInt8Array.length;

  // Allocate the necessary space up front.
  const charCodeArray = new Array<string>(count) 
  
  // Convert every entry in the array to a character.
  for (let i = count; i >= 0; i--) { 
    charCodeArray[i] = String.fromCharCode(uInt8Array[i]);
  }

  // Convert the characters to base64.
  const base64 = btoa(charCodeArray.join(''));
  return base64;
}

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Добавляет линию на лист. Shape Возвращает объект , представляющий новую строку.

addLine(
            startLeft: number,
            startTop: number,
            endLeft: number,
            endTop: number,
            connectorType?: ConnectorType
        ): Shape;

Параметры

startLeft

number

Расстояние (в точках) от начала строки до левой части листа.

startTop

number

Расстояние (в точках) от начала строки до верхней части листа.

endLeft

number

Расстояние (в точках) от конца строки слева от листа.

endTop

number

Расстояние (в точках) от конца строки до верхней части листа.

connectorType
ExcelScript.ConnectorType

Представляет тип соединителя. Дополнительные сведения см. в этой ExcelScript.ConnectorType статье.

Возвращает

addNamedItem(name, reference, comment)

Добавляет новое имя в определенную коллекцию.

addNamedItem(
            name: string,
            reference: Range | string,
            comment?: string
        ): NamedItem;

Параметры

name

string

Имя именованного элемента.

reference

ExcelScript.Range | string

Формула или диапазон, на который будет ссылаться имя.

comment

string

Необязательный параметр. Комментарий, связанный с именованным элементом.

Возвращает

addNamedItemFormulaLocal(name, formula, comment)

Добавляет новое имя в определенную коллекцию, используя языковой стандарт пользователя для формулы.

addNamedItemFormulaLocal(
            name: string,
            formula: string,
            comment?: string
        ): NamedItem;

Параметры

name

string

Имя именованного элемента.

formula

string

Формула на языке пользователя, на которую будет ссылаться имя.

comment

string

Необязательный параметр. Комментарий, связанный с именованным элементом.

Возвращает

addNamedSheetView(name)

Создает представление листа с заданным именем.

addNamedSheetView(name: string): NamedSheetView;

Параметры

name

string

Имя создаваемого представления листа. Выдает ошибку, если предоставленное имя уже существует, является пустым или является именем, зарезервированным листом.

Возвращает

addPivotTable(name, source, destination)

Добавьте сводную таблицу на основе указанных исходных данных и вставьте ее в левую верхнюю ячейку целевого диапазона.

addPivotTable(
            name: string,
            source: Range | string | Table,
            destination: Range | string
        ): PivotTable;

Параметры

name

string

Имя новой сводной таблицы.

source

ExcelScript.Range | string | ExcelScript.Table

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

destination

ExcelScript.Range | string

Ячейка в левом верхнем углу диапазона назначения отчета сводной таблицы (диапазон на листе, где будет размещен итоговый отчет).

Возвращает

Примеры

/**
 * This script creates a PivotTable from an existing table and adds it to a new worksheet.
 * This script assumes there is a table in the current worksheet with columns named "Type" and "Sales".
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a PivotTable based on a table in the current worksheet.
  let sheet = workbook.getActiveWorksheet();
  let table = sheet.getTables()[0];

  // Add the PivotTable to a new worksheet.
  let newSheet = workbook.addWorksheet("Pivot");
  let pivotTable = newSheet.addPivotTable("My Pivot", table, "A1");

  // Add fields to the PivotTable to show "Sales" per "Type".
  pivotTable.addRowHierarchy(pivotTable.getHierarchy("Type"));
  pivotTable.addDataHierarchy(pivotTable.getHierarchy("Sales"));

  // Switch to the new worksheet.
  newSheet.activate();
}

addSlicer(slicerSource, sourceField, slicerDestination)

Добавляет новый срез в книгу.

addSlicer(
            slicerSource: string | PivotTable | Table,
            sourceField: string | PivotField | number | TableColumn,
            slicerDestination?: string | Worksheet
        ): Slicer;

Параметры

slicerSource

string | ExcelScript.PivotTable | ExcelScript.Table

Источник данных, на который будет основан новый срез. Это может быть PivotTable объект, Table объект или строка. При передаче объекта сводной таблицы источник данных является источником PivotTable объекта . Table При передаче объекта источником данных является Table объект . При передаче строки она интерпретируется как имя или идентификатор сводной таблицы или таблицы.

sourceField

string | ExcelScript.PivotField | number | ExcelScript.TableColumn

Поле в источнике данных для фильтрации. Это может быть объект, TableColumn объект, идентификатор объекта PivotField или имя или идентификатор объекта TableColumn.PivotField

slicerDestination

string | ExcelScript.Worksheet

Необязательный параметр. Лист, на котором будет создан новый срез. Это может быть Worksheet объект или имя или идентификатор листа. Этот параметр можно опустить, если коллекция срезов извлекается с листа.

Возвращает

Примеры

/**
 * This script adds a slicer for an existing PivotTable on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first PivotTable from the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const pivot = currentSheet.getPivotTables()[0];

  // Create the slicer. 
  // Note that this assumes "Type" is already added as a hierarchy to the PivotTable.
  const slicer = currentSheet.addSlicer(
    pivot, /* The table or PivotTale to be sliced. */
    pivot.getHierarchy("Type").getFields()[0] /* What source field to use as the slicer options. */
  );

  // Select the items to display.
  slicer.selectItems(["Lemon", "Lime"]);

  // Set the left margin of the slicer.
  slicer.setLeft(400);
}

addTable(address, hasHeaders)

Создает таблицу. Объект или исходный адрес диапазона определяет лист, на который будет добавлена таблица. Если добавить таблицу не удается (например, если адрес недействителен или одна таблица будет перекрываться другой), выводится сообщение об ошибке.

addTable(address: Range | string, hasHeaders: boolean): Table;

Параметры

address

ExcelScript.Range | string

Объект Range или строковый адрес или имя диапазона, представляющего источник данных. Если адрес не содержит имя листа, используется текущий активный лист.

hasHeaders

boolean

Логическое значение, указывающее, имеют ли импортируемые данные метки столбцов. Если источник не содержит заголовки (т. е. если для этого свойства задано значение false), Excel автоматически создаст заголовок и сместит данные вниз на одну строку.

Возвращает

Примеры

/**
 * This sample creates a table from the current worksheet's used range, then sorts it based on the first column.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Create a table with the used cells.
  let usedRange = selectedSheet.getUsedRange();
  let newTable = selectedSheet.addTable(usedRange, true);

  // Sort the table using the first column.
  newTable.getSort().apply([{ key: 0, ascending: true }]);
}

addTextBox(text)

Добавляет текстовое поле на лист с указанным текстом в качестве содержимого. Shape Возвращает объект , представляющий новое текстовое поле.

addTextBox(text?: string): Shape;

Параметры

text

string

Представляет текст, который будет отображаться в созданном текстовом поле.

Возвращает

addVerticalPageBreak(pageBreakRange)

Добавляет разрыв страницы перед левой верхней ячейкой указанного диапазона.

addVerticalPageBreak(pageBreakRange: Range | string): PageBreak;

Параметры

pageBreakRange

ExcelScript.Range | string

Диапазон сразу после добавления разрыва страницы.

Возвращает

addWorksheetCustomProperty(key, value)

Добавляет новое пользовательское свойство, которое сопоставляется с предоставленным ключом. При этом существующие настраиваемые свойства перезаписываются этим ключом.

addWorksheetCustomProperty(
            key: string,
            value: string
        ): WorksheetCustomProperty;

Параметры

key

string

Ключ, идентифицирующий объект пользовательского свойства. Он не учитывает регистр. Ключ ограничен 255 символами (большие значения вызовет InvalidArgument ошибку).

value

string

Значение этого настраиваемого свойства.

Возвращает

calculate(markAllDirty)

Вычисляет все ячейки на листе.

calculate(markAllDirty: boolean): void;

Параметры

markAllDirty

boolean

True, чтобы пометить все как грязное.

Возвращает

void

copy(positionType, relativeTo)

Копирует лист и помещает его в указанное положение.

copy(
            positionType?: WorksheetPositionType,
            relativeTo?: Worksheet
        ): Worksheet;

Параметры

positionType
ExcelScript.WorksheetPositionType

Расположение в книге для размещения только что созданного листа. Значение по умолчанию — None, которое вставляет лист в начало листа.

relativeTo
ExcelScript.Worksheet

Существующий лист, определяющий положение только что созданного листа. Это необходимо только в том случае, если positionType имеет значение "До" или "После".

Возвращает

Примеры

/**
 * This script duplicates a worksheet named "Template". 
 * The new worksheet is added after the template.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the worksheet named "Template".
  let template = workbook.getWorksheet("Template");

  // Copy the worksheet.
  let newSheet = template.copy(
    ExcelScript.WorksheetPositionType.after,
    template
  );

  // Name the worksheet using the current date.
  let date = new Date(Date.now());
  newSheet.setName(`${date.toDateString()}`);
}

delete()

Удаляет лист из книги. Обратите внимание, что если для видимости листа задано значение VeryHidden, операция удаления завершится ошибкой InvalidOperation с исключением. Сначала необходимо изменить видимость на скрытую или видимую перед удалением.

delete(): void;

Возвращает

void

Примеры

/**
 * The following scripts removes the first worksheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first worksheet.
  let sheet = workbook.getWorksheets()[0];

  // Remove that worksheet from the workbook.
  sheet.delete();
}

enterTemporaryNamedSheetView()

Создает и активирует новое временное представление листа. Временные представления удаляются при закрытии приложения, выходе из временного представления с помощью метода exit или переключении в другое представление листа. Доступ к временному представлению листа также можно получить с помощью пустой строки (""), если временное представление существует.

enterTemporaryNamedSheetView(): NamedSheetView;

Возвращает

exitActiveNamedSheetView()

Выход из текущего активного представления листа.

exitActiveNamedSheetView(): void;

Возвращает

void

findAll(text, criteria)

Находит все вхождения заданной строки на основе заданных критериев и возвращает их в виде RangeAreas объекта, состоящего из одного или нескольких прямоугольных диапазонов.

findAll(text: string, criteria: WorksheetSearchCriteria): RangeAreas;

Параметры

text

string

Строка для поиска.

criteria
ExcelScript.WorksheetSearchCriteria

Дополнительные критерии поиска, включая то, должен ли поиск соответствовать всей ячейке или учитывать регистр.

Возвращает

Примеры

/**
 * This script searches through a worksheet and finds cells containing "No". 
 * Those cells are filled with the color red.
 * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let worksheet = workbook.getActiveWorksheet();
  let noCells = worksheet.findAll("No", { completeMatch: true });

  // Set the fill color to red.
  noCells.getFormat().getFill().setColor("red");
}

getActiveNamedSheetView()

Возвращает текущее активное представление листа.

getActiveNamedSheetView(): NamedSheetView;

Возвращает

getAutoFilter()

Представляет AutoFilter объект листа.

getAutoFilter(): AutoFilter;

Возвращает

Примеры

/**
 * This script creates an autoFilter on the worksheet that filters out rows based on column values. 
 * The autoFilter filters to only include rows that have a value in column D in the top 10 percentile 
 * (of column D values).
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const dataRange = currentSheet.getUsedRange();

  // Add a filter that will only show the rows with the top 10% of values in column D
  // (index 3, assuming the used range spans from at least A:D).
  currentSheet.getAutoFilter().apply(dataRange, 3, {
    criterion1: "10",
    filterOn: ExcelScript.FilterOn.topPercent
  });
}

getCell(row, column)

Возвращает объект, Range содержащий одну ячейку на основе номеров строк и столбцов. Ячейка может находиться за пределами родительского диапазона, если она находится в сетке листа.

getCell(row: number, column: number): Range;

Параметры

row

number

Номер строки ячейки, которую требуется извлечь. Используется нулевой индекс.

column

number

Номер столбца ячейки, которую требуется извлечь. Используется нулевой индекс.

Возвращает

getChart(name)

Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них. Если диаграмма не существует, этот метод возвращает .undefined

getChart(name: string): Chart | undefined;

Параметры

name

string

Имя получаемой диаграммы.

Возвращает

ExcelScript.Chart | undefined

Примеры

/**
 * This sample moves an existing chart to a specific place on the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();
  
  // Get an existing chart named "ColumnChart".
  let chart = selectedSheet.getChart("ColumnChart");

  // Place the chart over the range "F1:L13".
  chart.setPosition("F1", "L13");
}

getCharts()

Возвращает коллекцию диаграмм, которые являются частью листа.

getCharts(): Chart[];

Возвращает

getComment(commentId)

Получает примечание из коллекции на основе его идентификатора. Если объект comment не существует, этот метод возвращает undefined.

getComment(commentId: string): Comment | undefined;

Параметры

commentId

string

Идентификатор комментария.

Возвращает

ExcelScript.Comment | undefined

getCommentByCell(cellAddress)

Получает примечание из указанной ячейки. Если в ячейке нет комментария, возникает ошибка.

getCommentByCell(cellAddress: Range | string): Comment;

Параметры

cellAddress

ExcelScript.Range | string

Ячейка, в которой находится комментарий. Это может быть Range объект или строка. Если это строка, она должна содержать полный адрес, включая имя листа. Если InvalidArgument указанный диапазон больше одной ячейки, возникает ошибка.

Возвращает

getCommentByReplyId(replyId)

Возвращает комментарий, к которому подключен данный ответ.

getCommentByReplyId(replyId: string): Comment;

Параметры

replyId

string

Идентификатор ответа на комментарий.

Возвращает

getComments()

Возвращает коллекцию всех объектов Comments на листе.

getComments(): Comment[];

Возвращает

getCustomProperties()

Возвращает коллекцию настраиваемых свойств на уровне листа.

getCustomProperties(): WorksheetCustomProperty[];

Возвращает

getEnableCalculation()

Определяет, следует ли excel пересчитывать лист при необходимости. Значение true, если Excel пересчитывает лист при необходимости. Значение false, если Excel не пересчитывает лист.

getEnableCalculation(): boolean;

Возвращает

boolean

getFreezePanes()

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

getFreezePanes(): WorksheetFreezePanes;

Возвращает

getHorizontalPageBreaks()

Получает коллекцию горизонтальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

getHorizontalPageBreaks(): PageBreak[];

Возвращает

getId()

Возвращает значение, однозначно идентифицирующее лист в данной книге. Значение идентификатора остается прежним, даже если переименовать или переместить лист.

getId(): string;

Возвращает

string

getName()

Отображаемое имя листа. Имя должно содержать менее 32 символов.

getName(): string;

Возвращает

string

Примеры

/**
 * This sample gets all the worksheet names in the workbook.
 * It then logs those names to the console.
 */
function main(workbook: ExcelScript.Workbook) {
    // Create an array to hold the worksheet names.
    let worksheetNames = [];

    // Iterate over the worksheet collection in the workbook.
    for (let worksheet of workbook.getWorksheets()) {
        worksheetNames.push(worksheet.getName());
    }

    // Log the array of worksheet names.
    console.log(worksheetNames);
}

getNamedItem(name)

Возвращает объект, NamedItem используя его имя. Если объект не существует, этот метод возвращает undefined.

getNamedItem(name: string): NamedItem | undefined;

Параметры

name

string

Nameitem name.

Возвращает

ExcelScript.NamedItem | undefined

getNamedSheetView(key)

Возвращает представление листа, используя его имя. Если объект представления листа не существует, то этот метод возвращает объект со свойством isNullObjecttrue.

getNamedSheetView(key: string): NamedSheetView | undefined;

Параметры

key

string

Имя представления листа с учетом регистра. Используйте пустую строку (""), чтобы получить временное представление листа, если временное представление существует.

Возвращает

getNamedSheetViews()

Возвращает коллекцию представлений листа, присутствующих на листе.

getNamedSheetViews(): NamedSheetView[];

Возвращает

getNames()

Коллекция имен, относящих к текущему листу.

getNames(): NamedItem[];

Возвращает

getNext(visibleOnly)

Возвращает лист, следующий за этим. Если после этого листа нет, этот метод возвращает undefined.

getNext(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly

boolean

Необязательный параметр. Если trueзначение , учитывает только видимые листы, пропуская все скрытые листы.

Возвращает

getPageLayout()

PageLayout Возвращает объект листа.

getPageLayout(): PageLayout;

Возвращает

Примеры

/**
 * This script sets the printing orientation for the entire workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout = sheet.getPageLayout();

    // Print every page with a landscape orientation.
    pageLayout.setOrientation(ExcelScript.PageOrientation.landscape);
  });
}

getPivotTable(name)

Получает сводную таблицу по имени. Если сводная таблица не существует, этот метод возвращает undefined.

getPivotTable(name: string): PivotTable | undefined;

Параметры

name

string

Имя получаемой сводной таблицы.

Возвращает

getPivotTables()

Коллекция сводных таблиц на листе.

getPivotTables(): PivotTable[];

Возвращает

getPosition()

Положение листа (начиная с нуля) в книге.

getPosition(): number;

Возвращает

number

getPrevious(visibleOnly)

Возвращает лист, предшествующий этому листу. Если предыдущих листов нет, этот метод возвращает undefined.

getPrevious(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly

boolean

Необязательный параметр. Если trueзначение , учитывает только видимые листы, пропуская все скрытые листы.

Возвращает

getProtection()

Возвращает объект защиты листа для листа.

getProtection(): WorksheetProtection;

Возвращает

Примеры

/**
 * This script protects cells from being selected on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the protection settings for the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const sheetProtection = currentSheet.getProtection();

  // Create a new WorksheetProtectionOptions object with the selectionMode property set to `none`.
  let protectionOptions : ExcelScript.WorksheetProtectionOptions = {
    selectionMode: ExcelScript.ProtectionSelectionMode.none
  }

  // Apply the given protection options.
  sheetProtection.protect(protectionOptions);
}

getRange(address)

Range Возвращает объект , представляющий один прямоугольный блок ячеек, заданный адресом или именем.

getRange(address?: string): Range;

Параметры

address

string

Необязательный параметр. Строка, представляющая адрес или имя диапазона. Например, "A1:B2". Если аргумент не указан, возвращается весь диапазон листа. Имеет address ограничение в 8192 символа. Если адрес превышает ограничение символов, этот метод возвращает ошибку InvalidArgument .

Возвращает

Примеры

/**
 * This sample reads the value of A1 and prints it to the console.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the value of cell A1.
  let range = selectedSheet.getRange("A1");
  
  // Print the value of A1.
  console.log(range.getValue());
}

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

Возвращает объект, Range начинающийся с определенного индекса строки и индекса столбца и охватывающий определенное количество строк и столбцов.

getRangeByIndexes(
            startRow: number,
            startColumn: number,
            rowCount: number,
            columnCount: number
        ): Range;

Параметры

startRow

number

Начальная строка (с нулевым индексом).

startColumn

number

Начальный столбец (нулевой индекс).

rowCount

number

Количество строк для включения в диапазон.

columnCount

number

Количество столбцов для включения в диапазон.

Возвращает

getRanges(address)

RangeAreas Возвращает объект , представляющий один или несколько блоков прямоугольных диапазонов, заданных адресом или именем.

getRanges(address?: string): RangeAreas;

Параметры

address

string

Необязательный параметр. Строка, содержащая разделенные запятыми или разделенные точкой с запятой адреса или имена отдельных диапазонов. Например, "A1:B2, A5:B5" или "A1:B2; A5:B5". Если этот параметр не указан, RangeAreas возвращается объект для всего листа.

Возвращает

getShape(key)

Возвращает фигуру, используя ее имя или идентификатор. Если объект shape не существует, этот метод возвращает undefined.

getShape(key: string): Shape | undefined;

Параметры

key

string

Имя или идентификатор извлекаемой фигуры.

Возвращает

ExcelScript.Shape | undefined

getShapes()

Возвращает коллекцию всех объектов Shape на листе.

getShapes(): Shape[];

Возвращает

getShowDataTypeIcons()

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

getShowDataTypeIcons(): boolean;

Возвращает

boolean

getShowGridlines()

Указывает, являются ли линии сетки видимыми для пользователя.

getShowGridlines(): boolean;

Возвращает

boolean

getShowHeadings()

Указывает, являются ли заголовки видимыми для пользователя.

getShowHeadings(): boolean;

Возвращает

boolean

getSlicer(key)

Возвращает срез с использованием его имени или идентификатора. Если срез не существует, этот метод возвращает undefined.

getSlicer(key: string): Slicer | undefined;

Параметры

key

string

Имя или идентификатор извлекаемого среза.

Возвращает

ExcelScript.Slicer | undefined

getSlicers()

Возвращает коллекцию срезов, которые являются частью листа.

getSlicers(): Slicer[];

Возвращает

getStandardHeight()

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

getStandardHeight(): number;

Возвращает

number

getStandardWidth()

Задает стандартную (по умолчанию) ширину всех столбцов на листе. Одна единица ширины столбца равна ширине одного символа в обычном стиле. Для пропорциональных шрифтов используется ширина символа 0 (ноль).

getStandardWidth(): number;

Возвращает

number

getTabColor()

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет иметь значение null. Если лист виден, но для цвета вкладки задано значение auto, возвращается пустая строка. В противном случае свойству будет присвоен цвет в форме #RRGGBB (например, FFA500). При настройке цвета используйте пустую строку, чтобы задать "автоматический" цвет или реальный цвет в противном случае.

getTabColor(): string;

Возвращает

string

getTabId()

Возвращает значение, представляющее этот лист, который может быть прочитан с помощью Open Office XML. Это целочисленное значение, которое отличается от worksheet.id (возвращает глобальный уникальный идентификатор) и worksheet.name (которое возвращает такое значение, как "Лист1").

getTabId(): number;

Возвращает

number

getTable(key)

Получает таблицу по имени или ИД. Если таблица не существует, этот метод возвращает undefined.

getTable(key: string): Table | undefined;

Параметры

key

string

Имя или ИД получаемой таблицы.

Возвращает

ExcelScript.Table | undefined

getTables()

Коллекция таблиц, имеющихся на листе.

getTables(): Table[];

Возвращает

getUsedRange(valuesOnly)

Используемый диапазон — это наименьший диапазон, включающий в себя все ячейки с определенным значением или форматированием. Если весь лист пуст, этот метод возвращает undefined.

getUsedRange(valuesOnly?: boolean): Range;

Параметры

valuesOnly

boolean

Необязательный параметр. Учитывает только ячейки со значениями.

Возвращает

getVerticalPageBreaks()

Получает коллекцию вертикальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

getVerticalPageBreaks(): PageBreak[];

Возвращает

getVisibility()

Видимость листа.

getVisibility(): SheetVisibility;

Возвращает

getWorksheetCustomProperty(key)

Возвращает объект настраиваемого свойства по ключу, указываемому без учета регистра. Если пользовательское свойство не существует, этот метод возвращает undefined.

getWorksheetCustomProperty(
            key: string
        ): WorksheetCustomProperty | undefined;

Параметры

key

string

Ключ, идентифицирующий объект пользовательского свойства. Он не учитывает регистр.

Возвращает

refreshAllPivotTables()

Обновляет все сводные таблицы в коллекции.

refreshAllPivotTables(): void;

Возвращает

void

removeAllHorizontalPageBreaks()

Сбрасывает все добавленные вручную разрывы страниц в коллекции.

removeAllHorizontalPageBreaks(): void;

Возвращает

void

removeAllVerticalPageBreaks()

Сбрасывает все добавленные вручную разрывы страниц в коллекции.

removeAllVerticalPageBreaks(): void;

Возвращает

void

replaceAll(text, replacement, criteria)

Находит и заменяет определенную строку на основе условий, указанных в текущем листе.

replaceAll(
            text: string,
            replacement: string,
            criteria: ReplaceCriteria
        ): number;

Параметры

text

string

Строка для поиска.

replacement

string

Строка, которая заменяет исходную строку.

criteria
ExcelScript.ReplaceCriteria

Дополнительные условия замены.

Возвращает

number

setEnableCalculation(enableCalculation)

Определяет, следует ли excel пересчитывать лист при необходимости. Значение true, если Excel пересчитывает лист при необходимости. Значение false, если Excel не пересчитывает лист.

setEnableCalculation(enableCalculation: boolean): void;

Параметры

enableCalculation

boolean

Возвращает

void

setName(name)

Отображаемое имя листа. Имя должно содержать менее 32 символов.

setName(name: string): void;

Параметры

name

string

Возвращает

void

Примеры

/**
 * This sample renames a worksheet from "Sheet1" to "SALES".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get a worksheet named "Sheet1".
  const sheet = workbook.getWorksheet('Sheet1'); 

  // Set its name to SALES.
  sheet.setName('SALES');
}

setPosition(position)

Положение листа (начиная с нуля) в книге.

setPosition(position: number): void;

Параметры

position

number

Возвращает

void

Примеры

/**
 * This sample sets the worksheet named "SALES" as the first sheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get a worksheet named "SALES".
  const sheet = workbook.getWorksheet('SALES'); 
  // Position the worksheet at the beginning of the workbook.
  sheet.setPosition(0);
}

setShowDataTypeIcons(showDataTypeIcons)

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

setShowDataTypeIcons(showDataTypeIcons: boolean): void;

Параметры

showDataTypeIcons

boolean

Возвращает

void

setShowGridlines(showGridlines)

Указывает, являются ли линии сетки видимыми для пользователя.

setShowGridlines(showGridlines: boolean): void;

Параметры

showGridlines

boolean

Возвращает

void

setShowHeadings(showHeadings)

Указывает, являются ли заголовки видимыми для пользователя.

setShowHeadings(showHeadings: boolean): void;

Параметры

showHeadings

boolean

Возвращает

void

setStandardWidth(standardWidth)

Задает стандартную (по умолчанию) ширину всех столбцов на листе. Одна единица ширины столбца равна ширине одного символа в обычном стиле. Для пропорциональных шрифтов используется ширина символа 0 (ноль).

setStandardWidth(standardWidth: number): void;

Параметры

standardWidth

number

Возвращает

void

setTabColor(tabColor)

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет иметь значение null. Если лист виден, но для цвета вкладки задано значение auto, возвращается пустая строка. В противном случае свойству будет присвоен цвет в форме #RRGGBB (например, FFA500). При настройке цвета используйте пустую строку, чтобы задать "автоматический" цвет или реальный цвет в противном случае.

setTabColor(tabColor: string): void;

Параметры

tabColor

string

Возвращает

void

Примеры

/**
 * This script sets the tab color of every worksheet in the workbook to red.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get all the worksheets in the workbook. 
  let sheets = workbook.getWorksheets();
  
  // Set the tab color of each worksheet to a random color.
  for (let sheet of sheets) {    
    // Set the color of the current worksheet's tab to red.
    sheet.setTabColor("red");
  }
}

setVisibility(visibility)

Видимость листа.

setVisibility(visibility: SheetVisibility): void;

Параметры

Возвращает

void

Примеры

/**
 * This script unhides all the worksheets in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Iterate over each worksheet.
  workbook.getWorksheets().forEach((worksheet) => {
    // Set the worksheet visibility to visible.
    worksheet.setVisibility(ExcelScript.SheetVisibility.visible);
  });
}

showOutlineLevels(rowLevels, columnLevels)

Показывает группы строк или столбцов по уровням структуры. Структурирует группы и суммирует список данных на листе. Параметры rowLevels и columnLevels указывают, сколько уровней структуры будет отображаться. Допустимый диапазон аргументов находится в диапазоне от 0 до 8. Значение 0 не изменяет текущее отображение. Значение, превышающее текущее количество уровней, отображает все уровни.

showOutlineLevels(rowLevels: number, columnLevels: number): void;

Параметры

rowLevels

number

Количество отображаемых уровней строк структуры.

columnLevels

number

Количество уровней столбцов структуры для отображения.

Возвращает

void