Работа с таблицами с использованием API JavaScript для Excel

В этой статье приведены примеры кода, в которых показано, как выполнять стандартные задачи для таблиц с использованием API JavaScript для Excel. Полный список свойств и методов, поддерживаемых объектами и объектами, см. в таблице Object (API JavaScript для Excel) и TableCollection Object (API JavaScript для Excel). Table TableCollection

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

В примере кода ниже показано, как создать таблицу на листе Sample (Пример). В таблице имеются заголовки, а также четыре столбца и семь строк с данными. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.

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

Добавление строк в таблицу

В примере ниже показано, как добавить семь новых строк в таблицу ExpensesTable (Таблица расходов) на листе Sample (Пример). Новые строки будут добавлены в конец таблицы. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.

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

Добавление столбца в таблицу

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

Свойство index объекта TableColumn указывает номер индекса столбца в коллекции столбцов таблицы. Свойство id объекта TableColumn содержит уникальный ключ, идентифицирующий столбец.

В примере кода ниже показано, как добавить новый столбец в таблицу ExpensesTable (Таблица расходов) на листе Sample (Пример). Новый столбец будет добавлен после всех существующих столбцов в таблице. Он будет содержать заголовок Day of the Week (День недели), а также данные для заполнения ячеек в столбце. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.

В примере кода ниже показано, как добавить новый столбец в таблицу ExpensesTable (Таблица расходов) на листе Sample (Пример). Новый столбец будет добавлен в конец таблицы, будет содержать заголовок Type of the Day (Тип дня), и в нем будет использована формула для заполнения каждой ячейки столбца. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.

Resize a table

Надстройка может изменять объем таблицы без добавления данных в таблицу или изменения значений ячейки. Чтобы повторно использовать таблицу, используйте метод Table.resize . В следующем примере кода показано, как сделать таблицу повторной. В этом примере кода используется раздел ExpensesTable из раздела Create a table earlier in this article and sets the new range of the table to A1:D20.

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

Изменение имени столбца

В примере кода ниже показано, как изменить имя первого столбца в таблице на Purchase date. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.

Получение данных из таблицы

В примере кода ниже показано, как считать данные из таблицы ExpensesTable (Таблица расходов), размещенной на листе Sample (Пример), а затем отобразить эти данные под таблицей на том же листе.

Обнаружение изменений данных

Возможно, надстройке потребуется реагировать на изменения пользователями данных в таблице. Чтобы обнаружить эти изменения, можно зарегистрировать обработчик событий для события onChanged таблицы. Обработчики события onChanged получают объект TableChangedEventArgs при возникновении события.

Объект TableChangedEventArgs предоставляет сведения об изменениях и источнике. Так как событие onChanged возникает при изменении формата или значения данных, может быть полезно, чтобы надстройка проверяла, действительно ли значения изменились. Свойство details объединяет эти сведения в виде интерфейса ChangedEventDetail. В следующем примере кода показано, как отобразить значения и типы измененной ячейки до и после изменения.

Сортировка данных в таблице

В примере кода ниже показано, как отсортировать данные по убыванию в четвертом столбце таблицы.

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

Применение фильтров к таблице

В примере кода ниже показано, как применить фильтры для столбцов Amount (Сумма) и Category (Категория) в таблице. В результате применения фильтров будут отображены только те строки, у которых в столбце Category (Категория) содержится одно из указанных значений, а значения в столбце Amount (Сумма) меньше среднего значения для всех строк.

Удаление фильтров в таблице

В примере кода ниже показано, как удалить все фильтры, примененные к таблице.

Получение отображаемого диапазона из отфильтрованной таблицы

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

Автофильтр

Надстройка может использовать объект AutoFilter таблицы для фильтрации данных. Объект AutoFilter является целой структурой фильтра таблицы или диапазона. Все операции фильтрации, описанные выше в этой статье, совместимы с автофильтром. Единая точка доступа упрощает доступ к нескольким фильтрам и управление ими.

В следующем примере кода показана такая же фильтрация данных, как в примере кода выше, но выполненная полностью с помощью автофильтра.

Объект AutoFilter можно также применять к диапазону на уровне листа. Дополнительные сведения см. в статье Работа с листами с использованием API JavaScript для Excel.

Форматирование таблицы

В примере кода ниже показано, как применить форматирование к таблице. В примере показано, как указать различные цвета заливки для строки заголовков, основной части, второй строки и первого столбца таблицы. Сведения о свойствах, которые вы можете использовать для задания формата, см. в статье Объект RangeFormat (API JavaScript для Excel).

Преобразование диапазона в таблицу

В примере кода ниже показано, как создать диапазон данных и преобразовывать его в таблицу.

Импорт данных JSON в таблицу

В примере кода ниже показано, как создать таблицу на листе Sample (Пример), а затем заполнить ее с помощью объекта JSON, который определяет две строки данных. Если Excel, в котором работает код, поддерживает набор требований ExcelApi 1.2, ширина столбцов и высота строк лучше всего соответствуют текущим данным в таблице.