SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    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?: 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: 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>

      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.

      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: 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