SheetXL - v1.0.2
    Preparing search index...

    Interface IFilter

    Filters are used to hide spans (rows or columns). that do not match a set of conditions.

    A column's filter ANDs with the other columns' (Excel's AutoFilter): setting one leaves the rest in place unless replace says otherwise. Every write returns a Promise that resolves once the rows are hidden; the criteria are written in the same transaction, so an await is what makes a read after the call see them.

    interface IFilter {
        isIFilter: true;
        apply(options?: ITransaction.OperationOptions): Promise<IFilter>;
        delete(options?: ITransaction.OperationOptions): Promise<IFilter>;
        filter(
            condition?: ICondition.Input<any>,
            options?: ITransaction.OperationOptions,
        ): Promise<IFilter>;
        getCondition(): ICondition<any> | null;
        getDisplayTexts(values: readonly Scalar[]): readonly string[];
        getIndex(): number;
        getItems(options?: IFilter.GetItemsOptions): Promise<Items>;
        getRange(): ICellRange;
        setCondition(
            condition: ICondition.Input<any> | null,
            replace?: boolean,
            options?: ITransaction.OperationOptions,
        ): Promise<IFilter>;
    }

    Hierarchy (View Summary)

    Index
    isIFilter
    apply delete filter getCondition getDisplayTexts getIndex getItems getRange setCondition
    isIFilter: true

    For runtime type checking.

    • Filter the range using a condition.

      Parameters

      Returns Promise<IFilter>

      Resolves once the rows are hidden.

      Examples:

      keep only values greater than or equal to 30:

      sheet.getRange('E:E').filter({
        operator: ICondition.BuiltInOperatorNames.GreaterThanOrEqual,
        param: 30
      });

      Example 2 – function param

      sheet.getRange('E:E').filter(value => value >= 30);
      // or with context: (e.g., to ignore header row)
      sheet.getRange('E:E').filter((value, ctx) => {
        const { rowIndex } = ctx.getCoords();
        return rowIndex > 1 && value >= 30;
      });

      Example 3 – string The expression is parsed using the same rules as user input (e.g., "30" is a number, "=A1*2" is a formula, "40%" is 0.4).

      sheet.getRange('E:E').filter('>= 30');

    • The texts values show as in this column's data rows, each once, in column order: what a list by displayed text would hold for them, and what the xlsx writer spells a value list as, since OOXML's list holds displayed text. A value no cell holds contributes nothing.

      Parameters

      • values: readonly Scalar[]

      Returns readonly string[]

      Synchronous: it reads the number-format runs and the column's statistics, not its cells.

    • The offset index from the range

      Returns number

      This is relative to the table.

    • The column's distinct values, as a filter menu lists them.

      Parameters

      Returns Promise<Items>

      Under the default scope, which rows are read depends on the column:

      • With no condition on it, the rows that are showing. A row hidden by another column's filter, or by hand, is not listed.
      • With a condition on it, the rows every other column's filter passes, so a value this column's own condition hides is listed too, unchecked.

      An item is checked when at least one row holding it passes the filters, so a column filtered by any condition (> 5, say) lists the passing values checked. A row hidden by hand does not uncheck its value.

      Under the 'column' scope every row is read, and each item also says whether it passes the other columns' filters (IFilter.Item.passesOthers).

      Reads the stored values in one pass; the cost follows the column's content, not its extent.

      const filter = table.getColumnAt(1).getFilter();
      const { items } = await filter.getItems();
      // keep the first two values
      await filter.setCondition({
        operator: ICondition.BuiltInOperatorNames.InSet,
        param: { items: items.slice(0, 2).map((item) => item.text) }
      });

    • Returns the range this filter applies to: the column's data rows, header and totals excluded.

      Returns ICellRange

      A filter is exactly one column of its table, which is why the singular is declared here rather than on ICondition.Stateful.

    • Set the condition, null to clear this column's.

      Parameters

      • condition: ICondition.Input<any> | null

        The condition, or null to clear.

      • Optionalreplace: boolean

        If true, every other column's filter is dropped; omitted, they stay and this one ANDs with them. A column already filtered keeps its place in the level order.

      • Optionaloptions: ITransaction.OperationOptions

        Transaction options.

      Returns Promise<IFilter>

      Resolves once the rows are hidden; one transaction, one undo step.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods