docs: 完善 ViewMeta 和 CellData 文档 close #2845 (#2868)

antvis · Aug 23, 2024 · e05bb56 · e05bb56
1 parent 3dcf491
commit e05bb56
Show file tree

Hide file tree

Showing 14 changed files with 250 additions and 177 deletions.
diff --git 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
@@ -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
@@ -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<ViewMeta \| Node>) => `string`    |                                             |
-| getCustomFieldDescription                           | 获取自定义单元格字段描述                         | (cell: S2CellType<ViewMeta \| Node>) => `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                             | 设置数据配置                       | `<T extends boolean = false>(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<string, string>`                                                                                                                                                                             |                           |
 | getValueRangeByField   |  获取数值最大最小值区间      | `(field: string) => { minValue: number, maxValue: number }`     |   |
 
-### SimpleData
-
-```ts
-type SimpleData = string | number | null | undefined;
-```
-
-### MultiData
-
-```ts
-interface MultiData<T = SimpleData[][]> {
-  values: T;
-  originalValues?: T;
-  label?: string;
-  [key: string]: unknown;
-}
-```
-
-### DataItem
-
-```ts
-
-type DataItem =
-  | SimpleData
-  | MultiData
-  | Record<string, unknown>
-  | undefined
-  | null;
-```
-
-### RawData
-
-```ts
-type RawData = Record<string, DataItem>;
-```
-
-### DataType
-
-```ts
-type DataType = Record<string, unknown>;
-```
-
-### 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
@@ -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
@@ -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)
+```
+
+<embed src="@/docs/common/view-meta.zh.md"></embed>
diff --git 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<ViewMeta>` |
+| lastClickedCell | 上一次点击的单元格 | S2CellType<[`ViewMeta`](#viewmeta)> |
 | initOverscrollBehavior | 初始滚动链状态 | `'auto' \| 'none' \| 'contain'` |
 | sortMethodMap | 排序方式 | `Record<string, SortMethod>` |
 | [key: string] | 其他任意字段 | `unknown` |

diff --git 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<string, DataItem>
-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
-
-<embed src="@/docs/common/mini-chart.zh.md"></embed>
-
-#### 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   | 格式化 <br/> 单元格、行头和列头支持格式化，角头不支持格式化。只有单元格存在第二个参数。 <br/>数值字段：一般用于格式化数字单位<br/>文本字段：一般用于做字段枚举值的别名<br/> 第二个参数在以下情况会传入：data cell 格式化，复制/导出，tooltip 展示（**且仅在选择多个单元格时，data 类型为数组**） | `(value: unknown, data?: Data \| Data[], meta?: Node \| ViewMeta) => string` |        |      |
+| formatter   | 格式化 <br/> 单元格、行头和列头支持格式化，角头不支持格式化。只有单元格存在第二个参数。 <br/>数值字段：一般用于格式化数字单位<br/>文本字段：一般用于做字段枚举值的别名<br/> 第二个参数在以下情况会传入：data cell 格式化，复制/导出，tooltip 展示（**且仅在选择多个单元格时，data 类型为数组**） | (value: unknown, data?: [`Data`](#data) \| [`Data`](#data)[], meta?: [`Node`](/api/basic-class/node) \| [`ViewMeta`](#viewmeta)) => string |        |      |
 
 <embed src="@/docs/common/custom/customTreeNode.zh.md"></embed>
-
-<embed src="@/docs/common/sort-param.zh.md"></embed>
+<embed src="@/docs/common/view-meta.zh.md"></embed>
 
 ### FilterParam
 
@@ -130,3 +63,5 @@ const data = [
 | `filterKey`      | 需要筛选的字段 id                                                              | `string`                  |        | ✓    |
 | `filteredValues` | 不包含的维度值                                                                 | `unknown[]`               |        |      |
 | `customFilter`   | 自定义筛选函数，最终筛选的结果是同时满足 customFilter 且不在 filteredValues 中 | `(raw: Record<string, string>) => boolean` |        |      |
+
+<embed src="@/docs/common/sort-param.zh.md"></embed>
diff --git 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
@@ -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`      |       |