From 55b6f551148672c1edd6442632ff9ffddc83aa72 Mon Sep 17 00:00:00 2001 From: Jinke Li Date: Fri, 25 Oct 2024 15:22:28 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BC=98=E5=8C=96=20ViewMeta=20?= =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E5=AE=9A=E4=B9=89=E5=92=8C=E7=9B=B8=E5=85=B3?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20(#2935)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: 优化 ViewMeta 类型定义和相关文档 * docs: 补充 facet api 迁移文档 --- .../s2-core/src/common/interface/basic.ts | 2 +- .../s2-core/src/data-set/pivot-data-set.ts | 3 +- packages/s2-core/src/facet/pivot-facet.ts | 2 +- packages/s2-core/src/facet/table-facet.ts | 5 +- .../docs/api/basic-class/base-data-set.zh.md | 14 ++-- s2-site/docs/api/general/S2Options.zh.md | 70 +------------------ s2-site/docs/common/view-meta.zh.md | 2 +- s2-site/docs/manual/migration-v2.zh.md | 18 ++++- 8 files changed, 33 insertions(+), 83 deletions(-) diff --git a/packages/s2-core/src/common/interface/basic.ts b/packages/s2-core/src/common/interface/basic.ts index 2a84236549..871e0c2ba2 100644 --- a/packages/s2-core/src/common/interface/basic.ts +++ b/packages/s2-core/src/common/interface/basic.ts @@ -442,7 +442,7 @@ export interface ViewMeta { height: number; /** 单元格数据 */ - data: ViewMetaData | SimpleData | undefined; + data: ViewMetaData | undefined; /** 行索引 */ rowIndex: number; diff --git a/packages/s2-core/src/data-set/pivot-data-set.ts b/packages/s2-core/src/data-set/pivot-data-set.ts index 99631cf9a3..240e691945 100644 --- a/packages/s2-core/src/data-set/pivot-data-set.ts +++ b/packages/s2-core/src/data-set/pivot-data-set.ts @@ -41,6 +41,7 @@ import type { S2DataConfig, SimpleData, ViewMeta, + ViewMetaData, } from '../common/interface'; import { Node } from '../facet/layout/node'; import { resolveNillString } from '../utils'; @@ -439,7 +440,7 @@ export class PivotDataSet extends BaseDataSet { } } - public getCellData(params: GetCellDataParams) { + public getCellData(params: GetCellDataParams): ViewMetaData | undefined { const { query = {}, rowNode, isTotals = false, totalStatus } = params || {}; const { rows: originRows, columns } = this.fields; diff --git a/packages/s2-core/src/facet/pivot-facet.ts b/packages/s2-core/src/facet/pivot-facet.ts index 5c6e45e950..ef2e417e2e 100644 --- a/packages/s2-core/src/facet/pivot-facet.ts +++ b/packages/s2-core/src/facet/pivot-facet.ts @@ -150,7 +150,7 @@ export class PivotFacet extends FrozenFacet { rowQuery!, colQuery!, ); - const data = dataSet.getCellData({ + const data = (dataSet as PivotDataSet).getCellData({ query: dataQuery, rowNode: row, isTotals, diff --git a/packages/s2-core/src/facet/table-facet.ts b/packages/s2-core/src/facet/table-facet.ts index 452d8d1f67..7faf3339c4 100644 --- a/packages/s2-core/src/facet/table-facet.ts +++ b/packages/s2-core/src/facet/table-facet.ts @@ -22,6 +22,7 @@ import { import { DebuggerUtil } from '../common/debug'; import type { CellCallbackParams, + Data, DataItem, FilterParam, LayoutResult, @@ -376,7 +377,7 @@ export class TableFacet extends FrozenFacet { if (options.seriesNumber?.enable && colNode.field === SERIES_NUMBER_FIELD) { data = rowIndex + 1; } else { - data = dataSet.getCellData({ + data = (dataSet as TableDataSet).getCellData({ query: { field: colNode.field, rowIndex, @@ -397,7 +398,7 @@ export class TableFacet extends FrozenFacet { height: cellHeight, data: { [colNode.field]: data, - } as unknown as SimpleData, + } as unknown as Data, rowIndex, colIndex, isTotals: false, diff --git a/s2-site/docs/api/basic-class/base-data-set.zh.md b/s2-site/docs/api/basic-class/base-data-set.zh.md index 816262da73..eed5906237 100644 --- a/s2-site/docs/api/basic-class/base-data-set.zh.md +++ b/s2-site/docs/api/basic-class/base-data-set.zh.md @@ -40,18 +40,18 @@ s2.dataSet.getFieldName('type') ### Formatter ```ts - type Formatter = ( - v: unknown, - data?: SimpleData | ViewMetaData | ViewMetaData[], - meta?: Node | ViewMeta, -) => string; +type Formatter = ( + value: DataItem, + data?: DataItem | ViewMetaData | ViewMetaData[], + meta?: Node | ViewMeta | null | undefined, +) => SimpleData; ``` ### FormatResult ```ts - interface FormatResult { - formattedValue: string; +interface FormatResult { + formattedValue: SimpleData; value: DataItem; } ``` diff --git a/s2-site/docs/api/general/S2Options.zh.md b/s2-site/docs/api/general/S2Options.zh.md index 823a2faef8..ab16aeb761 100644 --- a/s2-site/docs/api/general/S2Options.zh.md +++ b/s2-site/docs/api/general/S2Options.zh.md @@ -70,6 +70,8 @@ const s2Options = { + + ## DataCellCallback ```js | pure @@ -78,8 +80,6 @@ DataCellCallback = (viewMeta: ViewMeta, s2: Spreadsheet) => G.Group; 功能描述：自定义数值单元格。[查看示例](/examples/custom/custom-cell#data-cell) - - ## CellCallback ```js | pure @@ -102,8 +102,6 @@ DataCellCallback = (s2: Spreadsheet, cells: S2CellType[], viewMeta: ViewMeta) => 功能描述：自定义合并单元格。[查看示例](/examples/custom/custom-cell/#custom-merged-cell) - - ## CornerHeaderCallback ```js | pure @@ -142,70 +140,6 @@ CornerHeaderCallback = (parent: S2CellType, spreadsheet: SpreadSheet, ...restOpt -## DataItem - -功能描述：基本数据格式 - -```ts -export enum MiniChartType { - Line = 'line', - Bar = 'bar', - Bullet = 'bullet', -} - -export interface MultiData { - label?: string; - values: SimpleData[][]; - originalValues?: SimpleData[][] -} - -export type SimpleData = string | number; - -export interface BaseChartData { - type: MiniChartType; - data: RawData[]; - encode?: { - x: keyof RawData; - y: keyof RawData; - }; - [key: string]: unknown; -} - -export interface BulletValue { - type: MiniChartType.Bullet; - measure: number | string; - target: number | string; - [key: string]: unknown; -} - -export type MiniChartData = BaseChartData | BulletValue; - -export interface MultiData { - values: T; - originalValues?: T; - label?: string; - [key: string]: unknown; -} - -export type SimpleData = string | number | null; - -export type DataItem = - | SimpleData - | MultiData - | Record - | undefined - | null; - -export type RawData = Record; - -export type ExtraData = { - [EXTRA_FIELD]: string; - [VALUE_FIELD]: string | DataItem; -}; - -export type Data = RawData & ExtraData; -``` - ## LayoutResult 功能描述：基本数据格式。[查看文档](/manual/advanced/get-cell-data#%E8%8E%B7%E5%8F%96%E6%8C%87%E5%AE%9A%E5%8C%BA%E5%9F%9F%E5%8D%95%E5%85%83%E6%A0%BC%E8%8A%82%E7%82%B9) diff --git a/s2-site/docs/common/view-meta.zh.md b/s2-site/docs/common/view-meta.zh.md index 3b3d1ae438..6d38603192 100644 --- a/s2-site/docs/common/view-meta.zh.md +++ b/s2-site/docs/common/view-meta.zh.md @@ -15,7 +15,7 @@ order: 6 | y | `number` | | | 单元格 y 坐标 | | width | `number` | | | 单元格宽度 | | height | `number` | | | 单元格高度 | -| data | [ViewMetaData](#viewmetadata) \| [SimpleData](#simpledata) | | | 单元格原始数据度量 | +| data | [ViewMetaData](#viewmetadata) | | | 单元格数据 | | rowIndex | `number` | | | 单元格在行叶子节点中的索引 | | colIndex | `number` | | | 单元格在列叶子节点中的索引 | | valueField | `string` | | | 度量 id | diff --git a/s2-site/docs/manual/migration-v2.zh.md b/s2-site/docs/manual/migration-v2.zh.md index eedb89c210..213baf149a 100644 --- a/s2-site/docs/manual/migration-v2.zh.md +++ b/s2-site/docs/manual/migration-v2.zh.md @@ -584,7 +584,7 @@ export interface LayoutResult { } ``` -5. 原 `s2.getContentHeight()` 废弃，移动到 `s2.facet.getContentHeight()` 中 +5. 原 `s2.getContentHeight()` 废弃，移动到 `s2.facet.getContentHeight()` 中。 ```diff - s2.getContentHeight() @@ -592,7 +592,21 @@ export interface LayoutResult { + s2.facet.getContentWidth() ``` -具体请查看 [获取单元格数据](/manual/advanced/get-cell-data) 相关文档。 +6. 获取布局节点相关 API，移动至 `s2.facet` 命名空间下。并新增丰富的 [语法糖](/api/basic-class/base-facet). + +```diff +- s2.getRowNodes() +- s2.getRowLeafNodes() +- s2.getColumnLeafNodes() +- s2.getColumnNodes() + ++ s2.facet.getRowNodes() ++ s2.facet.getRowLeafNodes() ++ s2.facet.getColLeafNodes() ++ s2.facet.getColNodes() +``` + +具体请查看 [获取单元格数据](/manual/advanced/get-cell-data) 和 [BaseFacet](/api/basic-class/base-facet) 相关文档。 #### 渲染参数变更