Segments et chronologies

Les segments filtrent les tableaux, tableaux croisés dynamiques et graphiques croisés dynamiques selon les membres de la source. Les chronologies filtrent les champs de date d’origine compatibles des rapports croisés ; elles ne prennent pas en charge les colonnes de tableaux, les champs texte, les champs calculés ni les champs de regroupement dérivés.

Mode plugin

Installation

pnpm add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui

npm install @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui

yarn add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui

bun add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui

Utilisation

Ajoutez les éléments suivants à votre configuration Sheets, avec le dessin et la source de tableau ou de tableau croisé dynamique configurés. Chargez la langue et enregistrez les plugins avant de créer le classeur.

import { UniverSheetsSlicerPlugin } from '@univerjs-pro/sheets-slicer'import { UniverSheetsSlicerUIPlugin } from '@univerjs-pro/sheets-slicer-ui'import SheetsSlicerUILocale from '@univerjs-pro/sheets-slicer-ui/locale/fr-FR'import { LocaleType } from '@univerjs/core'import '@univerjs-pro/sheets-slicer/facade'import '@univerjs-pro/sheets-slicer-ui/lib/index.css'univerAPI.loadLocales(LocaleType.FR_FR, SheetsSlicerUILocale)univer.registerPlugin(UniverSheetsSlicerPlugin)univer.registerPlugin(UniverSheetsSlicerUIPlugin)

Mode prédéfini

Installation

pnpm add @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

npm install @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

yarn add @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

bun add @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

Utilisation

Le preset avancé inclut les modèles, l’UI et les API Facade des segments et chronologies. Associez-le aux presets Core et Drawing, avec leurs traductions. S’il est déjà enregistré, ajoutez slicer à sa configuration sans le dupliquer. Configurez la licence selon utiliser une licence.

import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import AdvancedLocale from '@univerjs/preset-sheets-advanced/locales/fr-FR'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import CoreLocale from '@univerjs/preset-sheets-core/locales/fr-FR'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import DrawingLocale from '@univerjs/preset-sheets-drawing/locales/fr-FR'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.FR_FR,  locales: {    [LocaleType.FR_FR]: mergeLocales(CoreLocale, DrawingLocale, AdvancedLocale),  },  presets: [    UniverSheetsCorePreset({ container: 'app' }),    UniverSheetsDrawingPreset(),    UniverSheetsAdvancedPreset({ slicer: { maxMemberWindowSize: 200 } }),  ],})

Avec un Worker, définissez useWorker: true sur le preset avancé et enregistrez UniverSheetsAdvancedWorkerPreset() dans le Worker ; il inclut aussi le calcul des segments.

Créer un segment

Cet exemple utilise un tableau croisé dynamique en I1 de la feuille active, avec un champ source nommé Region. Obtenez son ID d’origine stable avec getSourceFieldsInfo() ; les noms affichés et les ID de champs du rapport ne conviennent pas à newSlicer().

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook?.getActiveSheet()if (!fWorkbook || !fWorksheet) throw new Error('No active worksheet')const pivotTable = fWorkbook.getPivotTableByCell(  fWorkbook.getId(),  fWorksheet.getSheetId(),  0,  8,)const regionField = pivotTable?.getSourceFieldsInfo().find((field) => field.name === 'Region')if (!pivotTable || !regionField) throw new Error('Region source field not found')const slicer = await fWorksheet.insertSlicer(  pivotTable.newSlicer(regionField.id)    .setCaption(regionField.name)    .setPosition('N2')    .build(),)

pivotTable.newSlicer() lie le constructeur à sa source. build() prépare uniquement la configuration ; insertSlicer() crée le contrôle. La feuille hôte peut différer de la feuille source, mais elles doivent appartenir au même classeur. Pour une source de tableau, utilisez fWorksheet.newSlicer(columnId).setTableReference({ subUnitId, tableId }), où columnId est l’ID stable de la colonne du tableau.

Créer une chronologie

L’exemple suivant utilise le même tableau croisé dynamique et nécessite un champ de date d’origine nommé Date. newTimeline() valide la source et refuse les champs non pris en charge. Les API de plages de chronologie utilisent les numéros de série Excel du système de dates du classeur, pas des objets JavaScript Date.

const dateField = pivotTable.getSourceFieldsInfo().find((field) => field.name === 'Date')if (!dateField) throw new Error('Date source field not found')const timeline = await fWorksheet.insertTimeline(  pivotTable.newTimeline(dateField.id)    .setCaption(dateField.name)    .setLevel(univerAPI.Enum.TimelineLevel.Month)    .setPosition('N18')    .build(),)

Retrouver les contrôles et observer les changements

Appelez getSlicer(viewId) / getSlicers() et getTimeline(viewId) / getTimelines() sur la feuille hôte. viewId est l’ID métier renvoyé par getId() du contrôle, pas son ID de dessin.

Abonnez-vous à SlicerAdded, SlicerChanged, SlicerRemoved, TimelineAdded, TimelineChanged et TimelineRemoved via univerAPI.addEvent(). Ces événements décrivent des changements locaux validés, pas une sauvegarde distante ni la fin du rendu. Appelez dispose() sur l’abonnement lorsqu’il n’est plus nécessaire.

Référence API :

• FSheetSlicer
• FSheetSlicerBuilder
• FSheetTimeline
• FSheetTimelineBuilder
• FEventName

Requêtes de membres et filtres partagés

Passez des valeurs sources typées à setSelection() : le nombre 1, la chaîne '1' et une cellule vide sont distincts. N’utilisez ni libellés ni indices visibles. Le filtre est partagé par toutes les vues du même cache et les rapports connectés. Pour une Table, il remplace le filtre de cette colonne et conserve les autres. clearFilter() le supprime.

import { FilterSelectionMode, RecordValueType } from '@univerjs/core'const accepted = await slicer.setSelection({  mode: FilterSelectionMode.Include,  values: [{ type: RecordValueType.String, value: 'EMEA' }],})

getItems({ start, count }) lit une fenêtre, sans modifier la sélection. La requête porte sur 100 membres par défaut, plafonnés par maxMemberWindowSize (entier positif, 200 par défaut). Conservez les sélections hors fenêtre. setConnections() remplace les connexions aux rapports croisés ; getConnectionCandidates() fournit les candidats compatibles. Les modifications nécessitent les permissions des feuilles concernées. Voir FSheetSlicer.

Conditions de date de la chronologie

setSelection({ startDate, endDate, useWholeDay: true }) étend les bornes fractionnaires à des journées entières tout en excluant la borne de fin entière. Sans useWholeDay, l’intervalle est exactement [startDate, endDate). Une condition fixe partagée depuis le tableau croisé peut être discontinue : lisez-la avec getDateCondition(). Dans ce cas, getSelection() renvoie undefined, ce qui ne signifie pas à lui seul que la chronologie n’est pas filtrée.