Excel.Filter class

Reference

Package:: excel

Manages the filtering of a table's column.

Extends: OfficeExtension.ClientObject

Remarks

Properties

context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
criteria	The currently applied filter on the given column.

Methods

apply(criteria)	Apply the given filter criteria on the given column.
applyBottomItemsFilter(count)	Apply a "Bottom Item" filter to the column for the given number of elements.
applyBottomPercentFilter(percent)	Apply a "Bottom Percent" filter to the column for the given percentage of elements.
applyCellColorFilter(color)	Apply a "Cell Color" filter to the column for the given color.
applyCustomFilter(criteria1, criteria2, oper)	Apply an "Icon" filter to the column for the given criteria strings.
applyCustomFilter(criteria1, criteria2, operString)	Apply an "Icon" filter to the column for the given criteria strings.
applyDynamicFilter(criteria)	Apply a "Dynamic" filter to the column.
applyDynamicFilter(criteriaString)	Apply a "Dynamic" filter to the column.
applyFontColorFilter(color)	Apply a "Font Color" filter to the column for the given color.
applyIconFilter(icon)	Apply an "Icon" filter to the column for the given icon.
applyTopItemsFilter(count)	Apply a "Top Item" filter to the column for the given number of elements.
applyTopPercentFilter(percent)	Apply a "Top Percent" filter to the column for the given percentage of elements.
applyValuesFilter(values)	Apply a "Values" filter to the column for the given values.
clear()	Clear the filter on the given column.
load(options)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
toJSON()	Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that is passed to it.) Whereas the original Excel.Filter object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.FilterData`) that contains shallow copies of any loaded child properties from the original object.

Property Details

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Excel.RequestContext

criteria

The currently applied filter on the given column.

readonly criteria: Excel.FilterCriteria;

Property Value

Excel.FilterCriteria

Remarks

[ API set: ExcelApi 1.2 ]

Method Details

apply(criteria)

Apply the given filter criteria on the given column.

apply(criteria: Excel.FilterCriteria): void;

Parameters

criteria: Excel.FilterCriteria

The criteria to apply.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyBottomItemsFilter(count)

Apply a "Bottom Item" filter to the column for the given number of elements.

applyBottomItemsFilter(count: number): void;

Parameters

count: number

The number of elements from the bottom to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyBottomPercentFilter(percent)

Apply a "Bottom Percent" filter to the column for the given percentage of elements.

applyBottomPercentFilter(percent: number): void;

Parameters

percent: number

The percentage of elements from the bottom to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyCellColorFilter(color)

Apply a "Cell Color" filter to the column for the given color.

applyCellColorFilter(color: string): void;

Parameters

color: string

The background color of the cells to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyCustomFilter(criteria1, criteria2, oper)

Apply an "Icon" filter to the column for the given criteria strings.

applyCustomFilter(criteria1: string, criteria2?: string, oper?: Excel.FilterOperator): void;

Parameters

criteria1: string

The first criteria string.

criteria2: string

Optional. The second criteria string.

oper: Excel.FilterOperator

Optional. The operator that describes how the two criteria are joined.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyCustomFilter(criteria1, criteria2, operString)

Apply an "Icon" filter to the column for the given criteria strings.

applyCustomFilter(criteria1: string, criteria2?: string, operString?: "And" | "Or"): void;

Parameters

criteria1: string

The first criteria string.

criteria2: string

Optional. The second criteria string.

operString: "And" | "Or"

Optional. The operator that describes how the two criteria are joined.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyDynamicFilter(criteria)

Apply a "Dynamic" filter to the column.

applyDynamicFilter(criteria: Excel.DynamicFilterCriteria): void;

Parameters

criteria: Excel.DynamicFilterCriteria

The dynamic criteria to apply.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyDynamicFilter(criteriaString)

Apply a "Dynamic" filter to the column.

applyDynamicFilter(criteriaString: "Unknown" | "AboveAverage" | "AllDatesInPeriodApril" | "AllDatesInPeriodAugust" | "AllDatesInPeriodDecember" | "AllDatesInPeriodFebruray" | "AllDatesInPeriodJanuary" | "AllDatesInPeriodJuly" | "AllDatesInPeriodJune" | "AllDatesInPeriodMarch" | "AllDatesInPeriodMay" | "AllDatesInPeriodNovember" | "AllDatesInPeriodOctober" | "AllDatesInPeriodQuarter1" | "AllDatesInPeriodQuarter2" | "AllDatesInPeriodQuarter3" | "AllDatesInPeriodQuarter4" | "AllDatesInPeriodSeptember" | "BelowAverage" | "LastMonth" | "LastQuarter" | "LastWeek" | "LastYear" | "NextMonth" | "NextQuarter" | "NextWeek" | "NextYear" | "ThisMonth" | "ThisQuarter" | "ThisWeek" | "ThisYear" | "Today" | "Tomorrow" | "YearToDate" | "Yesterday"): void;

Parameters

criteriaString: "Unknown" | "AboveAverage" | "AllDatesInPeriodApril" | "AllDatesInPeriodAugust" | "AllDatesInPeriodDecember" | "AllDatesInPeriodFebruray" | "AllDatesInPeriodJanuary" | "AllDatesInPeriodJuly" | "AllDatesInPeriodJune" | "AllDatesInPeriodMarch" | "AllDatesInPeriodMay" | "AllDatesInPeriodNovember" | "AllDatesInPeriodOctober" | "AllDatesInPeriodQuarter1" | "AllDatesInPeriodQuarter2" | "AllDatesInPeriodQuarter3" | "AllDatesInPeriodQuarter4" | "AllDatesInPeriodSeptember" | "BelowAverage" | "LastMonth" | "LastQuarter" | "LastWeek" | "LastYear" | "NextMonth" | "NextQuarter" | "NextWeek" | "NextYear" | "ThisMonth" | "ThisQuarter" | "ThisWeek" | "ThisYear" | "Today" | "Tomorrow" | "YearToDate" | "Yesterday"

The dynamic criteria to apply.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyFontColorFilter(color)

Apply a "Font Color" filter to the column for the given color.

applyFontColorFilter(color: string): void;

Parameters

color: string

The font color of the cells to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyIconFilter(icon)

Apply an "Icon" filter to the column for the given icon.

applyIconFilter(icon: Excel.Icon): void;

Parameters

icon: Excel.Icon

The icons of the cells to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyTopItemsFilter(count)

Apply a "Top Item" filter to the column for the given number of elements.

applyTopItemsFilter(count: number): void;

Parameters

count: number

The number of elements from the top to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyTopPercentFilter(percent)

Apply a "Top Percent" filter to the column for the given percentage of elements.

applyTopPercentFilter(percent: number): void;

Parameters

percent: number

The percentage of elements from the top to show.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

applyValuesFilter(values)

Apply a "Values" filter to the column for the given values.

applyValuesFilter(values: Array<string | FilterDatetime>): void;

Parameters

values: Array<string | Excel.FilterDatetime>

The list of values to show. This must be an array of strings or an array of Excel.FilterDateTime objects.

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

clear()

Clear the filter on the given column.

clear(): void;

Returns

void

Remarks

[ API set: ExcelApi 1.2 ]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Excel.Interfaces.FilterLoadOptions): Excel.Filter;

Parameters

options: Excel.Interfaces.FilterLoadOptions

Provides options for which properties of the object to load.

Returns

Excel.Filter

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

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

Parameters

propertyNames: string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Excel.Filter

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

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

Parameters

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

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Excel.Filter

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Filter object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.FilterData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.FilterData;

Returns

Excel.Interfaces.FilterData

Excel.Filter class

Remarks

Properties

Methods

Property Details

context

Property Value

criteria

Property Value

Remarks

Method Details

apply(criteria)

Parameters

Returns

Remarks

applyBottomItemsFilter(count)

Parameters

Returns

Remarks

applyBottomPercentFilter(percent)

Parameters

Returns

Remarks

applyCellColorFilter(color)

Parameters

Returns

Remarks

applyCustomFilter(criteria1, criteria2, oper)

Parameters

Returns

Remarks

applyCustomFilter(criteria1, criteria2, operString)

Parameters

Returns

Remarks

applyDynamicFilter(criteria)

Parameters

Returns

Remarks

applyDynamicFilter(criteriaString)

Parameters

Returns

Remarks

applyFontColorFilter(color)

Parameters

Returns

Remarks

applyIconFilter(icon)

Parameters

Returns

Remarks

applyTopItemsFilter(count)

Parameters

Returns

Remarks

applyTopPercentFilter(percent)

Parameters

Returns

Remarks

applyValuesFilter(values)

Parameters

Returns

Remarks

clear()

Returns

Remarks

load(options)

Parameters

Returns

load(propertyNames)

Parameters

Returns

load(propertyNamesAndPaths)

Parameters

Returns

toJSON()

Returns

Feedback

Additional resources