Merge pull request #3895 from VisActor/feat/gauge-clip

feat: gauge support clip when mark outof axis. close#3859

Author: xile611

common/changes/@visactor/vchart/feat-gauge-clip_2025-04-15-08-24.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "feat: gauge support clip when mark outof axis. close#3859",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

docs/assets/option/en/series/circular-progress.md

@@ -16,6 +16,30 @@
   seriesMarks = ['progress', 'track']
 ) }}
 
+#${prefix} tickMask(Object)
+Tick mode display. Supported since `1.4.0` version.
+
+##${prefix} angle(number)
+Default width of a single tick, angle value.
+
+##${prefix} offsetAngle(number)
+Offset angle of a single tick, angle value.
+
+##${prefix} forceAlign(boolean)
+Whether the primitives under the tick mask are forced to align with the tick edge.
+
+##${prefix} style(Object)
+{{ use: mark-style(
+markName = 'area'
+) }}
+
+{{ use: mark-area(
+prefix = '##' + ${prefix}
+) }}
+
+#${prefix} clamp(boolean) = false
+Supported since `1.13.9` version, whether the out-of-axis range is clipped (except tick mode, because tick mode has its own clipping).
+
 #${prefix} categoryField(string|string[])
 
 Category field, mapped to the radius axis. Can be declared as an array type, internally grouping data according to the declared fields.

docs/assets/option/en/series/gauge.md

@@ -14,6 +14,30 @@
   seriesMarks = ['segment'],
 ) }}
 
+#${prefix} tickMask(Object)
+Tick mode display. Supported since `1.4.0` version.
+
+##${prefix} angle(number)
+Default width of a single tick, angle value.
+
+##${prefix} offsetAngle(number)
+Offset angle of a single tick, angle value.
+
+##${prefix} forceAlign(boolean)
+Whether the primitives under the tick mask are forced to align with the tick edge.
+
+##${prefix} style(Object)
+{{ use: mark-style(
+markName = 'area'
+) }}
+
+{{ use: mark-area(
+prefix = '##' + ${prefix}
+) }}
+
+#${prefix} clamp(boolean) = false
+Supported since `1.13.9` version, whether the out-of-axis range is clipped (except tick mode, because tick mode has its own clipping).
+
 #${prefix} padAngle(number)
 
 Configure the angle between sectors.

docs/assets/option/en/series/linear-progress.md

@@ -78,3 +78,6 @@ Background bar style configuration.
 
 Progress bar width.
 In pixel (px) units.
+
+#${prefix} clamp(boolean) = false
+Supported since `1.13.9` version, whether the out-of-axis range is clipped.

docs/assets/option/zh/series/circular-progress.md

@@ -16,6 +16,30 @@
   seriesMarks = ['progress', 'track']
 ) }}
 
+#${prefix} tickMask(Object)
+tick 模式显示. 自`1.4.0`版本支持。
+
+##${prefix} angle(number)
+单个 tick 的默认宽度，角度值。
+
+##${prefix} offsetAngle(number)
+单个 tick 的偏移角度，角度值。
+
+##${prefix} forceAlign(boolean)
+tick mask 下的图元是否强制和 tick 的边线对齐。
+
+##${prefix} style(Object)
+{{ use: mark-style(
+  markName = 'area'
+) }}
+
+{{ use: mark-area(
+  prefix = '##' + ${prefix}
+) }}
+
+#${prefix} clamp(boolean) = false
+自`1.13.9`版本支持，超出轴范围是否被裁剪（除tick模式外, 因为tick模式自带裁剪）。
+
 #${prefix} categoryField(string|string[])
 
 类别字段，映射到半径轴。可以声明为数组类型，内部会依次按照声明的字段进行数据分组。

docs/assets/option/zh/series/gauge.md

@@ -14,6 +14,30 @@
   seriesMarks = ['segment'],
 ) }}
 
+#${prefix} tickMask(Object)
+tick 模式显示. 自`1.4.0`版本支持。
+
+##${prefix} angle(number)
+单个 tick 的默认宽度，角度值。
+
+##${prefix} offsetAngle(number)
+单个 tick 的偏移角度，角度值。
+
+##${prefix} forceAlign(boolean)
+tick mask 下的图元是否强制和 tick 的边线对齐。
+
+##${prefix} style(Object)
+{{ use: mark-style(
+  markName = 'area'
+) }}
+
+{{ use: mark-area(
+  prefix = '##' + ${prefix}
+) }}
+
+#${prefix} clamp(boolean) = false
+自`1.13.9`版本支持，超出轴范围是否被裁剪（除tick模式外, 因为tick模式自带裁剪）。
+
 #${prefix} padAngle(number)
 
 配置扇区间隔角度。

docs/assets/option/zh/series/linear-progress.md

@@ -78,3 +78,6 @@
 
 进度条宽度。
 以像素值(px)为单位。
+
+#${prefix} clamp(boolean) = false
+自`1.13.9`版本支持，超出轴范围是否被裁剪。

packages/vchart/src/chart/progress/linear/linear-progress-transformer.ts

@@ -12,7 +12,7 @@ export class LinearProgressChartSpecTransformer<
   }
 
   protected _getDefaultSeriesSpec(spec: T): ILinearProgressChartSpec {
-    const series = super._getDefaultSeriesSpec(spec, ['bandWidth', 'progress', 'track']);
+    const series = super._getDefaultSeriesSpec(spec, ['bandWidth', 'progress', 'track', 'clamp']);
     series.direction = spec.direction ?? 'horizontal';
 
     series.cornerRadius = spec.cornerRadius ?? 0;

packages/vchart/src/series/gauge/gauge.ts

@@ -17,6 +17,7 @@ import { GaugeSeriesSpecTransformer } from './gauge-transformer';
 import { registerArcMark } from '../../mark/arc';
 import { registerPolarLinearAxis } from '../../component/axis/polar';
 import { AttributeLevel } from '../../constant/attribute';
+import { valueInScaleRange } from '../../util';
 
 export class GaugeSeries<T extends IGaugeSeriesSpec = IGaugeSeriesSpec> extends ProgressLikeSeries<T> {
   static readonly type: string = SeriesTypeEnum.gauge;
@@ -157,19 +158,21 @@ export class GaugeSeries<T extends IGaugeSeriesSpec = IGaugeSeriesSpec> extends
   protected _getAngleValueStartWithoutMask(datum: Datum) {
     const startAngle = this._getAngleValueStartWithoutPadAngle(datum);
     const endAngle = this._getAngleValueEndWithoutPadAngle(datum);
-    return clamper(
+    const angle = clamper(
       startAngle,
       (startAngle + endAngle) / 2
     )(startAngle + (endAngle > startAngle ? 1 : -1) * Math.abs(this._padAngle / 2));
+    return this._spec.clamp ? valueInScaleRange(angle, this.angleAxisHelper.getScale(0)) : angle;
   }
 
   protected _getAngleValueEndWithoutMask(datum: Datum) {
     const startAngle = this._getAngleValueStartWithoutPadAngle(datum);
     const endAngle = this._getAngleValueEndWithoutPadAngle(datum);
-    return clamper(
+    const angle = clamper(
       endAngle,
       (startAngle + endAngle) / 2
     )(endAngle - (endAngle > startAngle ? 1 : -1) * Math.abs(this._padAngle / 2));
+    return this._spec.clamp ? valueInScaleRange(angle, this.angleAxisHelper.getScale(0)) : angle;
   }
 
   protected _getAngleValueStartWithoutPadAngle(datum: Datum) {

packages/vchart/src/series/polar/progress-like/interface.ts

@@ -33,6 +33,13 @@ export interface IProgressLikeSeriesSpec extends IPolarSeriesSpec {
    * @since 1.4.0
    */
   tickMask?: Omit<IMarkSpec<IArcMarkSpec>, 'state'> & ITickMaskSpec;
+
+  /**
+   * 超出轴范围是否被裁剪（除tick模式外, 因为tick模式自带裁剪）
+   * @since 1.13.9
+   * @default false
+   */
+  clamp?: boolean;
 }
 
 export interface IProgressLikeSeriesTheme extends IPolarSeriesTheme {