fix: valueRangeByField => getValueRange()

antvis · Jul 15, 2024 · 84cb88b · 84cb88b
1 parent ebaa6fb
commit 84cb88b
Show file tree

Hide file tree

Showing 6 changed files with 149 additions and 18 deletions.
diff --git a/packages/s2-core/src/cell/data-cell.ts b/packages/s2-core/src/cell/data-cell.ts
@@ -30,6 +30,7 @@ import type {
   MiniChartData,
   MultiData,
   TextTheme,
+  ValueRange,
   ViewMeta,
   ViewMetaData,
   ViewMetaIndexType,
@@ -119,7 +120,7 @@ export class DataCell extends BaseCell<ViewMeta> {
     return [CellBorderPosition.BOTTOM, CellBorderPosition.RIGHT];
   }
 
-  public get valueRangeByField() {
+  public getValueRange(): ValueRange {
     return this.spreadsheet.dataSet.getValueRangeByField(this.meta.valueField);
   }
 

diff --git a/packages/s2-core/src/utils/g-mini-charts.ts b/packages/s2-core/src/utils/g-mini-charts.ts
@@ -262,10 +262,15 @@ export const drawInterval = (cell: DataCell) => {
       return;
     }
 
-    const valueRange = attrs.isCompare ? attrs : cell.valueRangeByField;
-
-    const minValue = parseNumberWithPrecision(valueRange.minValue!);
-    const maxValue = parseNumberWithPrecision(valueRange.maxValue!);
+    const defaultValueRange = cell.getValueRange();
+    const valueRange = attrs.isCompare ? attrs : defaultValueRange;
+
+    const minValue = parseNumberWithPrecision(
+      valueRange.minValue ?? defaultValueRange.minValue!,
+    );
+    const maxValue = parseNumberWithPrecision(
+      valueRange.maxValue ?? defaultValueRange.maxValue!,
+    );
 
     const fieldValue = isNil(attrs?.fieldValue)
       ? parseNumberWithPrecision(cell.getMeta().fieldValue as number)

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
@@ -14,7 +14,7 @@ s2.dataSet.getFieldName('type')
 | -------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
 | fields                                 | 字段信息                           | [Fields](/docs/api/general/S2DataConfig#fields)                                                                                                                                        |                                             |
 | meta                                   | 字段元信息，包含有字段名、格式化等 | [Meta[]](/docs/api/general/S2DataConfig#meta)                                                                                                                                          |                                             |
-| originData                             | 原始数据                           | [RawData](#rawdata)[](#)                                                                                                                                                                |                                             |
+| originData                             | 原始数据                           | [RawData](#rawdata)[](#rawdata)                                                                                                                                                                |                                             |
 | indexesData                            | 多维索引数据                       | Record<string, [RawData](#rawdata)[][] \| [RawData](#rawdata)[]>                                                                                                                                                              |                                             |
 | sortParams                             | 排序配置                           | [SortParams](/docs/api/general/S2DataConfig#sortparams)                                                                                                                                |                                             |
 | filterParams                             | 筛选配置                           | [FilterParam](#filterparam)[]                                                                                                                                |                                             |
@@ -33,8 +33,9 @@ s2.dataSet.getFieldName('type')
 | getCellData                            | 获取单个的单元格数据               | (params: [GetCellDataParams](#getcelldataparams)) => [DataType[]](#datatype)                                                                                                                       |                                             |
 | getCellMultiData                           | 获取批量的单元格数据               | (params?: [GetCellMultiDataParams](#getcellmultidataparams)) => [DataType[]](#datatype)                                                                                       |                                             |
 | moreThanOneValue                       | 是否超过 1 个数值                  | () => [ViewMeta](#viewmeta)                                                                                                                                                                  |                                             |
-| isEmpty                                | 是否为空数据集                     | () => `boolean`                                                                                                                                                                              | `@antv/s2^1.51.1`                          |
-| displayFormattedValueMap                                |  单元格所对应格式化后的值（用于编辑表）                  | `Map<string, string>`                                                                                                                                                                             | `@antv/s2-v1.54.5`                          |
+| isEmpty                                | 是否为空数据集                     | () => `boolean`                                                                                                                                                                              |                          |
+| displayFormattedValueMap                                |  单元格所对应格式化后的值（用于编辑表）                  | `Map<string, string>`                                                                                                                                                                             |                           |
+| getValueRangeByField   |  获取数值最大最小值区间      | `(field: string) => { minValue: number, maxValue: number }`     |   |
 
 ### SimpleData
 

diff --git a/s2-site/docs/manual/basic/conditions.zh.md b/s2-site/docs/manual/basic/conditions.zh.md
@@ -47,7 +47,7 @@ const s2Options = {
 
 [Conditions 属性](/docs/api/general/S2Options#conditions) 可配置四种不同的字段，分别对应四种不同的字段标记。
 
-* `text`，`background` 和 `interval` ,`icon` 均是继承自[Condition](/docs/api/general/S2Options#condition) 数组类型
+* `text`，`background` 和 `interval` ,`icon` 均是继承自 [Condition](/docs/api/general/S2Options#condition) 数组类型
   * 包含 `field` 和 `mapping` 两个字段
   * 一个字段 ID 多次匹配到同一范围的字段标记规则，以最后一个规则为准
 * `icon` 稍有不同，为 [IconCondition](/docs/api/general/S2Options#iconcondition) 数组类型
@@ -85,7 +85,7 @@ const s2Options = {
 
 ### mapping
 
-其中的重点是`mapping`函数，它用于处理字段标记的回调函数，如果`mapping`函数返回值为空，则表明不渲染该单元格的字段标记。
+其中的重点是 `mapping` 函数，它用于处理字段标记的回调函数，如果 `mapping` 函数返回值为空，则表明不渲染该单元格的字段标记。
 
 ```ts
 export type ConditionMapping<T = unknown> = (
@@ -95,13 +95,13 @@ export type ConditionMapping<T = unknown> = (
 ) => ConditionMappingResult<T>;
 ```
 
-`mapping`接收三个参数，分别是:
+`mapping` 接收三个参数，分别是：
 
 * fieldValue: 当前单元格的值
 * data: 如果是数据单元格，则是格子对应的数据；如果是角头、行头、列头，则是格子的 meta 信息
 * cell: 对应当前格子的实例，如果前两个参数不满足业务需求，可以通过这个参数获取任意你想要的数据
 
-不同的字段标记类型所需的返回值类型`ConditionMappingResult<T>`有所不同，主要是泛型`T`不同。S2 提供了完备的类型提示：
+不同的字段标记类型所需的返回值类型 `ConditionMappingResult<T>` 有所不同，主要是泛型 `T`不同。S2 提供了完备的类型提示：
 
 ![类型提示](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*wgC1QoXRWkAAAAAAAAAAAAAADmJ7AQ/original)
 
@@ -113,7 +113,26 @@ export type ConditionMapping<T = unknown> = (
 
 ### 自定义图标位置
 
-通过设置 `icon` 字段标记中的 `position` 属性，可以设置图标位于文本的左侧还是右侧。（目前表头单元格暂不支持切换）
+通过设置 `icon` 字段标记中的 `position` 属性，可以设置图标位于文本的左侧还是右侧。
+
+```ts
+const s2Options = {
+  conditions: {
+    icon: [
+      {
+        field: 'number',
+        position: 'left',
+        mapping() {
+          return {
+            icon: 'CellUp',
+            fill: '#2498D1',
+          };
+        },
+      },
+    ],
+  },
+}
+```
 
 `price` 字段的图标位于文本右侧，`cost` 字段的图标位于文本左侧：
 
@@ -131,9 +150,40 @@ export type ConditionMapping<T = unknown> = (
 ### 自定义柱状图范围
 
 通过显示指定 `interval` 字段标记中的 `mapping` 函数返回值  `isCompare` 属性值为 `true`，并指定 `maxValue` 和 `minValue` 的值，可以自定义柱状图的区间范围。
-> 如果 `mapping 函数` 返回值中的 `isCompare` 属性值为 `false` 或者不返回该属性。此时 `maxValue` 和 `minValue` 会以所有图表数据中该字段的最大最小值为区间范围
 
-字段标记默认都是使用当前单元格的 value 作为绘制的依据，但在柱状图中，因为可以自定义柱状图的范围，那么也可能需要根据范围，同时对当前的 value 进行处理，使用新的 value 作为绘制的依据，此时可以通过`mapping` 函数返回值中指定`fieldValue`重新指定当前格子的绘制依据。
+:::info{title="提示"}
+如果 `mapping` 函数返回值中的 `isCompare` 属性值为 `false` 或者不返回该属性。此时 `maxValue` 和 `minValue` 默认会以所有图表数据中该字段的**最大最小值**为区间范围。
+:::
+
+也可以通过 `cell.getValueRange()` 获取默认的最大最小值数值区间，动态决定是否自定义柱状图范围。
+
+```ts
+const s2Options = {
+  conditions: {
+    interval: [
+      {
+        field: 'number',
+        mapping(value, data, cell) {
+          const defaultValueRange = cell.getValueRange();
+
+          console.log('默认的最大最小值数值区间：', defaultValueRange);
+
+          return {
+            fill: '#80BFFF',
+            // 自定义柱状图范围
+            isCompare: true,
+            maxValue: 8000,
+            minValue: 300,
+            fieldValue: Number(value) > 7900 ? 10 : value,
+          };
+        },
+      },
+    ],
+  }
+}
+```
+
+字段标记默认都是使用当前单元格的 value 作为绘制的依据，但在柱状图中，因为可以自定义柱状图的范围，那么也可能需要根据范围，同时对当前的 value 进行处理，使用新的 value 作为绘制的依据，此时可以通过 `mapping` 函数返回值中指定 `fieldValue` 重新指定当前格子的绘制依据。
 
 `price` 字段使用自定义模式，`cost` 字段使用默认模式：
 
@@ -143,6 +193,23 @@ export type ConditionMapping<T = unknown> = (
 
 当柱状图的区间有正负之分时，并搭配 `mapping` 函数返回值的 `fill` 属性，即可绘制出带有不同颜色的正负双向柱状图：
 
+```ts
+const s2Options = {
+  conditions: {
+    interval: [
+      {
+        field: 'number',
+        mapping(value) {
+          return {
+            fill: value >= 0 ? '#80BFFF' : '#F4664A',
+          };
+        },
+      },
+    ],
+  }
+}
+```
+
 <Playground path="analysis/conditions/demo/bidirectional-interval.ts" rid='bidirectional'></playground>
 
 📊 查看更多 [字段标记示例](/examples/analysis/conditions#bidirectional-interval)。
@@ -151,7 +218,33 @@ export type ConditionMapping<T = unknown> = (
 
 `S2` 的底层图形绘制采用 [AntV/g](https://g.antv.antgroup.com/guide/getting-started) 渲染引擎 ，借助其强大的绘制能力，`fill` 字段不仅仅是颜色属性，还可以使用 [渐变色](https://g.antv.antgroup.com/api/css/gradient)、[纹理](https://g.antv.antgroup.com/api/css/pattern) 等。
 
+```ts
+const s2Options = {
+  conditions: {
+    interval: [
+      {
+        field: 'number',
+        mapping(fieldValue) {
+          const maxValue = 7789;
+          const minValue = 352;
+          const rage = (fieldValue - minValue) / (maxValue - minValue);
+
+          const color = getGradient(rage, '#95F0FF', '#3A9DBF');
+
+          return {
+            fill: `l(0) 0:#95F0FF 1:${color}`,
+            isCompare: true,
+            maxValue,
+          };
+        },
+      },
+    ],
+  }
+}
+```
+
 `price` 字段使用渐变色：
+
 <Playground path="analysis/conditions/demo/gradient-interval.ts" rid='gradient'></playground>
 
 📊 查看更多 [字段标记示例](/examples/analysis/conditions#gradient-interval)。
@@ -162,11 +255,30 @@ export type ConditionMapping<T = unknown> = (
 当标记背景颜色较暗且文本颜色与背景颜色组合不符合 WCAG2.0 指南的 [AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) 级标准时，文本颜色将变为白色。当标记背景颜色明亮时，文本颜色默认为黑色。
 优先级： `background condition` 的 `intelligentReverseTextColor` < `text condition` 的 `fill`
 
-<Playground path="analysis/conditions/demo/intelligent-background.ts" rid='intelligentReverseTextColor'></playground>
+```ts
+const s2Options = {
+  conditions: {
+    background: [
+      {
+        field: 'number',
+        mapping() {
+          return {
+            // fill 是背景字段下唯一必须的字段，用于指定文本颜色
+            fill: '#000',
+            intelligentReverseTextColor: true,
+          };
+        },
+      },
+    ],
+  }
+}
+```
+
+<Playground path="analysis/conditions/demo/intelligent-background.ts" rid='intelligent-reverse-text-color'></playground>
 
 ### 区分角头、行头、列头
 
-在透视表模式中，如果字段标记对应的`field`是行头或者列头的维度，那么会同时将对应的角头单元格也进行标记，可以通过`mapping` 函数三个参数做区分：
+在透视表模式中，如果字段标记对应的 `field` 是行头或者列头的维度，那么会同时将对应的角头单元格也进行标记，可以通过 `mapping` 函数三个参数做区分：
 
 <Playground path="analysis/conditions/demo/distinguish-cell.ts" rid='distinguish-cell'></playground>
 

diff --git a/s2-site/docs/manual/migration-v2.zh.md b/s2-site/docs/manual/migration-v2.zh.md
@@ -787,6 +787,13 @@ s2.on(S2Event.GLOBAL_LINK_FIELD_JUMP, (data) => {
 
 具体请查看 [链接跳转](/manual/advanced/interaction/link-jump) 相关文档。
 
+### 数值单元格获取数值范围区间方式变更
+
+```diff
+- dataCell.valueRangeByField
++ dataCell.getValueRange()
+```
+
 ### 组件层 <Badge>@antv/s2-react</Badge>
 
 #### 支持 React 18 和 Ant Design 5.0

diff --git a/s2-site/examples/analysis/conditions/demo/interval.ts b/s2-site/examples/analysis/conditions/demo/interval.ts
@@ -17,11 +17,16 @@ fetch(
         interval: [
           {
             field: 'number',
-            mapping(value) {
+            mapping(value, data, cell) {
+              const defaultValueRange = cell.getValueRange();
+
+              console.log('默认数据区间:', defaultValueRange);
+
               return {
                 fill: '#80BFFF',
                 // 自定义柱状图范围
                 isCompare: true,
+                // 自定义最大值和最小值
                 maxValue: 8000,
                 minValue: 300,
                 fieldValue: Number(value) > 7900 ? 10 : value,