Skip to content

Commit

Permalink
docs: 更新 condition 文档
Browse files Browse the repository at this point in the history
  • Loading branch information
wjgogogo committed Jan 25, 2024
1 parent ad30971 commit 7eca3ca
Show file tree
Hide file tree
Showing 9 changed files with 232 additions and 84 deletions.
2 changes: 1 addition & 1 deletion packages/s2-core/src/common/interface/condition.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ export type IntervalConditionMappingResult = {
* @description custom the interval condition's width
* @version 1.38.0
*/
fieldValue?: number;
fieldValue?: number | string;
} & ValueRange;

export type ConditionMappingResult<T = unknown> = T | undefined | null;
Expand Down
4 changes: 0 additions & 4 deletions packages/s2-react/playground/config.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = {
return {
icon: 'CellUp',
fill: '#054',
size: 26,
};
},
},
Expand All @@ -204,7 +203,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = {
return {
icon: 'CellUp',
fill: '#FF4D4F',
size: 16,
};
}
},
Expand All @@ -216,7 +214,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = {
return {
icon: 'CellUp',
fill: '#FF4D4F',
size: 16,
};
},
},
Expand All @@ -226,7 +223,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = {
return {
icon: 'CellUp',
fill: '#FF4D4F',
size: 16,
};
},
},
Expand Down
63 changes: 25 additions & 38 deletions s2-site/docs/common/conditions.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,46 +9,33 @@ order: 2

<description>功能描述: 配置字段标记。分为文本 (text),背景 (background),柱状图 (interval),图标 (icon)。</description>

| 参数 | 说明 | 类型 | 默认值 | 必选 |
| ---------- | ---------- | --------------- | ------ | ---- |
| text | 文本字段标记 | [Condition](#condition)[] | - | |
| background | 背景字段标记 | [Condition](#condition)[] | - | |
| interval | 柱状图字段标记 | [Condition](#condition)[] | - | |
| icon | 图标字段标记 | [IconCondition](#iconcondition) | - | |
| 参数 | 说明 | 类型 | 默认值 | 必选 |
| ---------- | -------------- | --------------------------------------------- | ------ | ---- |
| text | 文本字段标记 | [TextCondition](#textcondition)[] | - | |
| background | 背景字段标记 | [BackgroundCondition](#backgroundcondition)[] | - | |
| interval | 柱状图字段标记 | [IntervalCondition](#intervalcondition)[] | - | |
| icon | 图标字段标记 | [IconCondition](#iconcondition)[] | - | |

### Condition

类型:`object`**必选**

<description>功能描述: 配置条件格式。包括文本 (text),背景 (background),柱状图 (interval)。</description>
<description>功能描述: 配置条件格式。TextCondition,BackgroundCondition,IntervalCondition,IconCondition 具继承于 Condition。</description>

| 参数 | 说明 | 类型 | 默认值 | 必选 |
|---------|-----------------------------------|------------|----------|-----|
| field | 1. 字段 ID <br /> 2. 使用正则表达式匹配字段 ID | `string \| RegExp` | | |
| mapping | 作用映射函数​ | `function` | ||
| 参数 | 说明 | 类型 | 默认值 | 必选 |
| ------- | ---------------------------------------------- | ------------------------------------- | ------ | ---- |
| field | 1. 字段 ID <br /> 2. 使用正则表达式匹配字段 ID | `string \| RegExp` | | |
| mapping | 作用映射函数​ | [ConditionMapping](#conditionmapping) | | |

#### MappingFunction
#### ConditionMapping

```ts
type MappingFunction = (
fieldValue: number | string | null,
data: Record<string, any>,
node: DataCell | HeaderCell
) => {
// 仅用于图标字段标记,可选
icon?: string;

// 背景 | 文本 | 柱状图 | 图标 字段标记颜色填充,必选
fill: string;

// 仅用于柱状图字段标记,可选
isCompare?: boolean;
minValue?: number;
maxValue?: number;

// 仅用于背景字段标记,可选。(当背景颜色较暗,将文本颜色设置为白色。优先级低于 文本字段标记)
intelligentReverseTextColor?: boolean;
} | null | undefined // 返回值为空时,表示当前字段不显示字段标记样式
// TextCondition,BackgroundCondition,IntervalCondition,IconCondition 各自对应的 mapping 函数返回 的 T 有所不同
export type ConditionMapping<T = unknown> = (
fieldValue: number | string,
data: RawData,
cell?: DataCell | HeaderCell,
) => ConditionMappingResult<T>;

```

Expand Down Expand Up @@ -90,15 +77,13 @@ const options = {

### IconCondition

类型:`object`**必选**,默认值:`null`
类型:`object`**必选**

<description>功能描述: 配置图标 (icon) 条件格式</description>
<description>功能描述: 配置图标 (icon) 条件格式,和其他 Condition 的唯一区别在于多了 position 参数用于自定义 icon 相对于文本的位置</description>

| 参数 | 说明 | 类型 | 默认值 | 必选 |
| -------- | ------------ | -------- | ------- | ---- |
| field | 字段 ID | `string` | ||
| position | icon 相较于文字的位置 | `left \| right` | `right` | |
| mapping | 映射函数 | [MappingFunction](#mappingfunction) | ||
| 参数 | 说明 | 类型 | 默认值 | 必选 |
| -------- | --------------------- | --------------- | ------- | ---- |
| position | icon 相较于文字的位置 | `left \| right` | `right` | |

**icon condition 用法示例:**

Expand All @@ -121,3 +106,5 @@ const options = {
};

```

<embed src="@/docs/common/icon.zh.md"></embed>​
69 changes: 43 additions & 26 deletions s2-site/docs/manual/basic/conditions.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,19 @@ order: 4
tag: Updated
---

S2 自带字段标记特性。用户可以根据业务语义设置不同的渲染逻辑,实现重点数据的标记和分析。字段标记类型包括
在数据可视化和分析中,字段标记是一种常用的功能,它允许用户通过可视化的方式强调数据中的关键信息。S2 是一个数据可视化库,支持灵活的字段标记功能

* 文本 (text) 字段标记 (所有单元格类型)
* 背景 (background) 字段标记 (所有单元格类型)
* 柱状图 (interval) 字段标记 (仅支持数据单元格)
* 图标 (icon) 字段标记 (目前支持透视表数据单元格、行头和列头单元格)
* 文本 (text) 字段标记
* 背景 (background) 字段标记
* 柱状图 (interval) 字段标记
* 图标 (icon) 字段标记

下图直观展示了四种字段标记的形态:

<img src="https://gw.alipayobjects.com/mdn/rms_56cbb2/afts/img/A*-lr0QJRCxkEAAAAAAAAAAAAAARQnAQ" width="600" alt="preview" />

**数据单元格完整的支持 4 种字段标记,而角头、行头、列头这些头部单元格只支持文本、背景和图标三种字段标记(柱状图不适用于头部单元格,业务上价值不大)。**

## 快速上手

`S2` 字段标记特性通过配置 `s2Options`[`Conditions`](/docs/api/general/S2Options#conditions) 属性。
Expand Down Expand Up @@ -45,19 +47,17 @@ const s2Options = {

[Conditions 属性](/docs/api/general/S2Options#conditions) 可配置四种不同的字段,分别对应四种不同的字段标记。

* `text``background``interval` 的均为 [Condition](/docs/api/general/S2Options#condition) 数组类型
* `text``background``interval` ,`icon` 均是继承自[Condition](/docs/api/general/S2Options#condition) 数组类型
* 包含 `field``mapping` 两个字段
* 一个字段 ID 多次匹配到同一范围的字段标记规则,以最后一个规则为准
* 一个字段 ID 多次匹配到同一范围的字段标记规则,以最后一个规则为准
* `icon` 稍有不同,为 [IconCondition](/docs/api/general/S2Options#iconcondition) 数组类型
* 多一个 `position` 字段用于指定图标相对于文字的位置

重点解释 `field``mapping` 两个字段:
* 多一个额外的`position` 字段用于指定图标相对于文字的位置,定义图标相对于单元格文本的位置。这个位置可以是文本的左侧、右侧

### field

`field` 用于指定将字段标记应用于哪些字段上,其取值范围会因表的形态不同而不同:

* 对于透视表,`field` 取值范围或正则匹配范围是 `values`,作用范围为行头、列头、角头和数据单元格
* 对于透视表,`field` 取值范围或正则匹配范围是 `rows``columns``values`,作用范围为行头、列头、角头和数据单元格
* 对于明细表,`field` 取值范围或正则匹配范围是 `columns`,作用范围为数据单元格

<table
Expand Down Expand Up @@ -85,25 +85,27 @@ const s2Options = {

### ​mapping

`mapping` 是处理字段标记的回调函数:
其中的重点是`mapping`函数,它用于处理字段标记的回调函数,如果`mapping`函数返回值为空,则表明不渲染该单元格的字段标记。

| 参数 | 说明 | 类型 | 默认值 | 必选 |
| ---------- |-------------| --------------------------------------- | ------ | ---- |
| fieldValue | 单元格对应字段的值 | `number` &#124; `string` &#124; `null` | - | |
| data | 单元格对应的​整行数据 | `object` | - ||
```ts
export type ConditionMapping<T = unknown> = (
fieldValue: number | string,
data: RawData,
cell?: DataCell | HeaderCell,
) => ConditionMappingResult<T>;
```

| 返回值 | 说明 | 类型 | 默认值 | 必选 |
| --------- |---------------------------------------------------------------------------------------------------------------------------| --------- | ------ | ---- |
| fill | 当作用于文本字段标记时,代表**文字填充颜色** <br>当作用于背景字段标记时,代表**单元格背景填充颜色** <br>当作用于柱状图字段标记时,代表**柱状图填充颜色** <br>当作用于图标字段标记时,代表**图标填充颜色** <br> | `string` | - ||
| icon | 仅用于**图标**字段标记,指定图标类型 | `string` | - | |
| isCompare | 仅用于**柱状图**字段标记,当为 `true` 时,可以定制柱状图的最大最小值 | `boolean` | - | |
| minValue | 仅用于**柱状图**字段标记且 `isCompare``true` 时,定制柱状图最小值 | `number` | - | |
| maxValue | 仅用于**柱状图**字段标记且 `isCompare``true` 时,定制柱状图最大值 | `number` | - | |
| fieldValue | 仅用于**柱状图**字段标记且 `isCompare``true` 时,定制柱状图的长度 | `number` | - | |
`mapping`接收三个参数,分别是:

> 如果`mapping`函数返回值为空,则表明不渲染该单元格的字段标记
* fieldValue: 当前单元格的值
* data: 如果是数据单元格,则是格子对应的数据;如果是角头、行头、列头,则是格子的 meta 信息
* cell: 对应当前格子的实例,如果前两个参数不满足业务需求,可以通过这个参数获取任意你想要的数据

<embed src="@/docs/common/icon.zh.md"></embed>​
不同的字段标记类型所需的返回值类型`ConditionMappingResult<T>`有所不同,主要是泛型`T`不同。S2 提供了完备的类型提示:

![类型提示](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*wgC1QoXRWkAAAAAAAAAAAAAADmJ7AQ/original)

> 也可以通过 [condition.ts](https://github.com/antvis/S2/blob/next/packages/s2-core/src/common/interface/condition.ts) 查看具体的类型定义。
🎨 字段标记详细的配置参考 [Conditions API](/docs/api/general/S2Options#conditions) 文档。

Expand All @@ -117,11 +119,20 @@ const s2Options = {

<Playground path="analysis/conditions/demo/icon.ts" rid='icon' height="200"></playground>

当同时存在自定义 Icon 时,Condition Icon 单元格 value 是强关联的,所以将 condition icon 放在紧贴文本的左右侧,即:

* `[header action icons] [condition icon] [text]`
* `[text] [condition icon] [header action icons]`

<Playground path="analysis/conditions/demo/icon-with-action.ts" rid='icon-with-action' height="200"></playground>

### 自定义柱状图范围

通过显示指定 `interval` 字段标记中的 `mapping` 函数返回值 `isCompare` 属性值为 `true`,并指定 `maxValue``minValue` 的值,可以自定义柱状图的区间范围。
> 如果 `mapping 函数` 返回值中的 `isCompare` 属性值为 `false` 或者不返回该属性。此时 `maxValue``minValue` 会以所有图表数据中该字段的最大最小值为区间范围
字段标记默认都是使用当前单元格的 value 作为绘制的依据,但在柱状图中,因为可以自定义柱状图的范围,那么也可能需要根据范围,同时对当前的 value 进行处理,使用新的 value 作为绘制的依据,此时可以通过`mapping` 函数返回值中指定`fieldValue`重新指定当前格子的绘制依据。

`price` 字段使用自定义模式,`cost` 字段使用默认模式:

<Playground path="analysis/conditions/demo/interval.ts" rid='interval'></playground>
Expand Down Expand Up @@ -151,4 +162,10 @@ const s2Options = {

<Playground path="analysis/conditions/demo/intelligent-background.ts" rid='intelligentReverseTextColor'></playground>

### 区分角头、行头、列头

在透视表模式中,如果字段标记对应的`field`是行头或者列头的维度,那么会同时将对应的角头单元格也进行标记,可以通过`mapping` 函数三个参数做区分:

<Playground path="analysis/conditions/demo/distinguish-cell.ts" rid='distinguish-cell'></playground>

​📊 查看更多 [字段标记示例](/examples/analysis/conditions#intelligent-background)
71 changes: 71 additions & 0 deletions s2-site/examples/analysis/conditions/demo/distinguish-cell.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
import { PivotSheet, S2Options, CornerCell } from '@antv/s2';

fetch(
'https://gw.alipayobjects.com/os/bmw-prod/2a5dbbc8-d0a7-4d02-b7c9-34f6ca63cff6.json',
)
.then((res) => res.json())
.then(async (dataCfg) => {
const container = document.getElementById('container');

const s2Options: S2Options = {
width: 600,
height: 480,
interaction: {
hoverHighlight: false,
},
conditions: {
text: [
// 行头
{
field: 'city',
mapping(fieldValue) {
// 如果是角头,fieldValue 就是 城市
if (fieldValue === '城市') {
return {
fill: 'red',
};
}
return {
fill: '#DB6BCF',
};
},
},
{
field: 'type',
mapping(fieldValue, data) {
// 非数据单元格的 data 返回的都是 cell 的 meta 信息
// 角头单元格独有 cornerType 属性
if (data.cornerType) {
return {
fill: 'blue',
};
}

return {
fill: '#327039',
};
},
},
{
field: 'sub_type',
mapping(fieldValue, data, cell) {
// cell 是对应当前格子的实例
if (cell instanceof CornerCell) {
return {
fill: '#BBDEDE',
};
}

return {
fill: '#2498D1',
};
},
},
],
},
};

const s2 = new PivotSheet(container, dataCfg, s2Options);

await s2.render();
});
60 changes: 60 additions & 0 deletions s2-site/examples/analysis/conditions/demo/icon-with-action.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import { PivotSheet, S2Options } from '@antv/s2';

fetch(
'https://gw.alipayobjects.com/os/bmw-prod/2a5dbbc8-d0a7-4d02-b7c9-34f6ca63cff6.json',
)
.then((res) => res.json())
.then(async (dataCfg) => {
const container = document.getElementById('container');

const s2Options: S2Options = {
width: 600,
height: 480,
interaction: {
hoverHighlight: false,
},
headerActionIcons: [
{
icons: ['ArrowUp'],
belongsCell: 'rowCell',
},
{
icons: ['CellUp'],
belongsCell: 'colCell',
},
{
icons: ['CellDown'],
belongsCell: 'cornerCell',
},
],
conditions: {
icon: [
{
field: 'city',
mapping() {
return {
icon: 'Trend',
fill: '#DB6BCF',
};
},
},
{
field: 'sub_type',
position: 'left',
mapping(fieldValue) {
if (fieldValue !== '子类别') {
return {
icon: 'CellDown',
fill: '#025DF4',
};
}
},
},
],
},
};

const s2 = new PivotSheet(container, dataCfg, s2Options);

await s2.render();
});
Loading

0 comments on commit 7eca3ca

Please sign in to comment.