Включить javascript в excel

Обзор API JavaScript для Excel

Надстройка Excel взаимодействует с объектами в Excel с помощью API JavaScript для Office, включающего две объектных модели JavaScript:

API JavaScript для Excel. Это API-интерфейсы для определенных приложений в Excel. Появившийся в Office 2016 API JavaScript для Excel предоставляет строго типизированные объекты, с помощью которых можно получать доступ к листам, диапазонам, таблицам, диаграммам и другим объектам.

Общие API. Появившиеся в Office 2013 общие API можно использовать для доступа к таким компонентам, как пользовательский интерфейс, диалоговые окна и параметры клиентов, общие для нескольких типов приложений Office.

В этом разделе рассматривается API JavaScript для Excel, используемый для разработки большинства функций в надстройках и предназначенный для Excel в Интернете, Excel 2016 или более поздних версий. Сведения об общем API см. в статье Общая объектная модель API JavaScript.

Сведения о концепциях объектной модели

Сведения о важных понятиях объектной модели см. в статье Объектная модель JavaScript для Excel в надстройках Office.

Чтобы получить практический опыт доступа к объектам в Excel с помощью API JavaScript для Excel, выполните инструкции из руководства по надстройкам Excel.

Сведения о возможностях API

Каждой основной функции API Excel посвящена статья или набор статей с описанием ее возможностей и соответствующей объектной модели.

Дополнительные сведения об объектной модели API JavaScript для Excel см. в справочной документации по API JavaScript для Excel.

Опробуйте примеры кода в Script Lab

Используйте Script Lab, чтобы быстро начать работу с коллекцией встроенных примеров, демонстрирующих выполнение задач с помощью API. Вы можете выполнять примеры в Script Lab, чтобы сразу увидеть результат в области задач или листе, изучать примеры, чтобы понять принципы действия API, и даже использовать примеры для создания собственных надстроек.

Источник

Объектная модель JavaScript для Excel в надстройках Office

В этой статье описано, как создавать надстройки для Excel 2016 или более поздней версии с помощью API JavaScript для Excel. В статье изложены основные принципы, которые являются фундаментальными при использовании этого API, а также имеются рекомендации по выполнению определенных задач, например чтению данных из большого диапазона или записи данных в него, изменения всех ячеек в диапазоне и много другого.

Сведения об асинхронном типе интерфейсов API Excel и принципах их работы с книгой см. в статье Использование модели API, зависящей от приложения.

Интерфейсы API Office.js для Excel

Надстройка Excel взаимодействует с объектами в Excel с помощью API JavaScript для Office, включающего две объектных модели JavaScript:

API JavaScript для Excel. Появившийся в Office 2016 API JavaScript для Excel предоставляет строго типизированные объекты, с помощью которых можно получать доступ к листам, диапазонам, таблицам, диаграммам и другим объектам.

Общие API. Появившиеся в Office 2013 общие API можно использовать для доступа к таким компонентам, как пользовательский интерфейс, диалоговые окна и параметры клиентов, общие для нескольких типов приложений Office.

Скорее всего, вы будете разрабатывать большую часть функций надстроек для Excel 2016 или более поздней версии с помощью API JavaScript для Excel, но вам также потребуются объекты из общего API. Например:

• Context. объект Context представляет среду выполнения надстройки и предоставляет доступ к ключевым объектам API. Он состоит из данных конфигурации книги, например contentLanguage и officeTheme , а также предоставляет сведения о среде выполнения надстройки, например host и platform . Кроме того, он предоставляет метод requirements.isSetSupported() , с помощью которого можно проверить, поддерживается ли указанный набор обязательных элементов приложением Excel, в котором работает надстройка.
• Document. Объект Document предоставляет метод getFileAsync() , позволяющий скачать файл Excel, в котором работает надстройка.

На рисунке ниже показано, когда можно использовать API JavaScript для Excel или общие API.

Объектная модель для Excel

Чтобы понять API-интерфейсы Excel, вы должны понимать, как компоненты рабочей книги связаны друг с другом.

• Рабочая книга содержит одну или несколько рабочих листов.
• Рабочий лист содержит коллекции тех объектов данных, которые присутствуют на отдельном листе, и предоставляет доступ к ячейкам с помощью объектов Range.
• Range представляет группу смежных клеток.
• Диапазоны используются для создания и размещения таблиц, диаграмм, фигур и других объектов визуализации данных или организации.
• Рабочие книги содержат коллекции некоторых из этих объектов данных (таких как таблицы) для всей рабочей книги.

В API JavaScript для Excel нет объекта или класса Cell. Вместо этого API JavaScript для Excel определяет все ячейки Excel как объекты Range . Отдельные ячейки в пользовательском интерфейсе Excel преобразуются в объект Range с одной ячейкой в API JavaScript для Excel. Один объект Range также может содержать несколько смежных ячеек. Дополнительные сведения см. в статье Работа с ячейками с использованием API JavaScript для Excel.

Диапазоны

Диапазон — это группа непрерывных ячеек в рабочей книге. В надстройках обычно используется нотация в стиле A1 (например, B3 для отдельной ячейки в столбце B и строке 3 или C2:F4 для ячеек из столбцов с C по F и строк с 2 по 4) для определения диапазонов.

Диапазоны имеют три основных свойства: values , formulas , и format . Эти свойства получают или устанавливают значения ячеек, формулы для оценки и визуальное форматирование ячеек.

Образец диапазона

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

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

Диаграммы, таблицы и другие объекты данных

API JavaScript для Excel могут создавать и управлять структурами данных и визуализациями в Excel. Таблицы и диаграммы являются двумя наиболее часто используемыми объектами, но API поддерживают сводные таблицы, фигуры, изображения и многое другое.

Создание таблицы

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

В следующем примере создается таблица с использованием диапазонов из предыдущего примера.

Использование этого примера кода на листе с предыдущими данными создает следующую таблицу.

Создание диаграммы

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

В следующем примере создается простая гистограмма для трех элементов, которая размещается на 100 пикселей ниже верхней части листа.

Выполнение этого примера на листе с предыдущей таблицей создает следующую диаграмму.

Источник

Work with worksheets using the Excel JavaScript API

This article provides code samples that show how to perform common tasks with worksheets using the Excel JavaScript API. For the complete list of properties and methods that the Worksheet and WorksheetCollection objects support, see Worksheet Object (JavaScript API for Excel) and WorksheetCollection Object (JavaScript API for Excel).

The information in this article applies only to regular worksheets; it does not apply to «chart» sheets or «macro» sheets.

Get worksheets

The following code sample gets the collection of worksheets, loads the name property of each worksheet, and writes a message to the console.

The id property of a worksheet uniquely identifies the worksheet in a given workbook and its value will remain the same even when the worksheet is renamed or moved. When a worksheet is deleted from a workbook in Excel on Mac, the id of the deleted worksheet may be reassigned to a new worksheet that is subsequently created.

Get the active worksheet

The following code sample gets the active worksheet, loads its name property, and writes a message to the console.

Set the active worksheet

The following code sample sets the active worksheet to the worksheet named Sample, loads its name property, and writes a message to the console. If there is no worksheet with that name, the activate() method throws an ItemNotFound error.

Reference worksheets by relative position

These examples show how to reference a worksheet by its relative position.

Get the first worksheet

The following code sample gets the first worksheet in the workbook, loads its name property, and writes a message to the console.

Get the last worksheet

The following code sample gets the last worksheet in the workbook, loads its name property, and writes a message to the console.

Get the next worksheet

The following code sample gets the worksheet that follows the active worksheet in the workbook, loads its name property, and writes a message to the console. If there is no worksheet after the active worksheet, the getNext() method throws an ItemNotFound error.

Get the previous worksheet

The following code sample gets the worksheet that precedes the active worksheet in the workbook, loads its name property, and writes a message to the console. If there is no worksheet before the active worksheet, the getPrevious() method throws an ItemNotFound error.

Add a worksheet

The following code sample adds a new worksheet named Sample to the workbook, loads its name and position properties, and writes a message to the console. The new worksheet is added after all existing worksheets.

Copy an existing worksheet

Worksheet.copy adds a new worksheet that is a copy of an existing worksheet. The new worksheet’s name will have a number appended to the end, in a manner consistent with copying a worksheet through the Excel UI (for example, MySheet (2)). Worksheet.copy can take two parameters, both of which are optional:

• positionType — A WorksheetPositionType enum specifying where in the workbook the new worksheet is to be added.
• relativeTo — If the positionType is Before or After , you need to specify a worksheet relative to which the new sheet is to be added (this parameter answers the question «Before or after what?»).

The following code sample copies the current worksheet and inserts the new sheet directly after the current worksheet.

Delete a worksheet

The following code sample deletes the final worksheet in the workbook (as long as it’s not the only sheet in the workbook) and writes a message to the console.

A worksheet with a visibility of «Very Hidden» cannot be deleted with the delete method. If you wish to delete the worksheet anyway, you must first change the visibility.

Rename a worksheet

The following code sample changes the name of the active worksheet to New Name.

Move a worksheet

The following code sample moves a worksheet from the last position in the workbook to the first position in the workbook.

Set worksheet visibility

These examples show how to set the visibility of a worksheet.

Hide a worksheet

The following code sample sets the visibility of worksheet named Sample to hidden, loads its name property, and writes a message to the console.

Unhide a worksheet

The following code sample sets the visibility of worksheet named Sample to visible, loads its name property, and writes a message to the console.

Get a single cell within a worksheet

The following code sample gets the cell that is located in row 2, column 5 of the worksheet named Sample, loads its address and values properties, and writes a message to the console. The values that are passed into the getCell(row: number, column:number) method are the zero-indexed row number and column number for the cell that is being retrieved.

Detect data changes

Your add-in may need to react to users changing the data in a worksheet. To detect these changes, you can register an event handler for the onChanged event of a worksheet. Event handlers for the onChanged event receive a WorksheetChangedEventArgs object when the event fires.

The WorksheetChangedEventArgs object provides information about the changes and the source. Since onChanged fires when either the format or value of the data changes, it can be useful to have your add-in check if the values have actually changed. The details property encapsulates this information as a ChangedEventDetail. The following code sample shows how to display the before and after values and types of a cell that has been changed.

Detect formula changes

Your add-in can track changes to formulas in a worksheet. This is useful when a worksheet is connected to an external database. When the formula changes in the worksheet, the event in this scenario triggers corresponding updates in the external database.

To detect changes to formulas, register an event handler for the onFormulaChanged event of a worksheet. Event handlers for the onFormulaChanged event receive a WorksheetFormulaChangedEventArgs object when the event fires.

The onFormulaChanged event detects when a formula itself changes, not the data value resulting from the formula’s calculation.

The following code sample shows how to register the onFormulaChanged event handler, use the WorksheetFormulaChangedEventArgs object to retrieve the formulaDetails array of the changed formula, and then print out details about the changed formula with the FormulaChangedEventDetail properties.

This code sample only works when a single formula is changed.

Handle sorting events

The onColumnSorted and onRowSorted events indicate when any worksheet data is sorted. These events are connected to individual Worksheet objects and to the workbook’s WorkbookCollection . They fire whether the sorting is done programmatically or manually through the Excel user interface.

onColumnSorted fires when columns are sorted as the result of a left-to-right sort operation. onRowSorted fires when rows are sorted as the result of a top-to-bottom sort operation. Sorting a table using the drop-down menu on a column header results in an onRowSorted event. The event corresponds with what is moving, not what is being considered as the sorting criteria.

The onColumnSorted and onRowSorted events provide their callbacks with WorksheetColumnSortedEventArgs or WorksheetRowSortedEventArgs, respectively. These give more details about the event. In particular, both EventArgs have an address property that represents the rows or columns moved as a result of the sort operation. Any cell with sorted content is included, even if that cell’s value was not part of the sorting criteria.

The following images show the ranges returned by the address property for sort events. First, here is the sample data before sorting:

If a top-to-bottom sort is performed on «Q1» (the values in «B«), the following highlighted rows are returned by WorksheetRowSortedEventArgs.address .

If a left-to-right sort is performed on «Quinces» (the values in «4«) on the original data, the following highlighted columns are returned by WorksheetColumnsSortedEventArgs.address .

The following code sample shows how to register an event handler for the Worksheet.onRowSorted event. The handler’s callback clears the fill color for the range, then fills the cells of the moved rows.

Find all cells with matching text

The Worksheet object has a findAll method to search for a specified string within the worksheet. It returns a RangeAreas object, which is a collection of Range objects that can be edited all at once.

The following code sample finds all cells with values equal to the string Complete and colors them green. Note that findAll throws an ItemNotFound error if the specified string doesn’t exist in the worksheet. If you’re uncertain whether the specified string exists in the worksheet, use the findAllOrNullObject method to gracefully handle that scenario.

This section describes how to find cells and ranges using the Worksheet object’s methods. More range retrieval information can be found in object-specific articles.

• For examples that show how to get a range within a worksheet using the Range object, see Get a range using the Excel JavaScript API.
• For examples that show how to get ranges from a Table object, see Work with tables using the Excel JavaScript API.
• For examples that show how to search a large range for multiple sub-ranges based on cell characteristics, see Work with multiple ranges simultaneously in Excel add-ins.

Filter data

An AutoFilter applies data filters across a range within the worksheet. This is created with Worksheet.autoFilter.apply , which has the following parameters.

• range : The range to which the filter is applied, specified as either a Range object or a string.
• columnIndex : The zero-based column index against which the filter criteria is evaluated.
• criteria : A FilterCriteria object determining which rows should be filtered based on the column’s cell.

The first code sample shows how to add a filter to the worksheet’s used range. This filter will hide entries that are not in the top 25%, based on the values in column 3.

The next code sample shows how to refresh the auto-filter using the reapply method. This should be done when the data in the range changes.

The following code sample shows how to use the clearColumnCriteria method to clear the auto-filter from only one column, while leaving the filter active on other columns.

The final auto-filter code sample shows how to remove the auto-filter from the worksheet with the remove method.

An AutoFilter can also be applied to individual tables. See Work with tables using the Excel JavaScript API for more information.

Data protection

Your add-in can control a user’s ability to edit data in a worksheet. The worksheet’s protection property is a WorksheetProtection object with a protect() method. The following example shows a basic scenario toggling the complete protection of the active worksheet.

The protect method has two optional parameters:

• options : A WorksheetProtectionOptions object defining specific editing restrictions.
• password : A string representing the password needed for a user to bypass protection and edit the worksheet.

The article Protect a worksheet has more information about worksheet protection and how to change it through the Excel UI.

Detect changes to the worksheet protection state

The protection state of a worksheet can be changed by an add-in or through the Excel UI. To detect changes to the protection state, register an event handler for the onProtectionChanged event of a worksheet. Event handlers for the onProtectionChanged event receive a WorksheetProtectionChangedEventArgs object when the event fires.

The following code sample shows how to register the onProtectionChanged event handler and use the WorksheetProtectionChangedEventArgs object to retrieve the isProtected , worksheetId , and source properties of the event.

Page layout and print settings

Add-ins have access to page layout settings at a worksheet level. These control how the sheet is printed. A Worksheet object has three layout-related properties: horizontalPageBreaks , verticalPageBreaks , pageLayout .

Worksheet.horizontalPageBreaks and Worksheet.verticalPageBreaks are PageBreakCollections. These are collections of PageBreaks, which specify ranges where manual page breaks are inserted. The following code sample adds a horizontal page break above row 21.

Worksheet.pageLayout is a PageLayout object. This object contains layout and print settings that are not dependent any printer-specific implementation. These settings include margins, orientation, page numbering, title rows, and print area.

The following code sample centers the page (both vertically and horizontally), sets a title row that will be printed at the top of every page, and sets the printed area to a subsection of the worksheet.

Источник

• #3