切片器与时间线

切片器按数据源中的成员筛选表格、数据透视表和透视图。时间线筛选数据透视表中可作为数据源的原始日期字段;表格列、文本字段、计算字段和派生分组字段都不能作为时间线的数据源。

插件模式

安装

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/zh-CN'import { LocaleType } from '@univerjs/core'import '@univerjs-pro/sheets-slicer/facade'import '@univerjs-pro/sheets-slicer-ui/lib/index.css'univerAPI.loadLocales(LocaleType.ZH_CN, SheetsSlicerUILocale)univer.registerPlugin(UniverSheetsSlicerPlugin)univer.registerPlugin(UniverSheetsSlicerUIPlugin)

插件配置

UniverSheetsSlicerPlugin

  • maxMemberWindowSize
    number默认值: 200
    单次查询最多返回的成员数。

预设模式

安装

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

使用

高级预设已包含切片器和时间线的模型插件、UI 插件以及对应的 Facade API。使用该预设时,需要与核心预设和绘图预设组合,并合并相应的语言包。如果已经在使用高级预设,请在原有注册中加入 slicer 选项,不要重复注册。客户端许可证的配置见使用许可证。

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

使用 Worker 时,请在高级预设上设置 useWorker: true,并在 Worker 中注册 UniverSheetsAdvancedWorkerPreset()。该预设同样包含切片器计算插件。

预设配置

UniverSheetsCorePreset

  • container
    string | HTMLElement默认值: 'app'
    编辑器挂载的 DOM 元素或其 ID。

UniverSheetsAdvancedPreset

  • slicer
    object
    • maxMemberWindowSize
      number默认值: 200
      单次查询最多返回的成员数。
  • useWorker
    boolean默认值: false
    在 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 是控件 getId() 返回的业务 ID,不是绘图 ID。

通过 univerAPI.addEvent() 监听 SlicerAdded、SlicerChanged、SlicerRemoved、TimelineAdded、TimelineChanged 和 TimelineRemoved。事件只表示本地改动已提交,不表示改动已保存到远端,也不表示渲染已完成。不再需要时,请调用返回的订阅对象上的 dispose()。

API 参考:

成员查询与共享筛选

setSelection() 需要传入有类型的源值。数字 1、字符串 '1' 和空白是三个不同的成员,因此不要传入显示标签或可见列表中的下标。同一缓存的所有视图以及连接到该缓存的报表共用这份筛选。使用表格数据源时,筛选会替换该列的筛选条件,其他列保持不变。清除筛选请调用 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.