Merge pull request #3750 from VisActor/feat/linear-scale-clamp

feat: support `clamp` in linear scales

common/changes/@visactor/vchart/feat-linear-scale-clamp_2025-02-20-11-12.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "'feat: support `clamp` in linear scales, #3738'",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

docs/assets/option/en/common/visual-scale-spec.md

@@ -189,3 +189,26 @@ const scale = {
 // scale('b') => 'blue'
 // scale('d') => 'red'
 ```
+
+#${prefix} clamp(boolean)
+
+If clamp is enabled, the return value of the scale is always within the scale’s range.
+
+`1.13.6` version supported, only supported in `type=linear`.
+
+Example:
+
+```ts
+const scale = {
+  type: 'linear',
+  domain: [100, 200],
+  range: [0, 50],
+  clamp: true
+};
+//
+// scale(100) => 0
+// scale(150) => 25
+// scale(200) => 50
+// scale(0) => 0
+// scale(300) => 50
+```

docs/assets/option/zh/common/visual-scale-spec.md

@@ -189,3 +189,26 @@ const scale = {
 // scale('b') => 'blue'
 // scale('d') => 'red'
 ```
+
+#${prefix} clamp(boolean)=false
+
+如果 clamp 为 true，则 scale 的返回值总是处于 scale 的 range 范围内。
+
+`1.13.6`版本开始支持，仅在 `type=linear` 时生效。
+
+示例：
+
+```ts
+const scale = {
+  type: 'linear',
+  domain: [100, 200],
+  range: [0, 50],
+  clamp: true
+};
+//
+// scale(100) => 0
+// scale(150) => 25
+// scale(200) => 50
+// scale(0) => 0
+// scale(300) => 50
+```

packages/vchart/src/chart/base/base-chart.ts

@@ -709,6 +709,7 @@ export class BaseChart<T extends IChartSpec> extends CompilableBase implements I
           Object.prototype.hasOwnProperty.call(tempSpec, 'range') && (colorScaleSpec.range = tempSpec.range);
           Object.prototype.hasOwnProperty.call(tempSpec, 'specified') &&
             (colorScaleSpec.specified = tempSpec.specified);
+          Object.prototype.hasOwnProperty.call(tempSpec, 'clamp') && (colorScaleSpec.clamp = tempSpec.clamp);
         }
       }
     }

packages/vchart/src/scale/global-scale.ts

@@ -1,6 +1,6 @@
 import type { IGlobalScale } from './interface';
 import { isArray, isEmpty, isEqual, isNil } from '@visactor/vutils';
-import type { IBaseScale, OrdinalScale } from '@visactor/vscale';
+import type { IBaseScale, LinearScale, OrdinalScale } from '@visactor/vscale';
 import { isContinuous } from '@visactor/vscale';
 import type { IChart } from '../chart/interface';
 import type { IChartSpec } from '../typings/spec';
@@ -51,6 +51,11 @@ export class GlobalScale implements IGlobalScale {
     if (s.specified && (<OrdinalScale>scale).specified) {
       (<OrdinalScale>scale).specified(s.specified);
     }
+
+    if (s.clamp && (<LinearScale>scale).clamp) {
+      (<LinearScale>scale).clamp(s.clamp);
+    }
+
     return scale;
   }
 

packages/vchart/src/typings/visual.ts

@@ -38,6 +38,13 @@ export interface IVisualSpecBase<D, T> {
    * @since 1.1.0
    */
   specified?: { [key: string]: unknown };
+  /**
+   * enable clamp in linear scale
+   * If clamp is enabled, the return value of the scale is always within the scale’s range.
+   * @since 1.13.6
+   * @default false
+   */
+  clamp?: boolean;
 }
 // 用来给用户进行mark.style上的映射配置。所以要配置数据维度
 export interface IVisualSpecStyle<D, T> extends IVisualSpecBase<D, T> {

packages/vchart/src/util/scale.ts

@@ -64,6 +64,10 @@ function initScaleWithSpec(scale: IBaseScale, spec: IVisualSpecBase<any, any>) {
   if (spec.specified && (<OrdinalScale>scale).specified) {
     (<OrdinalScale>scale).specified(spec.specified);
   }
+
+  if (spec.clamp && (<LinearScale>scale).clamp) {
+    (<LinearScale>scale).clamp(spec.clamp);
+  }
 }
 
 /**