Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Aug 23, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions packages/s2-core/src/data-set/cell-data.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
20 changes: 6 additions & 14 deletions packages/s2-core/src/interaction/base-interaction/click/data-cell-click.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dataCell 的 meta 中没有 value 和 valueField, 是类型错误

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 },
];
Expand Down
66 changes: 2 additions & 64 deletions s2-site/docs/api/basic-class/base-data-set.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`版本使用 |
Expand All @@ -37,68 +37,6 @@ s2.dataSet.getFieldName('type')
| displayFormattedValueMap | 单元格所对应格式化后的值（用于编辑表） | `Map<string, string>` | |
| getValueRangeByField | 获取数值最大最小值区间 | `(field: string) => { minValue: number, maxValue: number }` | |

### SimpleData
Copy link
Member Author

@lijinke666 lijinke666 Aug 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

移到了 view-meta.md 中

image


```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
Expand Down
5 changes: 5 additions & 0 deletions s2-site/docs/api/basic-class/cell-data.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: CellData
order: 10
tag: New
---
46 changes: 46 additions & 0 deletions s2-site/docs/api/basic-class/cell-data.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
2 changes: 1 addition & 1 deletion s2-site/docs/api/basic-class/store.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
73 changes: 4 additions & 69 deletions s2-site/docs/api/general/S2DataConfig.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,72 +28,6 @@ const s2DataConfig = {
| sortParams | 排序参数配置 | [SortParam](#sortparam)[] | | |
| filterParams | 筛选参数配置 | [FilterParam](#filterparam)[] | | |

### RawData
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同上


[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

功能描述： 配置表格的维度域，即对应行列维度。
Expand All @@ -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

Expand All @@ -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>
2 changes: 1 addition & 1 deletion s2-site/docs/common/custom/layoutCellMeta.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ LayoutCellMeta = (viewMeta: ViewMeta) => ViewMeta | null;

| 参数 | 类型 | 必选 | 默认值 | 功能描述 |
| --- | --- | --- | --- | --- |
| vieMeta | [ViewMeta](#viewmeta) | | | 单元格元信息 |
| viewMeta | [ViewMeta](#viewmeta) | | | 单元格元信息 |
2 changes: 1 addition & 1 deletion s2-site/docs/common/interaction.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` | |
Expand Down
Loading
Loading