ExcelScript.Worksheet interface

Ссылка

Пакет:: ExcelScript

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

Методы

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()	Отображаемое имя листа.
getNamedItem(name)	Возвращает объект, `NamedItem` используя его имя. Если объект не существует, этот метод возвращает `undefined`.
getNamedSheetView(key)	Возвращает представление листа, используя его имя. Если объект представления листа не существует, то этот метод возвращает `undefined`.
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 на листе.
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)
getVerticalPageBreaks()	Получает коллекцию вертикальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.
getVisibility()	Видимость листа.
getWorksheetCustomProperty(key)	Возвращает объект настраиваемого свойства по ключу, указываемому без учета регистра. Если пользовательское свойство не существует, этот метод возвращает `undefined`.
refreshAllPivotTables()	Обновляет все сводные таблицы в коллекции.
removeAllHorizontalPageBreaks()	Сбрасывает все добавленные вручную разрывы страниц в коллекции.
removeAllVerticalPageBreaks()	Сбрасывает все добавленные вручную разрывы страниц в коллекции.
replaceAll(text, replacement, criteria)	Находит и заменяет определенную строку на основе условий, указанных в текущем листе.
setEnableCalculation(enableCalculation)	Определяет, следует ли excel пересчитывать лист при необходимости. Значение true, если Excel пересчитывает лист при необходимости. Значение false, если Excel не пересчитывает лист.
setName(name)	Отображаемое имя листа.
setPosition(position)	Положение листа (начиная с нуля) в книге.
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 статье.

Возвращаемое значение

ExcelScript.Chart

Примеры

/**
 * 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.

Возвращаемое значение

ExcelScript.Comment

addGeometricShape(geometricShapeType)

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

addGeometricShape(geometricShapeType: GeometricShapeType): Shape;

Параметры

geometricShapeType: ExcelScript.GeometricShapeType

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

Возвращаемое значение

ExcelScript.Shape

Примеры

/**
 * 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>

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

Возвращаемое значение

ExcelScript.Shape

addHorizontalPageBreak(pageBreakRange)

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

addHorizontalPageBreak(pageBreakRange: Range | string): PageBreak;

Параметры

pageBreakRange: ExcelScript.Range | string

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

Возвращаемое значение

ExcelScript.PageBreak

addImage(base64ImageString)

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

addImage(base64ImageString: string): Shape;

Параметры

base64ImageString: string

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

Возвращаемое значение

ExcelScript.Shape

Примеры

/**
 * 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 статье.

Возвращаемое значение

ExcelScript.Shape

addNamedItem(name, reference, comment)

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

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

Параметры

name: string

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

reference: ExcelScript.Range | string

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

comment: string

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

Возвращаемое значение

ExcelScript.NamedItem

addNamedItemFormulaLocal(name, formula, comment)

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

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

Параметры

name: string

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

formula: string

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

comment: string

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

Возвращаемое значение

ExcelScript.NamedItem

addNamedSheetView(name)

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

addNamedSheetView(name: string): NamedSheetView;

Параметры

name: string

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

Возвращаемое значение

ExcelScript.NamedSheetView

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

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

Возвращаемое значение

ExcelScript.PivotTable

Примеры

/**
 * 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 объект или имя или идентификатор листа. Этот параметр можно опустить, если коллекция срезов извлекается с листа.

Возвращаемое значение

ExcelScript.Slicer

Примеры

/**
 * 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 автоматически создаст заголовок и сместит данные вниз на одну строку.

Возвращаемое значение

ExcelScript.Table

Примеры

/**
 * 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

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

Возвращаемое значение

ExcelScript.Shape

addVerticalPageBreak(pageBreakRange)

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

addVerticalPageBreak(pageBreakRange: Range | string): PageBreak;

Параметры

pageBreakRange: ExcelScript.Range | string

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

Возвращаемое значение

ExcelScript.PageBreak

addWorksheetCustomProperty(key, value)

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

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

Параметры

key: string

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

value: string

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

Возвращаемое значение

ExcelScript.WorksheetCustomProperty

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 имеет значение "До" или "После".

Возвращаемое значение

ExcelScript.Worksheet

Примеры

/**
 * 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;

Возвращаемое значение

ExcelScript.NamedSheetView

exitActiveNamedSheetView()

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

exitActiveNamedSheetView(): void;

Возвращаемое значение

void

findAll(text, criteria)

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

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

Параметры

text: string

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

criteria: ExcelScript.WorksheetSearchCriteria

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

Возвращаемое значение

ExcelScript.RangeAreas

Примеры

/**
 * This script searches through a worksheet and finds cells containing "No". 
 * Those cells are filled 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;

Возвращаемое значение

ExcelScript.NamedSheetView

getAutoFilter()

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

getAutoFilter(): AutoFilter;

Возвращаемое значение

ExcelScript.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

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

Возвращаемое значение

ExcelScript.Range

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[];

Возвращаемое значение

ExcelScript.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 указанный диапазон больше одной ячейки, возникает ошибка.

Возвращаемое значение

ExcelScript.Comment

getCommentByReplyId(replyId)

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

getCommentByReplyId(replyId: string): Comment;

Параметры

replyId: string

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

Возвращаемое значение

ExcelScript.Comment

getComments()

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

getComments(): Comment[];

Возвращаемое значение

ExcelScript.Comment[]

getCustomProperties()

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

getCustomProperties(): WorksheetCustomProperty[];

Возвращаемое значение

ExcelScript.WorksheetCustomProperty[]

getEnableCalculation()

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

getEnableCalculation(): boolean;

Возвращаемое значение

boolean

getFreezePanes()

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

getFreezePanes(): WorksheetFreezePanes;

Возвращаемое значение

ExcelScript.WorksheetFreezePanes

getHorizontalPageBreaks()

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

getHorizontalPageBreaks(): PageBreak[];

Возвращаемое значение

ExcelScript.PageBreak[]

getId()

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

getId(): string;

Возвращаемое значение

string

getName()

Отображаемое имя листа.

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)

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

getNamedSheetView(key: string): NamedSheetView | undefined;

Параметры

key: string

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

Возвращаемое значение

ExcelScript.NamedSheetView | undefined

getNamedSheetViews()

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

getNamedSheetViews(): NamedSheetView[];

Возвращаемое значение

ExcelScript.NamedSheetView[]

getNames()

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

getNames(): NamedItem[];

Возвращаемое значение

ExcelScript.NamedItem[]

getNext(visibleOnly)

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

getNext(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly: boolean

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

Возвращаемое значение

ExcelScript.Worksheet

getPageLayout()

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

getPageLayout(): PageLayout;

Возвращаемое значение

ExcelScript.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

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

Возвращаемое значение

ExcelScript.PivotTable | undefined

getPivotTables()

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

getPivotTables(): PivotTable[];

Возвращаемое значение

ExcelScript.PivotTable[]

getPosition()

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

getPosition(): number;

Возвращаемое значение

number

getPrevious(visibleOnly)

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

getPrevious(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly: boolean

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

Возвращаемое значение

ExcelScript.Worksheet

getProtection()

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

getProtection(): WorksheetProtection;

Возвращаемое значение

ExcelScript.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". Если аргумент не указан, возвращается весь диапазон листа.

Возвращаемое значение

ExcelScript.Range

Примеры

/**
 * 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

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

Возвращаемое значение

ExcelScript.Range

getRanges(address)

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

getRanges(address?: string): RangeAreas;

Параметры

address: string

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

Возвращаемое значение

ExcelScript.RangeAreas

getShape(key)

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

getShape(key: string): Shape | undefined;

Параметры

key: string

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

Возвращаемое значение

ExcelScript.Shape | undefined

getShapes()

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

getShapes(): Shape[];

Возвращаемое значение

ExcelScript.Shape[]

getShowGridlines()

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

getShowGridlines(): boolean;

Возвращаемое значение

boolean

getShowHeadings()

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

getShowHeadings(): boolean;

Возвращаемое значение

boolean

getSlicer(key)

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

getSlicer(key: string): Slicer | undefined;

Параметры

key: string

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

Возвращаемое значение

ExcelScript.Slicer | undefined

getSlicers()

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

getSlicers(): Slicer[];

Возвращаемое значение

ExcelScript.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[];

Возвращаемое значение

ExcelScript.Table[]

getUsedRange(valuesOnly)

getUsedRange(valuesOnly?: boolean): Range;

Параметры

valuesOnly: boolean

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

Возвращаемое значение

ExcelScript.Range

getVerticalPageBreaks()

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

getVerticalPageBreaks(): PageBreak[];

Возвращаемое значение

ExcelScript.PageBreak[]

getVisibility()

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

getVisibility(): SheetVisibility;

Возвращаемое значение

ExcelScript.SheetVisibility

getWorksheetCustomProperty(key)

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

getWorksheetCustomProperty(
            key: string
        ): WorksheetCustomProperty | undefined;

Параметры

key: string

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

Возвращаемое значение

ExcelScript.WorksheetCustomProperty | undefined

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)

setEnableCalculation(enableCalculation: boolean): void;

Параметры

enableCalculation: boolean

Возвращаемое значение

void

setName(name)

Отображаемое имя листа.

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);
}

setShowGridlines(showGridlines)

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

setShowGridlines(showGridlines: boolean): void;

Параметры

showGridlines: boolean

Возвращаемое значение

void

setShowHeadings(showHeadings)

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

setShowHeadings(showHeadings: boolean): void;

Параметры

showHeadings: boolean

Возвращаемое значение

void

setStandardWidth(standardWidth)

setStandardWidth(standardWidth: number): void;

Параметры

standardWidth: number

Возвращаемое значение

void

setTabColor(tabColor)

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;

Параметры

visibility: ExcelScript.SheetVisibility

Возвращаемое значение

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

ExcelScript.Worksheet interface

Комментарии

Примеры

Методы

Сведения о методе

activate()

Возвращаемое значение

Примеры

addChart(type, sourceData, seriesBy)

Параметры

Возвращаемое значение

Примеры

addComment(cellAddress, content, contentType)

Параметры

Возвращаемое значение

addGeometricShape(geometricShapeType)

Параметры

Возвращаемое значение

Примеры

addGroup(values)

Параметры

Возвращаемое значение

addHorizontalPageBreak(pageBreakRange)

Параметры

Возвращаемое значение

addImage(base64ImageString)

Параметры

Возвращаемое значение

Примеры

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

Параметры

Возвращаемое значение

addNamedItem(name, reference, comment)

Параметры

Возвращаемое значение

addNamedItemFormulaLocal(name, formula, comment)

Параметры

Возвращаемое значение

addNamedSheetView(name)

Параметры

Возвращаемое значение

addPivotTable(name, source, destination)

Параметры

Возвращаемое значение

Примеры

addSlicer(slicerSource, sourceField, slicerDestination)

Параметры

Возвращаемое значение

Примеры

addTable(address, hasHeaders)

Параметры

Возвращаемое значение

Примеры

addTextBox(text)

Параметры

Возвращаемое значение

addVerticalPageBreak(pageBreakRange)

Параметры

Возвращаемое значение

addWorksheetCustomProperty(key, value)

Параметры

Возвращаемое значение

calculate(markAllDirty)

Параметры

Возвращаемое значение

copy(positionType, relativeTo)

Параметры

Возвращаемое значение

Примеры

delete()

Возвращаемое значение

Примеры

enterTemporaryNamedSheetView()

Возвращаемое значение

exitActiveNamedSheetView()

Возвращаемое значение

findAll(text, criteria)

Параметры

Возвращаемое значение

Примеры