zrender-nightly 5.7.0-dev.20250620 → 5.7.0-dev.20250622

package/src/graphic/helper/parseText.ts

@@ -3,11 +3,16 @@ import {
     extend,
     retrieve2,
     retrieve3,
-    reduce
+    reduce,
 } from '../../core/util';
-import { TextAlign, TextVerticalAlign, ImageLike, Dictionary } from '../../core/types';
-import { TextStyleProps } from '../Text';
-import { getLineHeight, getWidth, parsePercent } from '../../contain/text';
+import { TextAlign, TextVerticalAlign, ImageLike, Dictionary, NullUndefined } from '../../core/types';
+import { DefaultTextStyle, TextStyleProps } from '../Text';
+import {
+    adjustTextX,
+    adjustTextY,
+    ensureFontMeasureInfo, FontMeasureInfo, getLineHeight, measureCharWidth, measureWidth, parsePercent,
+} from '../../contain/text';
+import BoundingRect, { BoundingRectIntersectOpt } from '../../core/BoundingRect';
 
 const STYLE_REG = /\{([a-zA-Z0-9_]+)\|([^}]*)\}/g;
 
@@ -23,15 +28,12 @@ interface InnerTruncateOption {
 }
 
 interface InnerPreparedTruncateOption extends Required<InnerTruncateOption> {
-    font: string
-
     ellipsis: string
     ellipsisWidth: number
     contentWidth: number
 
     containerWidth: number
-    cnCharWidth: number
-    ascCharWidth: number
+    fontMeasureInfo: FontMeasureInfo
 }
 
 /**
@@ -44,8 +46,25 @@ export function truncateText(
     ellipsis?: string,
     options?: InnerTruncateOption
 ): string {
+    const out = {} as Parameters<typeof truncateText2>[0];
+    truncateText2(out, text, containerWidth, font, ellipsis, options);
+    return out.text;
+}
+
+// PENDING: not sure whether `truncateText` is used outside zrender, since it has an `export`
+// specifier. So keep it and perform the interface modification in `truncateText2`.
+function truncateText2(
+    out: {text: string, isTruncated: boolean},
+    text: string,
+    containerWidth: number,
+    font: string,
+    ellipsis?: string,
+    options?: InnerTruncateOption
+): void {
     if (!containerWidth) {
-        return '';
+        out.text = '';
+        out.isTruncated = false;
+        return;
     }
 
     const textLines = (text + '').split('\n');
@@ -53,11 +72,16 @@ export function truncateText(
 
     // FIXME
     // It is not appropriate that every line has '...' when truncate multiple lines.
+    let isTruncated = false;
+    const truncateOut = {} as Parameters<typeof truncateSingleLine>[0];
     for (let i = 0, len = textLines.length; i < len; i++) {
-        textLines[i] = truncateSingleLine(textLines[i], options as InnerPreparedTruncateOption);
+        truncateSingleLine(truncateOut, textLines[i], options as InnerPreparedTruncateOption);
+        textLines[i] = truncateOut.textLine;
+        isTruncated = isTruncated || truncateOut.isTruncated;
     }
 
-    return textLines.join('\n');
+    out.text = textLines.join('\n');
+    out.isTruncated = isTruncated;
 }
 
 function prepareTruncateOptions(
@@ -69,16 +93,11 @@ function prepareTruncateOptions(
     options = options || {};
     let preparedOpts = extend({}, options) as InnerPreparedTruncateOption;
 
-    preparedOpts.font = font;
     ellipsis = retrieve2(ellipsis, '...');
     preparedOpts.maxIterations = retrieve2(options.maxIterations, 2);
     const minChar = preparedOpts.minChar = retrieve2(options.minChar, 0);
-    // FIXME
-    // Other languages?
-    preparedOpts.cnCharWidth = getWidth('国', font);
-    // FIXME
-    // Consider proportional font?
-    const ascCharWidth = preparedOpts.ascCharWidth = getWidth('a', font);
+    const fontMeasureInfo = preparedOpts.fontMeasureInfo = ensureFontMeasureInfo(font);
+    const ascCharWidth = fontMeasureInfo.asciiCharWidth;
     preparedOpts.placeholder = retrieve2(options.placeholder, '');
 
     // Example 1: minChar: 3, text: 'asdfzxcv', truncate result: 'asdf', but not: 'a...'.
@@ -88,7 +107,7 @@ function prepareTruncateOptions(
         contentWidth -= ascCharWidth;
     }
 
-    let ellipsisWidth = getWidth(ellipsis, font);
+    let ellipsisWidth = measureWidth(fontMeasureInfo, ellipsis);
     if (ellipsisWidth > contentWidth) {
         ellipsis = '';
         ellipsisWidth = 0;
@@ -104,19 +123,27 @@ function prepareTruncateOptions(
     return preparedOpts;
 }
 
-function truncateSingleLine(textLine: string, options: InnerPreparedTruncateOption): string {
+function truncateSingleLine(
+    out: {textLine: string, isTruncated: boolean},
+    textLine: string,
+    options: InnerPreparedTruncateOption
+): void {
     const containerWidth = options.containerWidth;
-    const font = options.font;
     const contentWidth = options.contentWidth;
+    const fontMeasureInfo = options.fontMeasureInfo;
 
     if (!containerWidth) {
-        return '';
+        out.textLine = '';
+        out.isTruncated = false;
+        return;
     }
 
-    let lineWidth = getWidth(textLine, font);
+    let lineWidth = measureWidth(fontMeasureInfo, textLine);
 
     if (lineWidth <= containerWidth) {
-        return textLine;
+        out.textLine = textLine;
+        out.isTruncated = false;
+        return;
     }
 
     for (let j = 0; ; j++) {
@@ -126,30 +153,32 @@ function truncateSingleLine(textLine: string, options: InnerPreparedTruncateOpti
         }
 
         const subLength = j === 0
-            ? estimateLength(textLine, contentWidth, options.ascCharWidth, options.cnCharWidth)
+            ? estimateLength(textLine, contentWidth, fontMeasureInfo)
             : lineWidth > 0
             ? Math.floor(textLine.length * contentWidth / lineWidth)
             : 0;
 
         textLine = textLine.substr(0, subLength);
-        lineWidth = getWidth(textLine, font);
+        lineWidth = measureWidth(fontMeasureInfo, textLine);
     }
 
     if (textLine === '') {
         textLine = options.placeholder;
     }
 
-    return textLine;
+    out.textLine = textLine;
+    out.isTruncated = true;
 }
 
 function estimateLength(
-    text: string, contentWidth: number, ascCharWidth: number, cnCharWidth: number
+    text: string,
+    contentWidth: number,
+    fontMeasureInfo: FontMeasureInfo
 ): number {
     let width = 0;
     let i = 0;
     for (let len = text.length; i < len && width < contentWidth; i++) {
-        const charCode = text.charCodeAt(i);
-        width += (0 <= charCode && charCode <= 127) ? ascCharWidth : cnCharWidth;
+        width += measureCharWidth(fontMeasureInfo, text.charCodeAt(i));
     }
     return i;
 }
@@ -159,41 +188,57 @@ export interface PlainTextContentBlock {
     // Line height of actual content.
     calculatedLineHeight: number
 
+    // Calculated based on the text.
     contentWidth: number
     contentHeight: number
 
+    // i.e., `retrieve2(style.width/height, contentWidth/contentHeight)`
     width: number
     height: number
 
-    /**
-     * Real text width containing padding.
-     * It should be the same as `width` if background is rendered
-     * and `width` is set by user.
-     */
+    // i.e., `contentBlock.width/height + style.padding`
+    // `borderWidth` is not included here, because historically Path is placed regardless of `lineWidth`,
+    // and `outerWidth`/`outerHeight` is used to calculate placement.
     outerWidth: number
     outerHeight: number
 
     lines: string[]
+
+    // Be `true` if and only if the result text is modified due to overflow, due to
+    // settings on either `overflow` or `lineOverflow`
+    isTruncated: boolean
 }
 
 export function parsePlainText(
     text: string,
-    style?: TextStyleProps
+    style: Omit<TextStyleProps, 'align' | 'verticalAlign'>, // Exclude props in DefaultTextStyle
+    defaultOuterWidth: number | NullUndefined,
+    defaultOuterHeight: number | NullUndefined
 ): PlainTextContentBlock {
     text != null && (text += '');
 
     // textPadding has been normalized
     const overflow = style.overflow;
     const padding = style.padding as number[];
+    const paddingH = padding ? padding[1] + padding[3] : 0;
+    const paddingV = padding ? padding[0] + padding[2] : 0;
     const font = style.font;
     const truncate = overflow === 'truncate';
     const calculatedLineHeight = getLineHeight(font);
     const lineHeight = retrieve2(style.lineHeight, calculatedLineHeight);
-    const bgColorDrawn = !!(style.backgroundColor);
 
     const truncateLineOverflow = style.lineOverflow === 'truncate';
+    let isTruncated = false;
 
     let width = style.width;
+    if (width == null && defaultOuterWidth != null) {
+        width = defaultOuterWidth - paddingH;
+    }
+    let height = style.height;
+    if (height == null && defaultOuterHeight != null) {
+        height = defaultOuterHeight - paddingV;
+    }
+
     let lines: string[];
 
     if (width != null && (overflow === 'break' || overflow === 'breakAll')) {
@@ -203,14 +248,18 @@ export function parsePlainText(
         lines = text ? text.split('\n') : [];
     }
 
-    const contentHeight = lines.length * lineHeight;
-    const height = retrieve2(style.height, contentHeight);
+    let contentHeight = lines.length * lineHeight;
+    if (height == null) {
+        height = contentHeight;
+    }
 
     // Truncate lines.
     if (contentHeight > height && truncateLineOverflow) {
         const lineCount = Math.floor(height / lineHeight);
 
+        isTruncated = isTruncated || (lines.length > lineCount);
         lines = lines.slice(0, lineCount);
+        contentHeight = lines.length * lineHeight;
 
         // TODO If show ellipse for line truncate
         // if (style.ellipsis) {
@@ -228,33 +277,29 @@ export function parsePlainText(
             placeholder: style.placeholder
         });
         // Having every line has '...' when truncate multiple lines.
+        const singleOut = {} as Parameters<typeof truncateSingleLine>[0];
         for (let i = 0; i < lines.length; i++) {
-            lines[i] = truncateSingleLine(lines[i], options);
+            truncateSingleLine(singleOut, lines[i], options);
+            lines[i] = singleOut.textLine;
+            isTruncated = isTruncated || singleOut.isTruncated;
         }
     }
 
     // Calculate real text width and height
     let outerHeight = height;
     let contentWidth = 0;
+    const fontMeasureInfo = ensureFontMeasureInfo(font);
     for (let i = 0; i < lines.length; i++) {
-        contentWidth = Math.max(getWidth(lines[i], font), contentWidth);
+        contentWidth = Math.max(measureWidth(fontMeasureInfo, lines[i]), contentWidth);
     }
     if (width == null) {
-        // When width is not explicitly set, use outerWidth as width.
+        // When width is not explicitly set, use contentWidth as width.
         width = contentWidth;
     }
 
-    let outerWidth = contentWidth;
-    if (padding) {
-        outerHeight += padding[0] + padding[2];
-        outerWidth += padding[1] + padding[3];
-        width += padding[1] + padding[3];
-    }
-
-    if (bgColorDrawn) {
-        // When render background, outerWidth should be the same as width.
-        outerWidth = width;
-    }
+    let outerWidth = width;
+    outerHeight += paddingV;
+    outerWidth += paddingH;
 
     return {
         lines: lines,
@@ -265,17 +310,21 @@ export function parsePlainText(
         calculatedLineHeight: calculatedLineHeight,
         contentWidth: contentWidth,
         contentHeight: contentHeight,
-        width: width
+        width: width,
+        isTruncated: isTruncated
     };
 }
 
 class RichTextToken {
     styleName: string
     text: string
+
+    // Includes `tokenStyle.padding`
     width: number
     height: number
 
     // Inner height exclude padding
+    // i.e., `retrieve2(tokenStyle.height, token.contentHeight)`
     innerHeight: number
 
     // Width and height of actual text content.
@@ -304,16 +353,22 @@ class RichTextLine {
     }
 }
 export class RichTextContentBlock {
-    // width/height of content
+    // i.e. `retrieve2(outermostStyle.width, contentWidth)`.
+    // exclude outermost style.padding.
     width: number = 0
     height: number = 0
-    // Calculated text height
+    // Calculated text width/height based on content (including tokenStyle.padding).
     contentWidth: number = 0
     contentHeight: number = 0
-    // outerWidth/outerHeight with padding
+    // i.e., contentBlock.width/height + outermostStyle.padding
+    // `borderWidth` is not included here, because historically Path is placed regardless of `lineWidth`,
+    // and `outerWidth`/`outerHeight` is used to calculate placement.
     outerWidth: number = 0
     outerHeight: number = 0
     lines: RichTextLine[] = []
+    // Be `true` if and only if the result text is modified due to overflow, due to
+    // settings on either `overflow` or `lineOverflow`
+    isTruncated: boolean = false
 }
 
 type WrapInfo = {
@@ -326,7 +381,13 @@ type WrapInfo = {
  * Also consider 'bbbb{a|xxx\nzzz}xxxx\naaaa'.
  * If styleName is undefined, it is plain text.
  */
-export function parseRichText(text: string, style: TextStyleProps) {
+export function parseRichText(
+    text: string,
+    style: Omit<TextStyleProps, 'align' | 'verticalAlign'>, // Exclude props in DefaultTextStyle
+    defaultOuterWidth: number | NullUndefined,
+    defaultOuterHeight: number | NullUndefined,
+    topTextAlign: TextAlign
+): RichTextContentBlock {
     const contentBlock = new RichTextContentBlock();
 
     text != null && (text += '');
@@ -334,8 +395,19 @@ export function parseRichText(text: string, style: TextStyleProps) {
         return contentBlock;
     }
 
-    const topWidth = style.width;
-    const topHeight = style.height;
+    const stlPadding = style.padding as number[];
+    const stlPaddingH = stlPadding ? stlPadding[1] + stlPadding[3] : 0;
+    const stlPaddingV = stlPadding ? stlPadding[0] + stlPadding[2] : 0;
+
+    let topWidth = style.width;
+    if (topWidth == null && defaultOuterWidth != null) {
+        topWidth = defaultOuterWidth - stlPaddingH;
+    }
+    let topHeight = style.height;
+    if (topHeight == null && defaultOuterHeight != null) {
+        topHeight = defaultOuterHeight - stlPaddingV;
+    }
+
     const overflow = style.overflow;
     let wrapInfo: WrapInfo = (overflow === 'break' || overflow === 'breakAll') && topWidth != null
         ? {width: topWidth, accumWidth: 0, breakAll: overflow === 'breakAll'}
@@ -362,10 +434,9 @@ export function parseRichText(text: string, style: TextStyleProps) {
     let calculatedHeight = 0;
     let calculatedWidth = 0;
 
-    const stlPadding = style.padding as number[];
-
     const truncate = overflow === 'truncate';
     const truncateLine = style.lineOverflow === 'truncate';
+    const tmpTruncateOut = {} as Parameters<typeof truncateText2>[0];
 
     // let prevToken: RichTextToken;
 
@@ -401,17 +472,18 @@ export function parseRichText(text: string, style: TextStyleProps) {
 
             textPadding && (tokenHeight += textPadding[0] + textPadding[2]);
             token.height = tokenHeight;
-            // Inlcude padding in lineHeight.
+            // Include padding in lineHeight.
             token.lineHeight = retrieve3(
                 tokenStyle.lineHeight, style.lineHeight, tokenHeight
             );
 
-            token.align = tokenStyle && tokenStyle.align || style.align;
+            token.align = tokenStyle && tokenStyle.align || topTextAlign;
             token.verticalAlign = tokenStyle && tokenStyle.verticalAlign || 'middle';
 
             if (truncateLine && topHeight != null && calculatedHeight + token.lineHeight > topHeight) {
                 // TODO Add ellipsis on the previous token.
                 // prevToken.text =
+                const originalLength = contentBlock.lines.length;
                 if (j > 0) {
                     line.tokens = line.tokens.slice(0, j);
                     finishLine(line, lineWidth, lineHeight);
@@ -420,6 +492,7 @@ export function parseRichText(text: string, style: TextStyleProps) {
                 else {
                     contentBlock.lines = contentBlock.lines.slice(0, i);
                 }
+                contentBlock.isTruncated = contentBlock.isTruncated || (contentBlock.lines.length < originalLength);
                 break outer;
             }
 
@@ -432,7 +505,7 @@ export function parseRichText(text: string, style: TextStyleProps) {
                 token.percentWidth = styleTokenWidth;
                 pendingList.push(token);
 
-                token.contentWidth = getWidth(token.text, font);
+                token.contentWidth = measureWidth(ensureFontMeasureInfo(font), token.text);
                 // Do not truncate in this case, because there is no user case
                 // and it is too complicated.
             }
@@ -461,15 +534,18 @@ export function parseRichText(text: string, style: TextStyleProps) {
                         token.width = token.contentWidth = 0;
                     }
                     else {
-                        token.text = truncateText(
+                        truncateText2(
+                            tmpTruncateOut,
                             token.text, remainTruncWidth - paddingH, font, style.ellipsis,
                             {minChar: style.truncateMinChar}
                         );
-                        token.width = token.contentWidth = getWidth(token.text, font);
+                        token.text = tmpTruncateOut.text;
+                        contentBlock.isTruncated = contentBlock.isTruncated || tmpTruncateOut.isTruncated;
+                        token.width = token.contentWidth = measureWidth(ensureFontMeasureInfo(font), token.text);
                     }
                 }
                 else {
-                    token.contentWidth = getWidth(token.text, font);
+                    token.contentWidth = measureWidth(ensureFontMeasureInfo(font), token.text);
                 }
             }
 
@@ -489,10 +565,8 @@ export function parseRichText(text: string, style: TextStyleProps) {
     contentBlock.contentHeight = calculatedHeight;
     contentBlock.contentWidth = calculatedWidth;
 
-    if (stlPadding) {
-        contentBlock.outerWidth += stlPadding[1] + stlPadding[3];
-        contentBlock.outerHeight += stlPadding[0] + stlPadding[2];
-    }
+    contentBlock.outerWidth += stlPaddingH;
+    contentBlock.outerHeight += stlPaddingV;
 
     for (let i = 0; i < pendingList.length; i++) {
         const token = pendingList[i];
@@ -544,10 +618,12 @@ function pushTokens(
             strLines = res.lines;
         }
     }
-    else {
+
+    if (!strLines) {
         strLines = str.split('\n');
     }
 
+    const fontMeasureInfo = ensureFontMeasureInfo(font);
     for (let i = 0; i < strLines.length; i++) {
         const text = strLines[i];
         const token = new RichTextToken();
@@ -560,8 +636,8 @@ function pushTokens(
         }
         else {
             token.width = linesWidths
-                ? linesWidths[i] // Caculated width in the wrap
-                : getWidth(text, font);
+                ? linesWidths[i] // Calculated width in the wrap
+                : measureWidth(fontMeasureInfo, text);
         }
 
         // The first token should be appended to the last line if not new line.
@@ -621,6 +697,11 @@ function isWordBreakChar(ch: string) {
     return true;
 }
 
+/**
+ * NOTE: The current strategy is that if no enough space, all the text is
+ * still displayed, regardless of overflow.
+ * A clip path can be used to completely avoid overflow.
+ */
 function wrapText(
     text: string,
     font: string,
@@ -634,6 +715,7 @@ function wrapText(
     let currentWord = '';
     let currentWordWidth = 0;
     let accumWidth = 0;
+    const fontMeasureInfo = ensureFontMeasureInfo(font);
 
     for (let i = 0; i < text.length; i++) {
 
@@ -653,7 +735,7 @@ function wrapText(
             continue;
         }
 
-        const chWidth = getWidth(ch, font);
+        const chWidth = measureCharWidth(fontMeasureInfo, ch.charCodeAt(0));
         const inWord = isBreakAll ? false : !isWordBreakChar(ch);
 
         if (!lines.length
@@ -735,12 +817,6 @@ function wrapText(
         }
     }
 
-    if (!lines.length && !line) {
-        line = text;
-        currentWord = '';
-        currentWordWidth = 0;
-    }
-
     // Append last line.
     if (currentWord) {
         line += currentWord;
@@ -761,4 +837,56 @@ function wrapText(
         lines: lines,
         linesWidths
     };
-}
+}
+
+/**
+ * @see {ElementTextConfig['autoOverflowArea']}
+ */
+export function calcInnerTextOverflowArea(
+    out: CalcInnerTextOverflowAreaOut,
+    overflowRect: DefaultTextStyle['overflowRect'],
+    baseX: number,
+    baseY: number,
+    textAlign: TextAlign,
+    textVerticalAlign: TextVerticalAlign
+): void {
+    out.baseX = baseX;
+    out.baseY = baseY;
+    out.outerWidth = out.outerHeight = null;
+
+    if (!overflowRect) {
+        return;
+    }
+
+    const textWidth = overflowRect.width * 2;
+    const textHeight = overflowRect.height * 2;
+    BoundingRect.set(
+        tmpCITCTextRect,
+        adjustTextX(baseX, textWidth, textAlign),
+        adjustTextY(baseY, textHeight, textVerticalAlign),
+        textWidth,
+        textHeight
+    );
+    // If `overflow: break` and no intersection or intersect but no enough space, we still display all text
+    // on the edge regardless of the overflow. Although that might be meaningless in production env, it is
+    // logically sound and helps in debug. Therefore we use `intersectOpt.clamp`.
+    BoundingRect.intersect(overflowRect, tmpCITCTextRect, null, tmpCITCIntersectRectOpt);
+    const outIntersectRect = tmpCITCIntersectRectOpt.outIntersectRect;
+    out.outerWidth = outIntersectRect.width;
+    out.outerHeight = outIntersectRect.height;
+    out.baseX = adjustTextX(outIntersectRect.x, outIntersectRect.width, textAlign, true);
+    out.baseY = adjustTextY(outIntersectRect.y, outIntersectRect.height, textVerticalAlign, true);
+}
+const tmpCITCTextRect = new BoundingRect(0, 0, 0, 0);
+const tmpCITCIntersectRectOpt = {outIntersectRect: {}, clamp: true} as BoundingRectIntersectOpt;
+
+export type CalcInnerTextOverflowAreaOut = {
+    // The input baseX/baseY or modified baseX/baseY, must exists.
+    baseX: number
+    baseY: number
+    // Calculated outer size based on overflowRect
+    // NaN indicates don't draw.
+    outerWidth: number | NullUndefined
+    outerHeight: number | NullUndefined
+};
+

package/src/svg-legacy/helper/ClippathManager.ts

@@ -4,7 +4,6 @@
  */
 
 import Definable from './Definable';
-import * as zrUtil from '../../core/util';
 import Displayable from '../../graphic/Displayable';
 import Path from '../../graphic/Path';
 import {path} from '../graphic';
@@ -142,13 +141,14 @@ export default class ClippathManager extends Definable {
      * @param displayable displayable element
      */
     markUsed(displayable: Displayable) {
-        // displayable.__clipPaths can only be `null`/`undefined` or an non-empty array.
-        if (displayable.__clipPaths) {
-            zrUtil.each(displayable.__clipPaths, (clipPath: PathExtended) => {
+        const clipPaths = displayable.__clipPaths;
+        if (clipPaths) {
+            for (let idx = 0; idx < clipPaths.length; idx++) {
+                const clipPath = clipPaths[idx] as PathExtended;
                 if (clipPath._dom) {
                     super.markDomUsed(clipPath._dom);
                 }
-            });
+            }
         }
     };
 

package/src/tool/color.ts

@@ -1,5 +1,5 @@
 import LRU from '../core/LRU';
-import { extend, isGradientObject, isString, map } from '../core/util';
+import { extend, isFunction, isGradientObject, isString, map } from '../core/util';
 import { GradientObject } from '../graphic/Gradient';
 
 const kCSSColorTable = {
@@ -93,7 +93,7 @@ function clampCssFloat(f: number): number {  // Clamp to float 0.0 .. 1.0.
     return f < 0 ? 0 : f > 1 ? 1 : f;
 }
 
-function parseCssInt(val: string | number): number {  // int or percentage.
+export function parseCssInt(val: string | number): number {  // int or percentage.
     let str = val as string;
     if (str.length && str.charAt(str.length - 1) === '%') {
         return clampCssByte(parseFloat(str) / 100 * 255);
@@ -101,7 +101,7 @@ function parseCssInt(val: string | number): number {  // int or percentage.
     return clampCssByte(parseInt(str, 10));
 }
 
-function parseCssFloat(val: string | number): number {  // float or percentage.
+export function parseCssFloat(val: string | number): number {  // float or percentage.
     let str = val as string;
     if (str.length && str.charAt(str.length - 1) === '%') {
         return clampCssFloat(parseFloat(str) / 100);
@@ -498,21 +498,25 @@ export const mapToColor = lerp;
 
 /**
  * @param color
- * @param h 0 ~ 360, ignore when null.
- * @param s 0 ~ 1, ignore when null.
- * @param l 0 ~ 1, ignore when null.
+ * @param h 0 ~ 360, ignore when null. If function, it takes hue as argument and returns a new hue.
+ * @param s 0 ~ 1, ignore when null. If function, it takes saturation as argument and returns a new saturation.
+ * @param l 0 ~ 1, ignore when null. If function, it takes lightness as argument and returns a new lightness.
  * @return Color string in rgba format.
  * @memberOf module:zrender/util/color
  */
-export function modifyHSL(color: string, h?: number, s?: number, l?: number): string {
+export function modifyHSL(
+    color: string,
+    h?: number | ((h: number) => number),
+    s?: number | string | ((s: number) => number),
+    l?: number | string | ((l: number) => number)
+): string {
     let colorArr = parse(color);
 
     if (color) {
         colorArr = rgba2hsla(colorArr);
-        h != null && (colorArr[0] = clampCssAngle(h));
-        s != null && (colorArr[1] = parseCssFloat(s));
-        l != null && (colorArr[2] = parseCssFloat(l));
-
+        h != null && (colorArr[0] = clampCssAngle(isFunction(h) ? h(colorArr[0]) : h));
+        s != null && (colorArr[1] = parseCssFloat(isFunction(s) ? s(colorArr[1]) : s));
+        l != null && (colorArr[2] = parseCssFloat(isFunction(l) ? l(colorArr[2]) : l));
         return stringify(hsla2rgba(colorArr), 'rgba');
     }
 }