Excel.Table class

Пакет:

excel

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

Extends

OfficeExtension.ClientObject

Комментарии

[ Набор API: ExcelApi 1.1 ]

Свойства

autoFilter	Представляет AutoFilter объект таблицы.
columns	Представляет коллекцию всех столбцов в таблице.
context	Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
highlightFirstColumn	Указывает, содержит ли первый столбец специальное форматирование.
highlightLastColumn	Указывает, содержит ли последний столбец специальное форматирование.
id	Возвращает значение, однозначно идентифицирующее таблицу в данной книге. Значение идентификатора остается прежним, даже если переименовать таблицу.
legacyId	Возвращает числовой идентификатор.
name	Имя таблицы. Заданное имя таблицы должно соответствовать рекомендациям, указанным в статье Переименование таблицы Excel .
rows	Представляет коллекцию всех строк в таблице.
showBandedColumns	Указывает, отображаются ли столбцы в виде чередующегося форматирования, в котором нечетные столбцы выделены иначе, чем четные, чтобы упростить чтение таблицы.
showBandedRows	Указывает, отображаются ли строки с чередованием, в котором нечетные строки выделены иначе, чем четные, чтобы упростить чтение таблицы.
showFilterButton	Указывает, отображаются ли кнопки фильтра в верхней части заголовка каждого столбца. Это свойство можно использовать, только если таблица содержит строку заголовков.
showHeaders	Указывает, отображается ли строка заголовка. Можно задать это значение, чтобы отобразить или скрыть строку заголовков.
showTotals	Указывает, отображается ли итоговая строка. Можно задать это значение, чтобы отобразить или скрыть строку итогов.
sort	Представляет сортировку для таблицы.
style	Значение константы, представляющее стиль таблицы. Возможные значения: "TableStyleLight1" – "TableStyleLight21", "TableStyleMedium1" – "TableStyleMedium28", "TableStyleDark1" – "TableStyleDark11". Также можно указать настраиваемый пользовательский стиль, имеющийся в книге.
tableStyle	Стиль, применяемый к таблице.
worksheet	Лист, содержащий текущую таблицу.

Методы

clearFilters()	Удаляет все фильтры, примененные к таблице.
clearStyle()	Изменяет таблицу для использования стиля таблицы по умолчанию.
convertToRange()	Преобразовывает таблицу в обычный диапазон ячеек. Все данные сохраняются.
delete()	Удаляет таблицу.
getDataBodyRange()	Получает объект диапазона, связанный с основными данными таблицы.
getHeaderRowRange()	Получает объект диапазона, связанный со строкой заголовка таблицы.
getRange()	Получает объект диапазона, связанный со всей таблицей.
getTotalRowRange()	Получает объект диапазона, связанный со строкой итогов таблицы.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
reapplyFilters()	Повторно применяет все текущие фильтры к таблице.
resize(newRange)	Измените размер таблицы до нового диапазона. Новый диапазон должен перекрываться с исходным диапазоном таблицы, а заголовки (или верхняя часть таблицы) должны находиться в одной строке.
set(properties, options)	Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)	Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
setStyle(style)	Задает стиль, применяемый к таблице.
toJSON()	Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.Table объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.TableData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

События

onChanged	Происходит при изменении данных в ячейках в определенной таблице.
onFiltered	Происходит при применении фильтра к определенной таблице.
onSelectionChanged	Происходит при изменении выделения в определенной таблице.

Сведения о свойстве

autoFilter

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

readonly autoFilter: Excel.AutoFilter;

Значение свойства

Excel.AutoFilter

Комментарии

[ Набор API: ExcelApi 1.9 ]

columns

Представляет коллекцию всех столбцов в таблице.

readonly columns: Excel.TableColumnCollection;

Значение свойства

Excel.TableColumnCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

highlightFirstColumn

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

highlightFirstColumn: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.3 ]

highlightLastColumn

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

highlightLastColumn: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.3 ]

id

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

readonly id: string;

Значение свойства

string

Комментарии

[ Набор API: ExcelApi 1.1 ]

legacyId

Возвращает числовой идентификатор.

readonly legacyId: string;

Значение свойства

string

Комментарии

[ Набор API: ExcelApi 1.8 ]

name

Имя таблицы.

Заданное имя таблицы должно соответствовать рекомендациям, указанным в статье Переименование таблицы Excel .

name: string;

Значение свойства

string

Комментарии

[ Набор API: ExcelApi 1.1 ]

rows

Представляет коллекцию всех строк в таблице.

readonly rows: Excel.TableRowCollection;

Значение свойства

Excel.TableRowCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

showBandedColumns

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

showBandedColumns: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.3 ]

showBandedRows

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

showBandedRows: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.3 ]

showFilterButton

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

showFilterButton: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.3 ]

showHeaders

Указывает, отображается ли строка заголовка. Можно задать это значение, чтобы отобразить или скрыть строку заголовков.

showHeaders: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.1 ]

showTotals

Указывает, отображается ли итоговая строка. Можно задать это значение, чтобы отобразить или скрыть строку итогов.

showTotals: boolean;

Значение свойства

boolean

Комментарии

[ Набор API: ExcelApi 1.1 ]

sort

Представляет сортировку для таблицы.

readonly sort: Excel.TableSort;

Значение свойства

Excel.TableSort

Комментарии

[ Набор API: ExcelApi 1.2 ]

style

Значение константы, представляющее стиль таблицы. Возможные значения: "TableStyleLight1" – "TableStyleLight21", "TableStyleMedium1" – "TableStyleMedium28", "TableStyleDark1" – "TableStyleDark11". Также можно указать настраиваемый пользовательский стиль, имеющийся в книге.

style: string;

Значение свойства

string

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

// Set table style.
await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    table.name = 'Table1-Renamed';
    table.showTotals = false;
    table.style = 'TableStyleMedium2';
    table.load('tableStyle');
    await context.sync();
    
    console.log(table.style);
});

tableStyle

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Стиль, применяемый к таблице.

readonly tableStyle: Excel.TableStyle;

Значение свойства

Excel.TableStyle

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

worksheet

Лист, содержащий текущую таблицу.

readonly worksheet: Excel.Worksheet;

Значение свойства

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.2 ]

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

clearFilters()

Удаляет все фильтры, примененные к таблице.

clearFilters(): void;

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

void

Комментарии

[ Набор API: ExcelApi 1.2 ]

clearStyle()

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

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

clearStyle(): void;

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

void

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

convertToRange()

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

convertToRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.2 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    table.convertToRange();
    await context.sync(); 
});

delete()

Удаляет таблицу.

delete(): void;

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

void

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    table.delete();
    await context.sync(); 
});

getDataBodyRange()

Получает объект диапазона, связанный с основными данными таблицы.

getDataBodyRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    const tableDataRange = table.getDataBodyRange();
    tableDataRange.load('address')
    await context.sync();
    
    console.log(tableDataRange.address);
});

getHeaderRowRange()

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

getHeaderRowRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    const tableHeaderRange = table.getHeaderRowRange();
    tableHeaderRange.load('address');
    await context.sync();

    console.log(tableHeaderRange.address);
});

getRange()

Получает объект диапазона, связанный со всей таблицей.

getRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    const tableRange = table.getRange();
    tableRange.load('address');    
    await context.sync();
    
    console.log(tableRange.address);
});

getTotalRowRange()

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

getTotalRowRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    const tableTotalsRange = table.getTotalRowRange();
    tableTotalsRange.load('address');    
    await context.sync();
    
    console.log(tableTotalsRange.address);
});

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(options?: Excel.Interfaces.TableLoadOptions): Excel.Table;

Параметры

options

Excel.Interfaces.TableLoadOptions

Предоставляет параметры свойств объекта для загрузки.

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

Excel.Table

load(propertyNames)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNames?: string | string[]): Excel.Table;

Параметры

propertyNames

string | string[]

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

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

Excel.Table

Примеры

// Get a table by name.
await Excel.run(async (context) => { 
    const tableName = 'Table1';
    const table = context.workbook.tables.getItem(tableName);
    table.load('id')
    await context.sync();
    
    console.log(table.id);
});

load(propertyNamesAndPaths)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Table;

Параметры

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и propertyNamesAndPaths.expand строка с разделителями-запятыми, указывающая загружаемые свойства навигации.

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

Excel.Table

reapplyFilters()

Повторно применяет все текущие фильтры к таблице.

reapplyFilters(): void;

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

void

Комментарии

[ Набор API: ExcelApi 1.2 ]

resize(newRange)

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

resize(newRange: Range | string): void;

Параметры

newRange

Excel.Range | string

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

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

void

Комментарии

[ Набор API: ExcelApi 1.13 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/46-table/resize-table.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and a table on that worksheet.
  const sheet = context.workbook.worksheets.getItem("Sample");
  const expensesTable = sheet.tables.getItem("ExpensesTable");
  
  // Resize the table.
  expensesTable.resize("A1:D20");
  
  await context.sync();
});

set(properties, options)

Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.

set(properties: Interfaces.TableUpdateData, options?: OfficeExtension.UpdateOptions): void;

Параметры

properties

Excel.Interfaces.TableUpdateData

Объект JavaScript со свойствами, структурированными изоморфно по свойствам объекта, для которого вызывается метод .

options

OfficeExtension.UpdateOptions

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

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

void

set(properties)

Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.

set(properties: Excel.Table): void;

Параметры

properties

Excel.Table

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

void

setStyle(style)

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Задает стиль, применяемый к таблице.

setStyle(style: string | TableStyle | BuiltInTableStyle): void;

Параметры

style

string | Excel.TableStyle | Excel.BuiltInTableStyle

Стиль, применяемый к таблице. Если InvalidArgumentException указана строка, не соответствующая имени какого-либо стиля, возникает исключение .

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

void

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.Table объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.TableData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

toJSON(): Excel.Interfaces.TableData;

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

Excel.Interfaces.TableData

Сведения о событии

onChanged

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

readonly onChanged: OfficeExtension.EventHandlers<Excel.TableChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.TableChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-table-changed.yaml

await Excel.run(async (context) => {
    let table = context.workbook.tables.getItemAt(0);
    table.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event");
});

onFiltered

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Происходит при применении фильтра к определенной таблице.

readonly onFiltered: OfficeExtension.EventHandlers<Excel.TableFilteredEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.TableFilteredEventArgs>

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

onSelectionChanged

Происходит при изменении выделения в определенной таблице.

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.TableSelectionChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.TableSelectionChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-table-changed.yaml

await Excel.run(async (context) => {
    let table = context.workbook.tables.getItemAt(0);
    table.onSelectionChanged.add(onSelectionChange);

    await context.sync();
    console.log("A handler has been registered for table onSelectionChanged event");
});