# Filtre

- Human documentation: [https://docs.univer.ai/fr-FR/guides/sheets/features/filter](https://docs.univer.ai/fr-FR/guides/sheets/features/filter)

- Agent Markdown: [https://docs.univer.ai/fr-FR/guides/sheets/features/filter.md](https://docs.univer.ai/fr-FR/guides/sheets/features/filter.md)

- Requested language: `fr-FR`

- Content language: `fr-FR`

- Documentation version: `1.2.0`

- Source: [sheets/features/filter.fr-FR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/filter.fr-FR.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-filter",
      "locale": "@univerjs/preset-sheets-filter/locales/en-US",
      "style": "@univerjs/preset-sheets-filter/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/sheets-filter",
      "facade": "@univerjs/sheets-filter/facade",
      "locale": "@univerjs/sheets-filter/locale/en-US"
    },
    {
      "client": "@univerjs/sheets-filter-ui",
      "locale": "@univerjs/sheets-filter-ui/locale/en-US",
      "style": "@univerjs/sheets-filter-ui/lib/index.css"
    }
  ],
  "mobile": true,
  "headless": true,
  "license": false,
  "server": false
}
```

La fonctionnalité de filtre permet aux utilisateurs de filtrer les données des feuilles de calcul afin de trouver et d’analyser rapidement des informations précises. Elle prend en charge diverses conditions et opérations de filtrage, ce qui permet de traiter les données plus efficacement.



## Mode plugin

### Installation

#### npm

```bash
npm install @univerjs/sheets-filter @univerjs/sheets-filter-ui
```

#### pnpm

```bash
pnpm add @univerjs/sheets-filter @univerjs/sheets-filter-ui
```

#### yarn

```bash
yarn add @univerjs/sheets-filter @univerjs/sheets-filter-ui
```

#### bun

```bash
bun add @univerjs/sheets-filter @univerjs/sheets-filter-ui
```

### Utilisation

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter' // [!code ++]
import { UniverSheetsFilterUIPlugin } from '@univerjs/sheets-filter-ui' // [!code ++]
import SheetsFilterUIEnUS from '@univerjs/sheets-filter-ui/locale/en-US' // [!code ++]
import '@univerjs/sheets-filter-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-filter/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsFilterUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsFilterPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsFilterUIPlugin) // [!code ++]
```

### Plugins et configuration

```typescript
interface IUniverSheetsFilterConfig {
  /**
   * Whether to display the filter sync switch in the filter panel.
   * This configuration can be used in a collaboration scenario to allow users to choose whether to enable filter synchronization.
   * If set to a defaultValue object, the filter sync switch will be displayed and its initial state will be determined by the defaultValue property.
   * @default false
   */
  enableSyncSwitch?: boolean | { defaultValue: boolean }
}
```

## Prise en charge mobile

Configurez d’abord l’[éditeur mobile](https://docs.univer.ai/fr-FR/guides/sheets/getting-started/installation.md#mobile-support). Dans l’initialisation en mode plugin de cette page, remplacez les inscriptions de bureau ci-dessous par les exports mobiles des mêmes paquets **avant d’ouvrir un document**. Conservez modèles, styles, traductions et imports Facade ; n’enregistrez pas les deux variantes.

| Paquet                       | Inscription de bureau        | Inscription mobile                 |
| ---------------------------- | ---------------------------- | ---------------------------------- |
| `@univerjs/sheets-filter-ui` | `UniverSheetsFilterUIPlugin` | `UniverSheetsFilterMobileUIPlugin` |

## Mode prédéfini

### Installation

#### npm

```bash
npm install @univerjs/preset-sheets-filter
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-filter
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-filter
```

#### bun

```bash
bun add @univerjs/preset-sheets-filter
```

### Utilisation

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsFilterPreset } from '@univerjs/preset-sheets-filter' // [!code ++]
import UniverPresetSheetsFilterEnUS from '@univerjs/preset-sheets-filter/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-filter/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsFilterEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsFilterPreset(), // [!code ++]
  ],
})
```

### Préréglages et configuration

```typescript
interface IUniverSheetsFilterPresetConfig {
  /**
   * Whether to display the filter sync switch in the filter panel.
   * This configuration can be used in a collaboration scenario to allow users to choose whether to enable filter synchronization.
   * If set to a defaultValue object, the filter sync switch will be displayed and its initial state will be determined by the defaultValue property.
   * @default false
   */
  enableSyncSwitch?: boolean | { defaultValue: boolean }
}
```

## API Facade

Les définitions de types complètes de l’API Facade sont disponibles dans la [FacadeAPI](https://docs.univer.ai/fr-FR/reference/facade.md).

### Importation

> [!INFO: Remarque sur le mode plugin]
> Seul le mode plugin nécessite l’importation manuelle du package Facade. Le mode prédéfini inclut déjà le package Facade correspondant ; aucune importation supplémentaire n’est donc nécessaire.

```typescript
import '@univerjs/sheets-filter/facade'
```

### Obtenir le filtre

Renvoie un objet [`FFilter`](https://docs.univer.ai/fr-FR/reference/facade/filter.md). Si la feuille ne comporte aucun filtre, renvoie `null`.

* Sur l’objet `FWorksheet`, utilisez [`getFilter()`](https://docs.univer.ai/fr-FR/reference/facade/worksheet.md#getfilter)
* Sur l’objet `FRange`, utilisez [`getFilter()`](https://docs.univer.ai/fr-FR/reference/facade/range.md#getfilter)

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// Get filter from FWorksheet
const fWorksheet = fWorkbook.getActiveSheet()
const fFilter = fWorksheet.getFilter()
fFilter?.getRange().getA1Notation()

// Get filter from FRange
const fRange = fWorksheet.getRange('A1:D14')
const fFilter2 = fRange.getFilter()
fFilter2?.getRange().getA1Notation()
```

### Créer un filtre

Crée un objet [`FFilter`](https://docs.univer.ai/fr-FR/reference/facade/filter.md). Si la feuille comporte déjà un filtre, renvoie `null`.

* Sur l’objet `FRange`, utilisez [`createFilter()`](https://docs.univer.ai/fr-FR/reference/facade/range.md#createfilter)

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D14')
let fFilter = fRange.createFilter()

// If the worksheet already has a filter, remove it and create a new filter.
if (!fFilter) {
  fWorksheet.getFilter().remove()
  fFilter = fRange.createFilter()
}
fFilter.getRange().getA1Notation()
```

### Supprimer le filtre

[`FFilter.remove()`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#remove) supprime le filtre de la feuille de calcul.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.getFilter()?.remove()
```

### Obtenir les critères de filtrage d’une colonne

La méthode [`FFilter.getColumnFilterCriteria(column)`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#getcolumnfiltercriteria) renvoie les critères de filtrage de la colonne spécifiée.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values of the range C1:F10
const fRange = fWorksheet.getRange('C1:F10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a filter on the range C1:F10
let fFilter = fRange.createFilter()

// If the filter already exists, remove it and create a new one
if (!fFilter) {
  fRange.getFilter().remove()
  fFilter = fRange.createFilter()
}

// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
const column = fWorksheet.getRange('C:C').getColumn()
fFilter.setColumnFilterCriteria(column, {
  colId: 0,
  filters: {
    filters: ['1', '5', '9'],
  },
})

// Print the filter criteria of the column C and D
fFilter.getColumnFilterCriteria(column) // { colId: 0, filters: { filters: ['1', '5', '9'] } }
fFilter.getColumnFilterCriteria(column + 1) // undefined
```

### Définir les critères de filtrage d’une colonne

La méthode [`FFilter.setColumnFilterCriteria(column, criteria)`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#setcolumnfiltercriteria) définit les critères de filtrage de la colonne spécifiée.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values of the range C1:F10
const fRange = fWorksheet.getRange('C1:F10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a filter on the range C1:F10
let fFilter = fRange.createFilter()

// If the filter already exists, remove it and create a new one
if (!fFilter) {
  fRange.getFilter().remove()
  fFilter = fRange.createFilter()
}

// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
const column = fWorksheet.getRange('C:C').getColumn()
fFilter.setColumnFilterCriteria(column, {
  colId: 0,
  filters: {
    filters: ['1', '5', '9'],
  },
})
```

### Supprimer les critères de filtrage d’une colonne

* La méthode [`FFilter.removeColumnFilterCriteria(column)`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#removecolumnfiltercriteria) supprime les critères de filtrage de la colonne spécifiée.
* La méthode [`FFilter.removeFilterCriteria()`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#removefiltercriteria) supprime les critères de filtrage de toutes les colonnes.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values of the range C1:F10
const fRange = fWorksheet.getRange('C1:F10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a filter on the range C1:F10
let fFilter = fRange.createFilter()

// If the filter already exists, remove it and create a new one
if (!fFilter) {
  fRange.getFilter().remove()
  fFilter = fRange.createFilter()
}

// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
const column = fWorksheet.getRange('C:C').getColumn()
fFilter.setColumnFilterCriteria(column, {
  colId: 0,
  filters: {
    filters: ['1', '5', '9'],
  },
})

// Clear the filter criteria of the column C after 3 seconds
setTimeout(() => {
  fFilter.removeColumnFilterCriteria(column)
  // Or use fFilter.removeFilterCriteria() to remove all column filter criteria
}, 3000)
```

### Obtenir les lignes exclues par le filtre

La méthode [`FFilter.getFilteredOutRows()`](https://docs.univer.ai/fr-FR/reference/facade/filter.md#getfilteredoutrows) renvoie un tableau contenant les indices des lignes exclues par le filtre.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set some values of the range C1:F10
const fRange = fWorksheet.getRange('C1:F10')
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13],
])

// Create a filter on the range C1:F10
let fFilter = fRange.createFilter()

// If the filter already exists, remove it and create a new one
if (!fFilter) {
  fRange.getFilter().remove()
  fFilter = fRange.createFilter()
}

// Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
const column = fWorksheet.getRange('C:C').getColumn()
fFilter.setColumnFilterCriteria(column, {
  colId: 0,
  filters: {
    filters: ['1', '5', '9'],
  },
})

// Print the filtered out rows
fFilter.getFilteredOutRows() // [1, 2, 3, 5, 6, 7, 9]
```

### Écouteurs d’événements

Les définitions complètes des types d’événements sont disponibles dans la section [Événements](https://docs.univer.ai/fr-FR/reference/facade/events.md).

L’événement `SheetRangeFiltered` est déclenché lorsque les critères de filtrage de la colonne changent.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFiltered, (params) => {
  const { workbook, worksheet, col, criteria } = params
})

// Remove the event listener, use `disposable.dispose()`
```

L’événement `SheetBeforeRangeFilter` est déclenché avant la modification des critères de filtrage de la colonne.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilter, (params) => {
  const { workbook, worksheet, col, criteria } = params

  // Cancel the filter criteria change operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```

L’événement `SheetRangeFilterCleared` est déclenché lorsque les critères sont effacés.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFilterCleared, (params) => {
  const { workbook, worksheet } = params
})

// Remove the event listener, use `disposable.dispose()`
```

L’événement `SheetBeforeRangeFilterClear` est déclenché avant l’effacement des critères.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilterClear, (params) => {
  const { workbook, worksheet } = params

  // Cancel the filter clear operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```