Срезы и временные шкалы

Headless поддерживается

Срезы фильтруют таблицы, сводные таблицы и сводные диаграммы по элементам источника. Временные шкалы фильтруют поддерживаемые исходные поля дат сводного отчёта; столбцы таблиц, текстовые, вычисляемые и производные поля группировки не поддерживаются.

Режим плагина

Установка

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

Использование

Добавьте следующий код в существующую настройку Sheets, настроив рисование и источник в виде таблицы или сводной таблицы. Загрузите локализацию и зарегистрируйте плагины до создания книги.

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

Режим предустановки

Установка

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

Использование

Пресет Advanced включает модели, UI и Facade API срезов и временных шкал. Используйте его вместе с Core и Drawing и объедините переводы. Если Advanced уже подключён, добавьте slicer в его конфигурацию без повторной регистрации. Лицензия настраивается по руководству.

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import AdvancedLocale from '@univerjs/preset-sheets-advanced/locales/ru-RU'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import CoreLocale from '@univerjs/preset-sheets-core/locales/ru-RU'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import DrawingLocale from '@univerjs/preset-sheets-drawing/locales/ru-RU'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.RU_RU,  locales: {    [LocaleType.RU_RU]: mergeLocales(CoreLocale, DrawingLocale, AdvancedLocale),  },  presets: [    UniverSheetsCorePreset({ container: 'app' }),    UniverSheetsDrawingPreset(),    UniverSheetsAdvancedPreset({ slicer: { maxMemberWindowSize: 200 } }),  ],})

При использовании Worker задайте useWorker: true у Advanced и зарегистрируйте UniverSheetsAdvancedWorkerPreset() в Worker. Он включает и расчёт срезов.

Создание среза

Пример использует сводную таблицу в I1 активного листа с исходным полем Region. Получите стабильный ID исходного поля через getSourceFieldsInfo(); отображаемое имя и ID поля отчёта нельзя передавать в newSlicer().

TypeScript
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() привязывает построитель к источнику. build() только готовит конфигурацию, а insertSlicer() создаёт элемент управления. Лист размещения может отличаться от листа источника, но они должны находиться в одной книге. Для обычной таблицы используйте fWorksheet.newSlicer(columnId).setTableReference({ subUnitId, tableId }), где columnId — стабильный ID столбца таблицы.

Создание временной шкалы

Следующий пример использует ту же сводную таблицу и требует исходное поле дат с именем Date. newTimeline() проверяет источник и отклоняет неподдерживаемые поля. API диапазонов временной шкалы принимают серийные значения Excel в системе дат книги, а не объекты JavaScript Date.

TypeScript
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(),)

Поиск элементов и отслеживание изменений

Вызывайте getSlicer(viewId) / getSlicers() и getTimeline(viewId) / getTimelines() на листе размещения. viewId — ID, возвращаемый методом getId() элемента управления, а не ID рисунка.

Подписывайтесь на SlicerAdded, SlicerChanged, SlicerRemoved, TimelineAdded, TimelineChanged и TimelineRemoved через univerAPI.addEvent(). Эти события описывают зафиксированные локальные изменения, а не удалённое сохранение или завершение отрисовки. Когда подписка больше не нужна, вызовите её метод dispose().

Справочник API:

Запрос элементов и общие фильтры

setSelection() принимает типизированные значения источника: число 1, строка '1' и пустое значение различаются. Не передавайте подписи или индексы списка. Фильтр общий для всех представлений одного кэша и связанных отчётов. Для Table он заменяет фильтр данного столбца, сохраняя остальные. clearFilter() снимает фильтр.

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

getItems({ start, count }) запрашивает окно данных, не меняя выбор. По умолчанию запрашивается 100 элементов, предел задаёт положительное целое maxMemberWindowSize (по умолчанию 200). Сохраняйте выбор за пределами окна. setConnections() заменяет связи со сводными отчётами; getConnectionCandidates() возвращает совместимые отчёты. Изменения требуют прав на соответствующие листы. См. FSheetSlicer.

Условия даты временной шкалы

setSelection({ startDate, endDate, useWholeDay: true }) расширяет дробные границы до целых дней, сохраняя целочисленную конечную границу исключённой. Без useWholeDay интервал точно равен [startDate, endDate). Фиксированное условие из сводной таблицы может быть непрерывным не всегда: читайте его через getDateCondition(). В этом случае getSelection() возвращает undefined, что само по себе не означает отсутствие фильтра.

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.