From 7eca3cab421837d5f68f9134d1d35937e2b90292 Mon Sep 17 00:00:00 2001 From: wjgogogo <906626481@qq.com> Date: Thu, 25 Jan 2024 17:40:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20condition=20=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../s2-core/src/common/interface/condition.ts | 2 +- packages/s2-react/playground/config.tsx | 4 -- s2-site/docs/common/conditions.zh.md | 63 +++++++--------- s2-site/docs/manual/basic/conditions.zh.md | 69 +++++++++++------- .../conditions/demo/distinguish-cell.ts | 71 +++++++++++++++++++ .../conditions/demo/icon-with-action.ts | 60 ++++++++++++++++ .../analysis/conditions/demo/interval.ts | 4 +- .../analysis/conditions/demo/meta.json | 41 +++++++---- .../analysis/conditions/demo/table-text.ts | 2 +- 9 files changed, 232 insertions(+), 84 deletions(-) create mode 100644 s2-site/examples/analysis/conditions/demo/distinguish-cell.ts create mode 100644 s2-site/examples/analysis/conditions/demo/icon-with-action.ts diff --git a/packages/s2-core/src/common/interface/condition.ts b/packages/s2-core/src/common/interface/condition.ts index 8f1440f93f..4b665f336e 100644 --- a/packages/s2-core/src/common/interface/condition.ts +++ b/packages/s2-core/src/common/interface/condition.ts @@ -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 | undefined | null; diff --git a/packages/s2-react/playground/config.tsx b/packages/s2-react/playground/config.tsx index 38bf9ddfb7..b7508f73b5 100644 --- a/packages/s2-react/playground/config.tsx +++ b/packages/s2-react/playground/config.tsx @@ -192,7 +192,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = { return { icon: 'CellUp', fill: '#054', - size: 26, }; }, }, @@ -204,7 +203,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = { return { icon: 'CellUp', fill: '#FF4D4F', - size: 16, }; } }, @@ -216,7 +214,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = { return { icon: 'CellUp', fill: '#FF4D4F', - size: 16, }; }, }, @@ -226,7 +223,6 @@ export const s2ConditionsOptions: SheetComponentOptions['conditions'] = { return { icon: 'CellUp', fill: '#FF4D4F', - size: 16, }; }, }, diff --git a/s2-site/docs/common/conditions.zh.md b/s2-site/docs/common/conditions.zh.md index b707100c20..754ba4f826 100644 --- a/s2-site/docs/common/conditions.zh.md +++ b/s2-site/docs/common/conditions.zh.md @@ -9,46 +9,33 @@ order: 2 功能描述： 配置字段标记。分为文本 (text)，背景 (background)，柱状图 (interval)，图标 (icon)。 -| 参数 | 说明 | 类型 | 默认值 | 必选 | -| ---------- | ---------- | --------------- | ------ | ---- | -| 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`，**必选** -功能描述： 配置条件格式。包括文本 (text)，背景 (background)，柱状图 (interval)。 +功能描述： 配置条件格式。TextCondition，BackgroundCondition，IntervalCondition，IconCondition 具继承于 Condition。 -| 参数 | 说明 | 类型 | 默认值 | 必选 | -|---------|-----------------------------------|------------|----------|-----| -| field | 1. 字段 ID
2. 使用正则表达式匹配字段 ID | `string \| RegExp` | | ✓ | -| mapping | 作用映射函数​ | `function` | | ✓ | +| 参数 | 说明 | 类型 | 默认值 | 必选 | +| ------- | ---------------------------------------------- | ------------------------------------- | ------ | ---- | +| field | 1. 字段 ID
2. 使用正则表达式匹配字段 ID | `string \| RegExp` | | ✓ | +| mapping | 作用映射函数​ | [ConditionMapping](#conditionmapping) | | ✓ | -#### MappingFunction +#### ConditionMapping ```ts -type MappingFunction = ( - fieldValue: number | string | null, - data: Record, - 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 = ( + fieldValue: number | string, + data: RawData, + cell?: DataCell | HeaderCell, +) => ConditionMappingResult; ``` @@ -90,15 +77,13 @@ const options = { ### IconCondition -类型：`object`，**必选**，默认值：`null` +类型：`object`，**必选** -功能描述： 配置图标 (icon) 条件格式。 +功能描述： 配置图标 (icon) 条件格式，和其他 Condition 的唯一区别在于多了 position 参数用于自定义 icon 相对于文本的位置 -| 参数 | 说明 | 类型 | 默认值 | 必选 | -| -------- | ------------ | -------- | ------- | ---- | -| field | 字段 ID | `string` | | ✓ | -| position | icon 相较于文字的位置 | `left \| right` | `right` | | -| mapping | 映射函数 | [MappingFunction](#mappingfunction) | | ✓ | +| 参数 | 说明 | 类型 | 默认值 | 必选 | +| -------- | --------------------- | --------------- | ------- | ---- | +| position | icon 相较于文字的位置 | `left \| right` | `right` | | **icon condition 用法示例：** @@ -121,3 +106,5 @@ const options = { }; ``` + +​ diff --git a/s2-site/docs/manual/basic/conditions.zh.md b/s2-site/docs/manual/basic/conditions.zh.md index 2c3f65dc40..ff0de57905 100644 --- a/s2-site/docs/manual/basic/conditions.zh.md +++ b/s2-site/docs/manual/basic/conditions.zh.md @@ -4,17 +4,19 @@ order: 4 tag: Updated --- -S2 自带字段标记特性。用户可以根据业务语义设置不同的渲染逻辑，实现重点数据的标记和分析。字段标记类型包括： +在数据可视化和分析中，字段标记是一种常用的功能，它允许用户通过可视化的方式强调数据中的关键信息。S2 是一个数据可视化库，支持灵活的字段标记功能： -* 文本 (text) 字段标记 （所有单元格类型） -* 背景 (background) 字段标记 （所有单元格类型） -* 柱状图 (interval) 字段标记 （仅支持数据单元格） -* 图标 (icon) 字段标记 （目前支持透视表数据单元格、行头和列头单元格） +* 文本 (text) 字段标记 +* 背景 (background) 字段标记 +* 柱状图 (interval) 字段标记 +* 图标 (icon) 字段标记 下图直观展示了四种字段标记的形态： preview +**数据单元格完整的支持 4 种字段标记，而角头、行头、列头这些头部单元格只支持文本、背景和图标三种字段标记（柱状图不适用于头部单元格，业务上价值不大）。** + ## 快速上手 `S2` 字段标记特性通过配置 `s2Options` 中 [`Conditions`](/docs/api/general/S2Options#conditions) 属性。 @@ -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`，作用范围为数据单元格 = ( + fieldValue: number | string, + data: RawData, + cell?: DataCell | HeaderCell, +) => ConditionMappingResult; +``` -| 返回值 | 说明 | 类型 | 默认值 | 必选 | -| --------- |---------------------------------------------------------------------------------------------------------------------------| --------- | ------ | ---- | -| fill | 当作用于文本字段标记时，代表**文字填充颜色**
当作用于背景字段标记时，代表**单元格背景填充颜色**
当作用于柱状图字段标记时，代表**柱状图填充颜色**
当作用于图标字段标记时，代表**图标填充颜色**
| `string` | - | ✓ | -| icon | 仅用于**图标**字段标记，指定图标类型 | `string` | - | | -| isCompare | 仅用于**柱状图**字段标记，当为 `true` 时，可以定制柱状图的最大最小值 | `boolean` | - | | -| minValue | 仅用于**柱状图**字段标记且 `isCompare` 为 `true` 时，定制柱状图最小值 | `number` | - | | -| maxValue | 仅用于**柱状图**字段标记且 `isCompare` 为 `true` 时，定制柱状图最大值 | `number` | - | | -| fieldValue | 仅用于**柱状图**字段标记且 `isCompare` 为 `true` 时，定制柱状图的长度 | `number` | - | | +`mapping`接收三个参数，分别是: -> 如果`mapping`函数返回值为空，则表明不渲染该单元格的字段标记 +* fieldValue: 当前单元格的值 +* data: 如果是数据单元格，则是格子对应的数据；如果是角头、行头、列头，则是格子的 meta 信息 +* cell: 对应当前格子的实例，如果前两个参数不满足业务需求，可以通过这个参数获取任意你想要的数据 -​ +不同的字段标记类型所需的返回值类型`ConditionMappingResult`有所不同，主要是泛型`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) 文档。 @@ -117,11 +119,20 @@ const s2Options = { +当同时存在自定义 Icon 时，Condition Icon 单元格 value 是强关联的，所以将 condition icon 放在紧贴文本的左右侧，即： + +* `[header action icons] [condition icon] [text]` +* `[text] [condition icon] [header action icons]` + + + ### 自定义柱状图范围 通过显示指定 `interval` 字段标记中的 `mapping` 函数返回值 `isCompare` 属性值为 `true`，并指定 `maxValue` 和 `minValue` 的值，可以自定义柱状图的区间范围。 > 如果 `mapping 函数` 返回值中的 `isCompare` 属性值为 `false` 或者不返回该属性。此时 `maxValue` 和 `minValue` 会以所有图表数据中该字段的最大最小值为区间范围 +字段标记默认都是使用当前单元格的 value 作为绘制的依据，但在柱状图中，因为可以自定义柱状图的范围，那么也可能需要根据范围，同时对当前的 value 进行处理，使用新的 value 作为绘制的依据，此时可以通过`mapping` 函数返回值中指定`fieldValue`重新指定当前格子的绘制依据。 + `price` 字段使用自定义模式，`cost` 字段使用默认模式： @@ -151,4 +162,10 @@ const s2Options = { +### 区分角头、行头、列头 + +在透视表模式中，如果字段标记对应的`field`是行头或者列头的维度，那么会同时将对应的角头单元格也进行标记，可以通过`mapping` 函数三个参数做区分： + + + ​📊 查看更多 [字段标记示例](/examples/analysis/conditions#intelligent-background)。 diff --git a/s2-site/examples/analysis/conditions/demo/distinguish-cell.ts b/s2-site/examples/analysis/conditions/demo/distinguish-cell.ts new file mode 100644 index 0000000000..256f034aa2 --- /dev/null +++ b/s2-site/examples/analysis/conditions/demo/distinguish-cell.ts @@ -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(); + }); diff --git a/s2-site/examples/analysis/conditions/demo/icon-with-action.ts b/s2-site/examples/analysis/conditions/demo/icon-with-action.ts new file mode 100644 index 0000000000..abc824342f --- /dev/null +++ b/s2-site/examples/analysis/conditions/demo/icon-with-action.ts @@ -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(); + }); diff --git a/s2-site/examples/analysis/conditions/demo/interval.ts b/s2-site/examples/analysis/conditions/demo/interval.ts index a31a322ae7..9b68adf2b8 100644 --- a/s2-site/examples/analysis/conditions/demo/interval.ts +++ b/s2-site/examples/analysis/conditions/demo/interval.ts @@ -1,4 +1,4 @@ -import { PivotSheet, S2Options, S2Options } from '@antv/s2'; +import { PivotSheet, S2Options } from '@antv/s2'; fetch( 'https://gw.alipayobjects.com/os/bmw-prod/2a5dbbc8-d0a7-4d02-b7c9-34f6ca63cff6.json', @@ -24,7 +24,7 @@ fetch( isCompare: true, maxValue: 8000, minValue: 300, - fieldValue: value > 7900 ? 10 : value, + fieldValue: Number(value) > 7900 ? 10 : value, }; }, }, diff --git a/s2-site/examples/analysis/conditions/demo/meta.json b/s2-site/examples/analysis/conditions/demo/meta.json index 5983726005..e897cbc3aa 100644 --- a/s2-site/examples/analysis/conditions/demo/meta.json +++ b/s2-site/examples/analysis/conditions/demo/meta.json @@ -37,12 +37,12 @@ "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/ReYpm%24KcI2/b923ab47-cd74-48fe-aae2-1412091d4a31.png" }, { - "filename": "table-text.ts", + "filename": "icon-with-action.ts", "title": { - "zh": "明细表文本标记", - "en": "Table text condition" + "zh": "图标标记混合自定义 Action Icons", + "en": "Icon condition with action icons" }, - "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/jdTsPFc09l/4795d9f3-f55b-4575-99de-829e0e3ab3db.png" + "screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*wClMR4kLBaoAAAAAAAAAAAAADmJ7AQ/original" }, { "filename": "multi-background.ts", @@ -60,14 +60,6 @@ }, "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/y1IafbmC7W/c79f8906-ca2e-4bbd-b384-e663bde759e4.png" }, - { - "filename": "multi-conditions.ts", - "title": { - "zh": "混合字段标记", - "en": "Multi-conditions" - }, - "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/6FFtlY%240T/792a0865-b01d-4674-a3ef-98da6c5be285.png" - }, { "filename": "bidirectional-interval.ts", "title": { @@ -76,6 +68,15 @@ }, "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/oUICMHjOA/7fd723cb-fc2a-45a5-a0ab-a2840127a48a.png" }, + { + "filename": "multi-conditions.ts", + "title": { + "zh": "混合字段标记", + "en": "Multi-conditions" + }, + "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/6FFtlY%240T/792a0865-b01d-4674-a3ef-98da6c5be285.png" + }, + { "filename": "intelligent-background.ts", "title": { @@ -84,6 +85,22 @@ }, "screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*--3oTK25-wgAAAAAAAAAAAAADmJ7AQ/original", "new": true + }, + { + "filename": "distinguish-cell.ts", + "title": { + "zh": "区分行列角头和数据单元格", + "en": "Distinguish different cell" + }, + "screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*pxw2S5JFzUcAAAAAAAAAAAAADmJ7AQ/original" + }, + { + "filename": "table-text.ts", + "title": { + "zh": "明细表文本标记", + "en": "Table text condition" + }, + "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/jdTsPFc09l/4795d9f3-f55b-4575-99de-829e0e3ab3db.png" } ] } diff --git a/s2-site/examples/analysis/conditions/demo/table-text.ts b/s2-site/examples/analysis/conditions/demo/table-text.ts index ac421e5bca..11e1bb55e2 100644 --- a/s2-site/examples/analysis/conditions/demo/table-text.ts +++ b/s2-site/examples/analysis/conditions/demo/table-text.ts @@ -1,4 +1,4 @@ -import { S2DataConfig, S2Options, S2Options, TableSheet } from '@antv/s2'; +import { S2DataConfig, S2Options, TableSheet } from '@antv/s2'; fetch( 'https://gw.alipayobjects.com/os/bmw-prod/986d48ce-cfdf-475d-980c-553762770928.json',