From d881be0222e9c7cbbef6ac3c8a11993a478c6ba4 Mon Sep 17 00:00:00 2001 From: lijinke666 Date: Mon, 19 Aug 2024 16:47:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20ViewMeta=20?= =?UTF-8?q?=E5=92=8C=20CellData=20=E6=96=87=E6=A1=A3=20close=20#2845?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/s2-core/src/data-set/cell-data.ts | 4 +- .../base-interaction/click/data-cell-click.ts | 20 +-- .../docs/api/basic-class/base-data-set.zh.md | 66 +-------- s2-site/docs/api/basic-class/cell-data.en.md | 5 + s2-site/docs/api/basic-class/cell-data.zh.md | 46 +++++++ s2-site/docs/api/basic-class/store.zh.md | 2 +- s2-site/docs/api/general/S2DataConfig.zh.md | 73 +--------- .../docs/common/custom/layoutCellMeta.zh.md | 2 +- s2-site/docs/common/interaction.zh.md | 2 +- s2-site/docs/common/view-meta.zh.md | 126 +++++++++++++++++- .../docs/manual/advanced/get-cell-data.zh.md | 36 ++--- s2-site/docs/manual/basic/sort/basic.zh.md | 2 +- .../extended-reading/data-process/pivot.zh.md | 4 +- s2-site/docs/manual/migration-v2.zh.md | 39 +++++- 14 files changed, 250 insertions(+), 177 deletions(-) create mode 100644 s2-site/docs/api/basic-class/cell-data.en.md create mode 100644 s2-site/docs/api/basic-class/cell-data.zh.md diff --git a/packages/s2-core/src/data-set/cell-data.ts b/packages/s2-core/src/data-set/cell-data.ts index 380fdfd781..e12cdf3fbb 100644 --- a/packages/s2-core/src/data-set/cell-data.ts +++ b/packages/s2-core/src/data-set/cell-data.ts @@ -5,8 +5,8 @@ import type { RawData } from '../common/interface/s2DataConfig'; export class CellData { constructor( - private raw: RawData, - private extraField: string, + public readonly raw: RawData, + public readonly extraField: string, ) {} static getCellData(raw: RawData, extraField: string) { diff --git a/packages/s2-core/src/interaction/base-interaction/click/data-cell-click.ts b/packages/s2-core/src/interaction/base-interaction/click/data-cell-click.ts index b408f1ee10..6fb67cea23 100644 --- a/packages/s2-core/src/interaction/base-interaction/click/data-cell-click.ts +++ b/packages/s2-core/src/interaction/base-interaction/click/data-cell-click.ts @@ -95,23 +95,15 @@ export class DataCellClick extends BaseEvent implements BaseEventImplement { } private showTooltip(event: CanvasEvent, meta: ViewMeta) { - const { - data, - isTotals = false, - value, - fieldValue, - field, - valueField, - } = meta; - const currentCellMeta = data; + const { data, isTotals = false, fieldValue, valueField } = meta; const onlyShowCellText = this.spreadsheet.isTableMode(); const cellData = onlyShowCellText ? ({ - ...(currentCellMeta as ViewMetaData), - value: value || fieldValue, - valueField: field || valueField, - } as TooltipData) - : (currentCellMeta as TooltipData); + ...(data as ViewMetaData), + value: fieldValue, + valueField, + } as unknown as TooltipData) + : (data as TooltipData); const cellInfos: TooltipData[] = [ cellData || { ...meta.rowQuery, ...meta.colQuery }, ]; 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 24906fbf01..816262da73 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 @@ -23,8 +23,8 @@ s2.dataSet.getFieldName('type') | getField | 获取字段 | (field: [CustomHeaderField](#customheaderfield)) => [Meta](/docs/api/general/S2DataConfig#meta) | | | getFieldMeta | 获取字段元数据信息 | (field: [CustomHeaderField](#customheaderfield), meta?: [Meta[]](/docs/api/general/S2DataConfig#meta)) => [Meta](/docs/api/general/S2DataConfig#meta) | | getFieldName | 获取字段名 | (field: [CustomHeaderField](#customheaderfield), defaultValue?: string) => `string` | | -| getCustomRowFieldName | 获取自定义单元格字段名称 | (cell: S2CellType) => `string` | | -| getCustomFieldDescription | 获取自定义单元格字段描述 | (cell: S2CellType) => `string` | | +| getCustomRowFieldName | 获取自定义单元格字段名称 | (cell: S2CellType<[`ViewMeta`](#viewmeta) \| [`Node`](/api/basic-class/node)>) => `string` | | +| getCustomFieldDescription | 获取自定义单元格字段描述 | (cell: S2CellType<[`ViewMeta`](#viewmeta) \| [`Node`](/api/basic-class/node)>) => `string` | | | getFieldFormatter | 获取字段格式化函数 | (field: [CustomHeaderField](#customheaderfield)) => [Formatter](#formatter) | | | getFieldDescription | 获取字段描述 | (field: [CustomHeaderField](#customheaderfield)) => [Formatter](#formatter) | | | setDataCfg | 设置数据配置 | `(dataCfg: T extends true ?` [`S2DataConfig`](/docs/api/general/S2DataConfig) `: Partial<`[`S2DataConfig`](/docs/api/general/S2DataConfig)`>, reset?: T) => void` | `reset` 参数需在 `@antv/s2^1.34.0`版本使用 | @@ -37,68 +37,6 @@ s2.dataSet.getFieldName('type') | displayFormattedValueMap | 单元格所对应格式化后的值（用于编辑表） | `Map` | | | getValueRangeByField | 获取数值最大最小值区间 | `(field: string) => { minValue: number, maxValue: number }` | | -### SimpleData - -```ts -type SimpleData = string | number | null | undefined; -``` - -### MultiData - -```ts -interface MultiData { - values: T; - originalValues?: T; - label?: string; - [key: string]: unknown; -} -``` - -### DataItem - -```ts - -type DataItem = - | SimpleData - | MultiData - | Record - | undefined - | null; -``` - -### RawData - -```ts -type RawData = Record; -``` - -### DataType - -```ts -type DataType = Record; -``` - -### ExtraData - -```ts -type ExtraData = { - [EXTRA_FIELD]: string; - [VALUE_FIELD]: string | DataItem; -}; -``` - -### Data - -```ts -type Data = RawData & ExtraData; -``` - -### ViewMetaData - -```ts -type ViewMetaData = Data | CellData; -``` - ### Formatter ```ts diff --git a/s2-site/docs/api/basic-class/cell-data.en.md b/s2-site/docs/api/basic-class/cell-data.en.md new file mode 100644 index 0000000000..033fd4c925 --- /dev/null +++ b/s2-site/docs/api/basic-class/cell-data.en.md @@ -0,0 +1,5 @@ +--- +title: CellData +order: 10 +tag: New +--- diff --git a/s2-site/docs/api/basic-class/cell-data.zh.md b/s2-site/docs/api/basic-class/cell-data.zh.md new file mode 100644 index 0000000000..8958d93cc4 --- /dev/null +++ b/s2-site/docs/api/basic-class/cell-data.zh.md @@ -0,0 +1,46 @@ +--- +title: CellData +order: 10 +tag: New +--- + +功能描述：透视表数值单元格元数据。[详情](https://github.com/antvis/S2/blob/next/packages/s2-core/src/data-set/cell-data.ts) + +```ts +this.meta.data +``` + +| 参数 | 说明 | 类型 | +| --- | --- | --- | +| extraField | `string` | 虚拟度量字段 | +| raw | 原始数据 | [RawData](#rawdata) | +| getValueByField | 获取数值 | (field: `string`) => [DataItem](#dataitem) | +| $$value$$ | 指标值（内部使用） | [DataItem](#dataitem) | +| $$extra$$ | 虚拟度量字段 （内部使用，等价于 `extraField`) | `string` | +| $$origin$$ | 原始数据 （内部使用，等价于 `raw`) | [RawData](#rawdata) | + +## 静态方法 + +```ts | pure +import { CellData } from '@antv/s2' +``` + +### getCellData + +```ts +CellData.getCellData(raw: RawData, extraField: string) +``` + +### getCellDataList + +```ts +CellData.getCellDataList(raw: RawData, extraFields: string[]) +``` + +### getFieldValue + +```ts +CellData.getFieldValue(data: ViewMetaData, field?: string) +``` + + diff --git a/s2-site/docs/api/basic-class/store.zh.md b/s2-site/docs/api/basic-class/store.zh.md index 3fa89e5451..4e39b7b248 100644 --- a/s2-site/docs/api/basic-class/store.zh.md +++ b/s2-site/docs/api/basic-class/store.zh.md @@ -30,7 +30,7 @@ s2.store.set('key', value) // 存储 | lastRenderedColumnFields | 上一次渲染的列头配置 | `string[]` | | resized | 是否手动调整过宽高 | `boolean` | | visibleActionIcons | hover 显示的 icon 缓存 | `GuiIcon[]` | -| lastClickedCell | 上一次点击的单元格 | `S2CellType` | +| lastClickedCell | 上一次点击的单元格 | S2CellType<[`ViewMeta`](#viewmeta)> | | initOverscrollBehavior | 初始滚动链状态 | `'auto' \| 'none' \| 'contain'` | | sortMethodMap | 排序方式 | `Record` | | [key: string] | 其他任意字段 | `unknown` | diff --git a/s2-site/docs/api/general/S2DataConfig.zh.md b/s2-site/docs/api/general/S2DataConfig.zh.md index b0886b1458..dd1984755d 100644 --- a/s2-site/docs/api/general/S2DataConfig.zh.md +++ b/s2-site/docs/api/general/S2DataConfig.zh.md @@ -28,72 +28,6 @@ const s2DataConfig = { | sortParams | 排序参数配置 | [SortParam](#sortparam)[] | | | | filterParams | 筛选参数配置 | [FilterParam](#filterparam)[] | | | -### RawData - -[SimpleData](#simpledata) | [MiniChartData](#minichartdata) | [MultiData](#multidata) - -功能描述：表格数据源 - -```ts -type RawData = Record -type DataItem = SimpleData | MultiData -``` - -#### SimpleData - -功能描述：基础数据类型 - -```ts -type SimpleData = string | number -``` - -```ts -const data = [ - { - area: '东北', - province: '吉林', - city: '白山', - type: '办公用品', - subType: '纸张', - cost: '2', - }, - { - area: '东北', - province: '吉林', - city: '白山', - type: '办公用品', - subType: '笔', - cost: '3', - } -]; -``` - -#### MiniChartData - - - -#### MultiData - -功能描述：用于支持多指标类型的自定义数据单元格渲染。例如：[趋势分析表](/examples/react-component/sheet#strategy) - -| 配置项名称 | 说明 | 类型 | 默认值 | 必选 | -| :--------------- | :----------------------------------------- | :---------------------------- | :----- | :--- | -| `values` | 格式化后的数据，直接展示在 dataCfg 中 | [SimpleData](#simpledata)[][] | ✓ | -| `originalValues` | 原始数据，用于原始数据导出 | [SimpleData](#simpledata)[][] | | | -| `label` | 用作单元格小标题，单独占一行展示 | `string` | | | -| `[key: string]` | 其他透传字段，用于自定义单元格的定制化展示 | `unknown` | `` | | - -```ts -const data = [ - { - number: { - originalValues: [1, 2, 3], - values: ['1', '2', '3'] - } - } -]; -``` - ### Fields 功能描述： 配置表格的维度域，即对应行列维度。 @@ -115,11 +49,10 @@ const data = [ | field | 字段 id （即 [Fields](#fields) 中配置的字段） | `string \| string[] \| RegExp` | | | | name | 字段名称 | `string` | | | | description | 字段描述，会显示在行头、列头、单元格对应的 tooltip 中 | `string` | | | -| formatter | 格式化
单元格、行头和列头支持格式化，角头不支持格式化。只有单元格存在第二个参数。
数值字段：一般用于格式化数字单位
文本字段：一般用于做字段枚举值的别名
第二个参数在以下情况会传入：data cell 格式化，复制/导出，tooltip 展示（**且仅在选择多个单元格时，data 类型为数组**） | `(value: unknown, data?: Data \| Data[], meta?: Node \| ViewMeta) => string` | | | +| formatter | 格式化
单元格、行头和列头支持格式化，角头不支持格式化。只有单元格存在第二个参数。
数值字段：一般用于格式化数字单位
文本字段：一般用于做字段枚举值的别名
第二个参数在以下情况会传入：data cell 格式化，复制/导出，tooltip 展示（**且仅在选择多个单元格时，data 类型为数组**） | (value: unknown, data?: [`Data`](#data) \| [`Data`](#data)[], meta?: [`Node`](/api/basic-class/node) \| [`ViewMeta`](#viewmeta)) => string | | | - - + ### FilterParam @@ -130,3 +63,5 @@ const data = [ | `filterKey` | 需要筛选的字段 id | `string` | | ✓ | | `filteredValues` | 不包含的维度值 | `unknown[]` | | | | `customFilter` | 自定义筛选函数，最终筛选的结果是同时满足 customFilter 且不在 filteredValues 中 | `(raw: Record) => boolean` | | | + + diff --git a/s2-site/docs/common/custom/layoutCellMeta.zh.md b/s2-site/docs/common/custom/layoutCellMeta.zh.md index 1c71a95ef4..c3436e8562 100644 --- a/s2-site/docs/common/custom/layoutCellMeta.zh.md +++ b/s2-site/docs/common/custom/layoutCellMeta.zh.md @@ -13,4 +13,4 @@ LayoutCellMeta = (viewMeta: ViewMeta) => ViewMeta | null; | 参数 | 类型 | 必选 | 默认值 | 功能描述 | | --- | --- | --- | --- | --- | -| vieMeta | [ViewMeta](#viewmeta) | | | 单元格元信息 | +| viewMeta | [ViewMeta](#viewmeta) | | | 单元格元信息 | diff --git a/s2-site/docs/common/interaction.zh.md b/s2-site/docs/common/interaction.zh.md index e210ad6901..0a614389c7 100644 --- a/s2-site/docs/common/interaction.zh.md +++ b/s2-site/docs/common/interaction.zh.md @@ -9,7 +9,7 @@ order: 5 | 参数 | 说明 | 类型 | 默认值 | 必选 | | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| -------- | ---------------- | -| linkFields | 标记字段为链接样式，用于外链跳转 | `string[]` \| (meta: [Node](/docs/api/basic-class/node) \| ViewMeta) => boolean | | | +| linkFields | 标记字段为链接样式，用于外链跳转 | `string[]` \| (meta: [Node](/docs/api/basic-class/node) \| [ViewMeta](#viewmeta)) => boolean | | | | selectedCellsSpotlight | 是否开启选中高亮聚光灯效果 | `boolean` | `false` | | | hoverHighlight | 鼠标悬停时高亮当前单元格，以及所对应的行头，列头 | `boolean` | `true` | | | hoverFocus | 鼠标悬停在当前单元格超过默认 800ms 后，保持当前高亮，显示 tooltip，悬停时间通过设置 `duration` 来控制 | `boolean \| {duration: number}` | `true` | | diff --git a/s2-site/docs/common/view-meta.zh.md b/s2-site/docs/common/view-meta.zh.md index 8fcbb8a89a..3b3d1ae438 100644 --- a/s2-site/docs/common/view-meta.zh.md +++ b/s2-site/docs/common/view-meta.zh.md @@ -5,17 +5,17 @@ order: 6 ## ViewMeta -功能描述：单元格数据和位置等信息 +功能描述：数值单元格数据和位置等信息 | 参数 | 类型 | 必选 | 默认值 | 功能描述 | | --- | --- | --- | --- | --- | -| spreadsheet | [SpreadSheet](/docs/api/basic-class/spreadsheet) | | | 表格实例 | +| spreadsheet | [SpreadSheet](/api/basic-class/spreadsheet) | | | 表格实例 | | id | `string` | | | 单元格唯一标识 | | x | `number` | | | 单元格 x 坐标 | | y | `number` | | | 单元格 y 坐标 | | width | `number` | | | 单元格宽度 | | height | `number` | | | 单元格高度 | -| data | `Record` | | | 单元格原始数据度量 | +| data | [ViewMetaData](#viewmetadata) \| [SimpleData](#simpledata) | | | 单元格原始数据度量 | | rowIndex | `number` | | | 单元格在行叶子节点中的索引 | | colIndex | `number` | | | 单元格在列叶子节点中的索引 | | valueField | `string` | | | 度量 id | @@ -26,3 +26,123 @@ order: 6 | colQuery | `Record` | | | 列查询条件 | | rowId | `string` | | | 单元格的行 id | | colId | `string` | | | 单元格的列 id | + +### RawData + +[DateItem](#dataitem) + +```ts | pure +type RawData = Record; +``` + +### SimpleData + +```ts +type SimpleData = string | number | null | undefined; +``` + +### MultiData + +功能描述：用于支持多指标类型的自定义数据单元格渲染。例如：[趋势分析表](/examples/react-component/sheet#strategy) + +| 配置项名称 | 说明 | 类型 | 默认值 | 必选 | +| :--------------- | :----------------------------------------- | :---------------------------- | :----- | :--- | +| `values` | 格式化后的数据，直接展示在 dataCfg 中 | [SimpleData](#simpledata)[][] | ✓ | +| `originalValues` | 原始数据，用于原始数据导出 | [SimpleData](#simpledata)[][] | | | +| `label` | 用作单元格小标题，单独占一行展示 | `string` | | | +| `[key: string]` | 其他透传字段，用于自定义单元格的定制化展示 | `unknown` | `` | | + +```json +{ + "number": { + "originalValues": [1, 2, 3], + "values": ["1", "2", "3"] + } +} +``` + +### DataItem + +[SimpleData](#simpledata) | [MultiData](#multidata) | [MiniChartData](#minichartdata) + +```ts | pure +type DataItem = SimpleData | MultiData | MiniChartData | Record; +``` + +```json +{ + "number": 7789, + "province": "浙江省", + "city": "杭州市", + "type": "家具", + "sub_type": "桌子" +} +``` + +### ExtraData + +```ts | pure +import type { EXTRA_FIELD, VALUE_FIELD } from '@antv/s2'; + +type ExtraData = { + [EXTRA_FIELD]: string; + [VALUE_FIELD]: string | DataItem; +}; +``` + +```json +{ + "$$extra$$": "number", + "$$value$$": 7789, +} +``` + +### Data + +```ts | pure +type Data = RawData & ExtraData; +``` + +### ViewMetaData + +[查看 `CellData` 定义](/api/basic-class/cell-data) + +```ts | pure +type ViewMetaData = Data | CellData; +``` + +#### Data + +```json +{ + "city": "杭州市" +} +``` + +#### CellData + +```json +{ + "extraField": "number", + "raw": { + "number": 7789, + "province": "浙江省", + "city": "杭州市", + "type": "家具", + "sub_type": "桌子" + }, + "$$extra$$": "number", + "$$value$$": 7789, + "$$origin$$": { + "number": 7789, + "province": "浙江省", + "city": "杭州市", + "type": "家具", + "sub_type": "桌子" + } +} +``` + +### MiniChartData + + diff --git a/s2-site/docs/manual/advanced/get-cell-data.zh.md b/s2-site/docs/manual/advanced/get-cell-data.zh.md index a4b58f9cf2..f9cbbe002c 100644 --- a/s2-site/docs/manual/advanced/get-cell-data.zh.md +++ b/s2-site/docs/manual/advanced/get-cell-data.zh.md @@ -306,14 +306,15 @@ s2.on(S2Event.DATA_CELL_CLICK, (event) => { console.log('当前单元格数据：', meta.data) /** { - "number": 834, - "province": "浙江省", - "city": "舟山市", - "type": "家具", - "sub_type": "沙发", - "$$extra$$": "number", - "$$value$$": 834 - } + "raw": { + "number": 632, + "province": "浙江省", + "city": "绍兴市", + "type": "家具", + "sub_type": "沙发" + }, + "extraField": "number" + } */ }) ``` @@ -369,15 +370,16 @@ const cellMeta = s2.facet.getCellMeta( ); /** - { - "number": 1634, - "province": "浙江省", - "city": "舟山市", - "type": "办公用品", - "sub_type": "纸张", - "$$extra$$": "number", - "$$value$$": 1634 - } + [{ + "raw": { + "number": 1634, + "province": "浙江省", + "city": "舟山市", + "type": "办公用品", + "sub_type": "纸张" + }, + "extraField": "number" + }] */ ``` diff --git a/s2-site/docs/manual/basic/sort/basic.zh.md b/s2-site/docs/manual/basic/sort/basic.zh.md index 971928cee2..5a446cb3e8 100644 --- a/s2-site/docs/manual/basic/sort/basic.zh.md +++ b/s2-site/docs/manual/basic/sort/basic.zh.md @@ -179,7 +179,7 @@ const s2DataConfig = { | sortByMeasure | 按照度量值（数值）排序 | `string` | - | | | query | 筛选条件，缩小排序范围 如 ：`{city:'白山'}` | `object` | - | | | type | 组内排序用来显示 icon | `string` | - | | -| data | 当前排序数据列表 | `Array` | - | | +| data | 当前排序数据列表 | Array<`string` \| [`CellData`](/api/basic-class/cell-data)> | - | | #### 维度值（行/列头） diff --git a/s2-site/docs/manual/extended-reading/data-process/pivot.zh.md b/s2-site/docs/manual/extended-reading/data-process/pivot.zh.md index 8f98f507a6..34f8761887 100644 --- a/s2-site/docs/manual/extended-reading/data-process/pivot.zh.md +++ b/s2-site/docs/manual/extended-reading/data-process/pivot.zh.md @@ -162,7 +162,7 @@ const rawData = lodash.get(indexesData, path); ```ts const data = CellData.getCellData(rawData, query[EXTRA_FIELD]); -console.log(data); //{ raw: rawData, extraField: "xxx" } +console.log(data); // { raw: rawData, extraField: "xxx" } ``` ### 获取多个数据 @@ -173,7 +173,7 @@ console.log(data); //{ raw: rawData, extraField: "xxx" } ```ts const dataList = getMultiData({ - query: { province: '浙江省', $$extra$$: 'price' } + query: { province: '浙江省', $$extra$$: 'price' } }); ``` diff --git a/s2-site/docs/manual/migration-v2.zh.md b/s2-site/docs/manual/migration-v2.zh.md index a991d88aab..f78f6a3135 100644 --- a/s2-site/docs/manual/migration-v2.zh.md +++ b/s2-site/docs/manual/migration-v2.zh.md @@ -565,6 +565,7 @@ export interface LayoutResult { + "$$extra$$": "number" + } } +``` 明细表： @@ -652,7 +653,7 @@ const s2Options = { ```js { - fields:{ + fields: { rows: ["province", "city"], columns: ["type", "subType"], values: ["number1", "number2"], @@ -721,6 +722,40 @@ const s2Options = { 具体请查看 [获取单元格数据](/manual/advanced/get-cell-data) 相关文档。 +#### 透视表数值单元格元数据数据结构变更 + +`this.meta.data` 数据结构变更： + +```diff +{ +- "number": 7789, +- "province": "浙江省", +- "city": "杭州市", +- "type": "家具", +- "sub_type": "桌子", + ++ "extraField": "number", ++ "raw": { ++ "number": 7789, ++ "province": "浙江省", ++ "city": "杭州市", ++ "type": "家具", ++ "sub_type": "桌子" ++ }, ++ "$$extra$$": "number", ++ "$$value$$": 7789, ++ "$$origin$$": { ++ "number": 7789, ++ "province": "浙江省", ++ "city": "杭州市", ++ "type": "家具", ++ "sub_type": "桌子" ++ } +} +``` + +具体请查看 [CellData](/api/basic-class/cell-data) 相关文档。 + #### 单元格刷选选中状态变更 `1.x` 中，行列头刷选选中状态为 `brushSelected`, 数值单元格的刷选选中状态为 `selected`, `2.x` 中做了进一步统一和区分： @@ -880,7 +915,7 @@ s2.on(S2Event.GLOBAL_LINK_FIELD_JUMP, (data) => { ``` -### 数值单元格获取数值范围区间方式变更 +#### 数值单元格获取数值范围区间方式变更 ```diff - dataCell.valueRangeByField